From 85d11ec1858a81abe6b39d45bce0a4817fca297e Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Mon, 30 Dec 2024 01:05:27 +0100
Subject: [PATCH 01/33] Rework Dialog component + focus outline refactoring.

---
 biome.jsonc                                       | 6 ++++++
 src/components/containers/Dialog/Dialog.tsx       | 1 -
 src/components/containers/Panel/Panel.module.scss | 1 +
 src/layouts/util/Scroller.tsx                     | 2 +-
 4 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/biome.jsonc b/biome.jsonc
index 255afc92..fbb44450 100644
--- a/biome.jsonc
+++ b/biome.jsonc
@@ -33,6 +33,12 @@
       "style": {
         "useImportType": "off",
         "noUnusedTemplateLiteral": "off"
+      },
+      "a11y": {
+        // Putting `tabindex` on non-interactive elements is often necessary, for example for scrolling content.
+        // https://ux.stackexchange.com/questions/119952/when-is-it-wrong-to-put-tabindex-0-on-non-interactive-content
+        // https://stackoverflow.com/questions/53597209/tabindex-on-el-that-are-interactive-under-certain-conditions
+        "noNoninteractiveTabindex": "off"
       }
     }
   }
diff --git a/src/components/containers/Dialog/Dialog.tsx b/src/components/containers/Dialog/Dialog.tsx
index 95948216..03b23cea 100644
--- a/src/components/containers/Dialog/Dialog.tsx
+++ b/src/components/containers/Dialog/Dialog.tsx
@@ -17,7 +17,6 @@ import cl from './Dialog.module.scss';
 
 export { cl as DialogClassNames };
 
-
 export type ActionIconProps = ComponentProps<typeof Button> & {
   /** There must be `label` on an icon-only button, for accessibility. */
   label: Required<ComponentProps<typeof Button>>['label'],
diff --git a/src/components/containers/Panel/Panel.module.scss b/src/components/containers/Panel/Panel.module.scss
index 21b1f72b..6abd9082 100644
--- a/src/components/containers/Panel/Panel.module.scss
+++ b/src/components/containers/Panel/Panel.module.scss
@@ -9,6 +9,7 @@
   --bk-panel-border-color: #{bk.$theme-card-border-default};
   
   overflow: hidden;
+  overflow-y: auto;
   
   min-height: 4rem;
   padding: 22px 26px; // FIXME
diff --git a/src/layouts/util/Scroller.tsx b/src/layouts/util/Scroller.tsx
index 889127e1..253a1159 100644
--- a/src/layouts/util/Scroller.tsx
+++ b/src/layouts/util/Scroller.tsx
@@ -1,5 +1,5 @@
 
-import { classNames as cx } from '../../util/componentUtil.tsx';
+import { classNames as cx } from '../../util/componentUtil.ts';
 
 import cl from './Scroller.module.scss';
 

From 36562e6a67915cd6659f53792653020230b95bc9 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Mon, 30 Dec 2024 18:32:25 +0100
Subject: [PATCH 02/33] Implement new ModalProvider component (first draft).

---
 .../ModalProvider/ModalProvider.module.scss   | 37 +++++++++++++++
 .../ModalProvider/ModalProvider.stories.tsx   | 36 ++++++++++++++
 .../overlays/ModalProvider/ModalProvider.tsx  | 40 ++++++++++++++++
 .../ModalProvider/useControlledDialog.ts      | 47 +++++++++++++++++++
 4 files changed, 160 insertions(+)
 create mode 100644 src/components/overlays/ModalProvider/ModalProvider.module.scss
 create mode 100644 src/components/overlays/ModalProvider/ModalProvider.stories.tsx
 create mode 100644 src/components/overlays/ModalProvider/ModalProvider.tsx
 create mode 100644 src/components/overlays/ModalProvider/useControlledDialog.ts

diff --git a/src/components/overlays/ModalProvider/ModalProvider.module.scss b/src/components/overlays/ModalProvider/ModalProvider.module.scss
new file mode 100644
index 00000000..49e7b20d
--- /dev/null
+++ b/src/components/overlays/ModalProvider/ModalProvider.module.scss
@@ -0,0 +1,37 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+@use '../../../styling/defs.scss' as bk;
+
+@layer baklava.components {
+  .bk-modal-provider {
+    @include bk.component-base(bk-modal-provider);
+    
+    --bk-modal-provider-background-color: light-dark(#{bk.$color-neutral-700}, #{bk.$color-neutral-50});
+    --bk-modal-provider-text-color: light-dark(#{bk.$color-neutral-50}, #{bk.$color-neutral-700});
+    
+    cursor: default;
+    
+    overflow-y: auto;
+    
+    max-width: 30rem;
+    max-height: 8lh;
+    
+    margin: bk.$sizing-s;
+    padding: bk.$sizing-s;
+    border-radius: bk.$sizing-s;
+    background: var(--bk-modal-provider-background-color);
+    
+    @include bk.text-layout;
+    color: var(--bk-modal-provider-text-color);
+    @include bk.font(bk.$font-family-body);
+    font-size: bk.$font-size-m;
+    
+    @media (prefers-reduced-motion: no-preference) {
+      --transition-duration: 150ms;
+      transition:
+        opacity var(--transition-duration) ease-out;
+    }
+  }
+}
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
new file mode 100644
index 00000000..2294ae60
--- /dev/null
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -0,0 +1,36 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Button } from '../../actions/Button/Button.tsx';
+
+import { ModalProvider } from './ModalProvider.tsx';
+
+
+type ModalProviderArgs = React.ComponentProps<typeof ModalProvider>;
+type Story = StoryObj<ModalProviderArgs>;
+
+export default {
+  component: ModalProvider,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+  },
+  args: {
+  },
+  render: (args) => <ModalProvider {...args}/>,
+} satisfies Meta<ModalProviderArgs>;
+
+
+export const ModalProviderStandard: Story = {
+  args: {
+    children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
+    content: ref => <dialog open ref={ref}>Content</dialog>,
+  },
+};
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
new file mode 100644
index 00000000..c5fcb7d1
--- /dev/null
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -0,0 +1,40 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+
+import { useControlledDialog } from './useControlledDialog.ts';
+
+import cl from './ModalProvider.module.scss';
+
+
+export { cl as ModalProviderClassNames };
+
+
+export type ModalProviderProps = {
+  /** The trigger that activates the modal overlay. */
+  children: (activate: () => void) => React.ReactNode,
+  
+  /** The content to be shown in the modal overlay. */
+  content: (ref: React.RefCallback<HTMLDialogElement>) => React.ReactNode,
+};
+/**
+ * Provider around a trigger (e.g. button) to display a modal overlay on trigger activation.
+ */
+export const ModalProvider = (props: ModalProviderProps) => {
+  const { children, content } = props;
+  
+  const [active, setActive] = React.useState(false);
+  const activate = React.useCallback(() => { setActive(true); }, []);
+  const deactivate = React.useCallback(() => { setActive(false); }, []);
+  
+  const dialogRef = useControlledDialog(active, deactivate);
+  
+  return (
+    <>
+      {active && content(dialogRef)}
+      {children(activate)}
+    </>
+  );
+};
diff --git a/src/components/overlays/ModalProvider/useControlledDialog.ts b/src/components/overlays/ModalProvider/useControlledDialog.ts
new file mode 100644
index 00000000..9c3ef895
--- /dev/null
+++ b/src/components/overlays/ModalProvider/useControlledDialog.ts
@@ -0,0 +1,47 @@
+
+import * as React from 'react';
+
+
+type UseControlledDialogOptions = {
+  handleBackdropClick?: undefined | boolean,
+};
+
+type ControlledDialogProps = React.ComponentProps<'dialog'>;
+
+/**
+ * Control the activation state of the given `<dialog>` element through the given `active` boolean.
+ */
+export const useControlledDialog = (
+  active: boolean,
+  onDeactivate: () => void,
+  options?: undefined | UseControlledDialogOptions,
+) => {
+  const { handleBackdropClick = true } = options ?? {};
+  
+  const dialogRef = React.useRef<HTMLDialogElement>(null);
+  
+  React.useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) { return; }
+    
+    const isDialogOpen = dialog.matches(':modal');
+    if (active && !isDialogOpen) {
+      dialog.open = false; // Make sure the <dialog> does not already have a non-modal `open`
+      dialog.showModal();
+    } else if (!active && isDialogOpen) {
+      dialog.close();
+    }
+  }, [active]);
+  
+  const handleDialogClose = React.useCallback(() => { onDeactivate(); }, [onDeactivate]);
+  const refCallback: React.RefCallback<HTMLDialogElement> = React.useCallback((dialog: HTMLDialogElement) => {
+    dialogRef.current = dialog;
+    dialog.addEventListener('close', handleDialogClose);
+    
+    return () => {
+      dialog.removeEventListener('close', handleDialogClose);
+    };
+  }, [handleDialogClose]);
+  
+  return refCallback;
+};

From 628cde9987dc15f470808cfe769f2eb98c831193 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Mon, 30 Dec 2024 23:46:13 +0100
Subject: [PATCH 03/33] Implement useControlledDialog().

---
 src/components/actions/Button/Button.tsx      |  32 ++++--
 .../ModalProvider/ModalProvider.stories.tsx   |  12 ++-
 .../overlays/ModalProvider/ModalProvider.tsx  |  10 +-
 .../ModalProvider/useControlledDialog.ts      | 102 +++++++++++++++---
 4 files changed, 126 insertions(+), 30 deletions(-)

diff --git a/src/components/actions/Button/Button.tsx b/src/components/actions/Button/Button.tsx
index 0a70c4e0..2f048b50 100644
--- a/src/components/actions/Button/Button.tsx
+++ b/src/components/actions/Button/Button.tsx
@@ -32,9 +32,16 @@ export type ButtonProps = React.PropsWithChildren<Omit<ComponentProps<'button'>,
   /** What variant the button is, from higher prominance to lower. */
   variant?: undefined | 'primary' | 'secondary' | 'tertiary',
   
+  /**
+   * Whether the button is disabled. This is meant for essentially permanent disabled buttons, not for buttons that
+   * are just temporarily non-interactive. Use `nonactive` for the latter. Disabled buttons cannot be focused.
+   */
+  disabled?: undefined | boolean,
+  
   /**
    * Whether the button is in "nonactive" state. This is a variant of `disabled`, but instead of completely graying
-   * out the button, it only becomes a muted variation of the button's appearance. When true, also implies `disabled`.
+   * out the button, it only becomes a muted variation of the button's appearance. Nonactive buttons are useful for
+   * temporarily states such as while an action is currently ongoing. Nonactive buttons are still focusable.
    */
   nonactive?: undefined | boolean,
   
@@ -53,6 +60,7 @@ export const Button = (props: ButtonProps) => {
     unstyled = false,
     trimmed = false,
     label,
+    disabled = false,
     nonactive = false,
     variant = 'tertiary',
     onPress,
@@ -63,24 +71,31 @@ export const Button = (props: ButtonProps) => {
   const [isPressPending, startPressTransition] = React.useTransition();
   
   const isPending = isPressPending;
-  const isInteractive = !propsRest.disabled && !nonactive && !isPending;
+  const isInteractive = !disabled && !nonactive && !isPending;
   const isNonactive = nonactive || isPending;
   
   const handlePress = React.useCallback(() => {
     if (typeof onPress !== 'function') { return; }
     
-    startPressTransition(async () => {
-      await Promise.race([onPress(), timeout(asyncTimeout)]);
-    });
+    const onPressResult = onPress();
+    
+    // Note: do not start a transition unless `onPress` is actually async, because otherwise sync press actions
+    // will cause a brief rerender with disabled state and loading indicator, which messes with things like
+    // button focus.
+    if (onPressResult instanceof Promise) {
+      startPressTransition(async () => {
+        await Promise.race([onPressResult, timeout(asyncTimeout)]);
+      });
+    }
   }, [onPress, asyncTimeout]);
   
   const handleClick = React.useCallback(async (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+    if (!isInteractive) { return; }
+    
     // `onClick` should not be used in most cases, only if the consumer needs low level control over click events.
     // Instead, use `onPress` or a `<form>` component with `action`.
     props.onClick?.(event); // Call this first, to allow cancellation
     
-    if (!isInteractive) { return; }
-    
     if (typeof onPress === 'function') {
       event.preventDefault();
       handlePress();
@@ -122,9 +137,10 @@ export const Button = (props: ButtonProps) => {
   return (
     <button
       aria-label={accessibleName}
+      aria-disabled={!isInteractive}
+      disabled={disabled}
       {...propsRest}
       type={buttonType} // Not overridable
-      disabled={!isInteractive}
       className={cx({
         bk: true,
         [cl['bk-button']]: !unstyled,
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index 2294ae60..14c2db62 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -5,8 +5,10 @@
 import * as React from 'react';
 
 import type { Meta, StoryObj } from '@storybook/react';
+import { LoremIpsum } from '../../../util/storybook/LoremIpsum.tsx';
 
 import { Button } from '../../actions/Button/Button.tsx';
+import { Dialog } from '../../containers/Dialog/Dialog.tsx';
 
 import { ModalProvider } from './ModalProvider.tsx';
 
@@ -31,6 +33,14 @@ export default {
 export const ModalProviderStandard: Story = {
   args: {
     children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
-    content: ref => <dialog open ref={ref}>Content</dialog>,
+    content: ({ close, ...props }) =>
+      <Dialog {...props} onCloseAction={close}><LoremIpsum paragraphs={5}/></Dialog>,
+  },
+};
+
+export const ModalProviderWithBasicDialog: Story = {
+  args: {
+    children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
+    content: props => <dialog {...props}>Content</dialog>,
   },
 };
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index c5fcb7d1..c17f7047 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -4,7 +4,7 @@
 
 import * as React from 'react';
 
-import { useControlledDialog } from './useControlledDialog.ts';
+import { useControlledDialog, type ControlledDialogProps } from './useControlledDialog.ts';
 
 import cl from './ModalProvider.module.scss';
 
@@ -17,7 +17,7 @@ export type ModalProviderProps = {
   children: (activate: () => void) => React.ReactNode,
   
   /** The content to be shown in the modal overlay. */
-  content: (ref: React.RefCallback<HTMLDialogElement>) => React.ReactNode,
+  content: (props: ControlledDialogProps) => React.ReactNode,
 };
 /**
  * Provider around a trigger (e.g. button) to display a modal overlay on trigger activation.
@@ -29,11 +29,13 @@ export const ModalProvider = (props: ModalProviderProps) => {
   const activate = React.useCallback(() => { setActive(true); }, []);
   const deactivate = React.useCallback(() => { setActive(false); }, []);
   
-  const dialogRef = useControlledDialog(active, deactivate);
+  const dialogProps = useControlledDialog(active, deactivate, {
+    allowUserClose: true,
+  });
   
   return (
     <>
-      {active && content(dialogRef)}
+      {active && content(dialogProps)}
       {children(activate)}
     </>
   );
diff --git a/src/components/overlays/ModalProvider/useControlledDialog.ts b/src/components/overlays/ModalProvider/useControlledDialog.ts
index 9c3ef895..a98849b3 100644
--- a/src/components/overlays/ModalProvider/useControlledDialog.ts
+++ b/src/components/overlays/ModalProvider/useControlledDialog.ts
@@ -2,11 +2,20 @@
 import * as React from 'react';
 
 
-type UseControlledDialogOptions = {
-  handleBackdropClick?: undefined | boolean,
+export type UseControlledDialogOptions = {
+  /**
+   * Whether to allow the user to close the modal through the browser (e.g. with the Escape key). Disabling this may
+   * be useful in cases where we need the user to stay in the modal (e.g. pending confirmation, pending form submit).
+   */
+  allowUserClose?: undefined | boolean,
+  
+  /** Whether the user clicking the backdrop should close the modal. */
+  shouldCloseOnBackdropClick?: undefined | boolean,
 };
 
-type ControlledDialogProps = React.ComponentProps<'dialog'>;
+export type ControlledDialogProps = React.ComponentProps<'dialog'> & {
+  close: () => void,
+};
 
 /**
  * Control the activation state of the given `<dialog>` element through the given `active` boolean.
@@ -15,33 +24,92 @@ export const useControlledDialog = (
   active: boolean,
   onDeactivate: () => void,
   options?: undefined | UseControlledDialogOptions,
-) => {
-  const { handleBackdropClick = true } = options ?? {};
+): ControlledDialogProps => {
+  const {
+    allowUserClose = true,
+    shouldCloseOnBackdropClick = true,
+  } = options ?? {};
   
   const dialogRef = React.useRef<HTMLDialogElement>(null);
+  //const lastActiveElementRef = React.useRef<Element>(null);
   
+  // Sync active state with <dialog> DOM state
   React.useEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog) { return; }
     
     const isDialogOpen = dialog.matches(':modal');
     if (active && !isDialogOpen) {
-      dialog.open = false; // Make sure the <dialog> does not already have a non-modal `open`
-      dialog.showModal();
+      // Save a reference to the last focused element before opening the modal
+      //lastActiveElementRef.current = document.activeElement;
+      
+      try {
+        dialog.open = false; // Make sure the <dialog> does not already have a non-modal `open`
+        dialog.showModal();
+      } catch (error: unknown) {
+        console.error(`Unable to open modal dialog`, error);
+        onDeactivate();
+      }
     } else if (!active && isDialogOpen) {
       dialog.close();
     }
-  }, [active]);
+  }, [active, onDeactivate]);
+  
+  // Handle dialog `close` event
+  const handleDialogClose = React.useCallback(() => {
+    /*
+    // XXX This is probably not necessary, browsers do this out of the box already
+    // Restore focus to last active element before the user opened the modal
+    const lastActiveElement = lastActiveElementRef.current;
+    if (lastActiveElement && 'focus' in lastActiveElement && typeof lastActiveElement.focus === 'function') {
+      lastActiveElement.focus();
+    }
+    */
+    
+    onDeactivate(); // Sync with the consumer
+  }, [onDeactivate]);
+  
+  const handleDialogClick = React.useCallback((event: React.MouseEvent<HTMLDialogElement>) => {
+    const dialog: HTMLDialogElement = event.currentTarget;
+    const target: EventTarget = event.target;
+    
+    // We want to determine whether the click was on the `<dialog>` backdrop. For the event, the backdrop is considered
+    // just a part of the `<dialog>` element. So we need to check both that the target is the `<dialog>` *and also*
+    // that the click landed outside of the element content boundary.
+    // Source: https://stackoverflow.com/questions/25864259/how-to-close-dialog-tag-by-clicking-on-its-backdrop
+    let isClickOnBackdrop = false;
+    if (target === dialog) {
+      const rect = dialog.getBoundingClientRect();
+      const isInsideDialog = rect.top <= event.clientY
+        && event.clientY <= rect.top + rect.height
+        && rect.left <= event.clientX
+        && event.clientX <= rect.left + rect.width;
+      isClickOnBackdrop = !isInsideDialog;
+    }
+    
+    if (allowUserClose && shouldCloseOnBackdropClick && isClickOnBackdrop) {
+      dialog.close();
+    }
+  }, [allowUserClose, shouldCloseOnBackdropClick]);
   
-  const handleDialogClose = React.useCallback(() => { onDeactivate(); }, [onDeactivate]);
-  const refCallback: React.RefCallback<HTMLDialogElement> = React.useCallback((dialog: HTMLDialogElement) => {
-    dialogRef.current = dialog;
-    dialog.addEventListener('close', handleDialogClose);
+  const handleDialogKeyDown = React.useCallback((event: React.KeyboardEvent<HTMLDialogElement>) => {
+    if (event.key === 'Escape' && !allowUserClose) {
+      event.preventDefault();
+    }
+  }, [allowUserClose]);
+  
+  const dialogProps: ControlledDialogProps = {
+    ref: dialogRef,
+    open: undefined, // Leave the `open` attribute to the browser to manage
+    
+    onClose: handleDialogClose,
+    // Note: we don't need keyboard accessibility for this `onClick`, the backdrop is not (and should not be) an
+    // interactive element. This is a visual only convenience, screen readers should use the other close mechanisms.
+    onClick: shouldCloseOnBackdropClick ? handleDialogClick : undefined,
+    onKeyDown: handleDialogKeyDown,
     
-    return () => {
-      dialog.removeEventListener('close', handleDialogClose);
-    };
-  }, [handleDialogClose]);
+    close: () => { dialogRef.current?.close(); },
+  };
   
-  return refCallback;
+  return dialogProps;
 };

From 21ec9bd21767b98084a985577561690cb6cfe3b2 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Tue, 31 Dec 2024 14:40:24 +0100
Subject: [PATCH 04/33] Refactor useControlledDialog().

---
 .../ModalProvider/ModalProvider.stories.tsx   |  8 +--
 .../overlays/ModalProvider/ModalProvider.tsx  | 12 ++--
 .../ModalProvider/useControlledDialog.ts      | 67 ++++++++++++-------
 3 files changed, 54 insertions(+), 33 deletions(-)

diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index 14c2db62..ba66cfd9 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -17,11 +17,11 @@ type ModalProviderArgs = React.ComponentProps<typeof ModalProvider>;
 type Story = StoryObj<ModalProviderArgs>;
 
 export default {
+  tags: ['autodocs'],
   component: ModalProvider,
   parameters: {
     layout: 'fullscreen',
   },
-  tags: ['autodocs'],
   argTypes: {
   },
   args: {
@@ -33,14 +33,14 @@ export default {
 export const ModalProviderStandard: Story = {
   args: {
     children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
-    content: ({ close, ...props }) =>
-      <Dialog {...props} onCloseAction={close}><LoremIpsum paragraphs={5}/></Dialog>,
+    content: ({ close, dialogProps }) =>
+      <Dialog {...dialogProps} onCloseAction={close}><LoremIpsum paragraphs={5}/></Dialog>,
   },
 };
 
 export const ModalProviderWithBasicDialog: Story = {
   args: {
     children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
-    content: props => <dialog {...props}>Content</dialog>,
+    content: ({ close, dialogProps }) => <dialog {...dialogProps}>Content</dialog>,
   },
 };
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index c17f7047..3f50c5e2 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -18,18 +18,22 @@ export type ModalProviderProps = {
   
   /** The content to be shown in the modal overlay. */
   content: (props: ControlledDialogProps) => React.ReactNode,
+  
+  /** Whether the modal should be active by default. */
+  activeDefault?: undefined | boolean,
 };
 /**
  * Provider around a trigger (e.g. button) to display a modal overlay on trigger activation.
  */
 export const ModalProvider = (props: ModalProviderProps) => {
-  const { children, content } = props;
+  const { children, content, activeDefault = false } = props;
   
-  const [active, setActive] = React.useState(false);
+  const [active, setActive] = React.useState(activeDefault);
   const activate = React.useCallback(() => { setActive(true); }, []);
-  const deactivate = React.useCallback(() => { setActive(false); }, []);
   
-  const dialogProps = useControlledDialog(active, deactivate, {
+  const dialogProps = useControlledDialog({
+    active,
+    onActiveStateChange: setActive,
     allowUserClose: true,
   });
   
diff --git a/src/components/overlays/ModalProvider/useControlledDialog.ts b/src/components/overlays/ModalProvider/useControlledDialog.ts
index a98849b3..bb625f09 100644
--- a/src/components/overlays/ModalProvider/useControlledDialog.ts
+++ b/src/components/overlays/ModalProvider/useControlledDialog.ts
@@ -2,7 +2,13 @@
 import * as React from 'react';
 
 
-export type UseControlledDialogOptions = {
+export type UseControlledDialogArgs = {
+  /** Whether the dialog is currently active. */
+  active: boolean,
+  
+  /** A callback that will be called when the dialog changes active state. */
+  onActiveStateChange: (active: boolean) => void,
+  
   /**
    * Whether to allow the user to close the modal through the browser (e.g. with the Escape key). Disabling this may
    * be useful in cases where we need the user to stay in the modal (e.g. pending confirmation, pending form submit).
@@ -13,26 +19,36 @@ export type UseControlledDialogOptions = {
   shouldCloseOnBackdropClick?: undefined | boolean,
 };
 
-export type ControlledDialogProps = React.ComponentProps<'dialog'> & {
+export type ControlledDialogProps = {
   close: () => void,
+  dialogProps: React.ComponentProps<'dialog'>,
 };
 
 /**
  * Control the activation state of the given `<dialog>` element through the given `active` boolean.
  */
-export const useControlledDialog = (
-  active: boolean,
-  onDeactivate: () => void,
-  options?: undefined | UseControlledDialogOptions,
-): ControlledDialogProps => {
+export const useControlledDialog = (args: UseControlledDialogArgs): ControlledDialogProps => {
   const {
+    active,
+    onActiveStateChange,
     allowUserClose = true,
     shouldCloseOnBackdropClick = true,
-  } = options ?? {};
+  } = args;
   
   const dialogRef = React.useRef<HTMLDialogElement>(null);
   //const lastActiveElementRef = React.useRef<Element>(null);
   
+  const requestDialogClose = React.useCallback(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) { console.warn(`Unable to close dialog: reference does not exist.`); return; }
+    
+    try {
+      dialog.close();
+    } catch (error: unknown) {
+      console.error(`Failed to close dialog`, error);
+    }
+  }, []);
+  
   // Sync active state with <dialog> DOM state
   React.useEffect(() => {
     const dialog = dialogRef.current;
@@ -48,12 +64,12 @@ export const useControlledDialog = (
         dialog.showModal();
       } catch (error: unknown) {
         console.error(`Unable to open modal dialog`, error);
-        onDeactivate();
+        onActiveStateChange(false);
       }
     } else if (!active && isDialogOpen) {
       dialog.close();
     }
-  }, [active, onDeactivate]);
+  }, [active, onActiveStateChange]);
   
   // Handle dialog `close` event
   const handleDialogClose = React.useCallback(() => {
@@ -66,9 +82,10 @@ export const useControlledDialog = (
     }
     */
     
-    onDeactivate(); // Sync with the consumer
-  }, [onDeactivate]);
+    onActiveStateChange(false); // Sync with the consumer
+  }, [onActiveStateChange]);
   
+  // Handle dialog `click` event
   const handleDialogClick = React.useCallback((event: React.MouseEvent<HTMLDialogElement>) => {
     const dialog: HTMLDialogElement = event.currentTarget;
     const target: EventTarget = event.target;
@@ -92,24 +109,24 @@ export const useControlledDialog = (
     }
   }, [allowUserClose, shouldCloseOnBackdropClick]);
   
+  // Handle dialog `keydown` event
   const handleDialogKeyDown = React.useCallback((event: React.KeyboardEvent<HTMLDialogElement>) => {
     if (event.key === 'Escape' && !allowUserClose) {
       event.preventDefault();
     }
   }, [allowUserClose]);
   
-  const dialogProps: ControlledDialogProps = {
-    ref: dialogRef,
-    open: undefined, // Leave the `open` attribute to the browser to manage
-    
-    onClose: handleDialogClose,
-    // Note: we don't need keyboard accessibility for this `onClick`, the backdrop is not (and should not be) an
-    // interactive element. This is a visual only convenience, screen readers should use the other close mechanisms.
-    onClick: shouldCloseOnBackdropClick ? handleDialogClick : undefined,
-    onKeyDown: handleDialogKeyDown,
-    
-    close: () => { dialogRef.current?.close(); },
+  return {
+    close: requestDialogClose,
+    dialogProps: {
+      ref: dialogRef,
+      open: undefined, // Leave the `open` attribute to the browser to manage
+      
+      onClose: handleDialogClose,
+      // Note: we don't need keyboard accessibility for this `onClick`, the backdrop is not (and should not be) an
+      // interactive element. This is a visual only convenience, screen readers should use the other close mechanisms.
+      onClick: shouldCloseOnBackdropClick ? handleDialogClick : undefined,
+      onKeyDown: handleDialogKeyDown,
+    },
   };
-  
-  return dialogProps;
 };

From e9de2dfbae7431d1c86c38fb4a8aa25b4383cabb Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Tue, 31 Dec 2024 19:37:41 +0100
Subject: [PATCH 05/33] Update ModalProvider.

---
 .../overlays/ModalProvider/ModalProvider.module.scss        | 2 --
 .../overlays/ModalProvider/ModalProvider.stories.tsx        | 6 +++---
 src/components/overlays/ModalProvider/ModalProvider.tsx     | 6 ++++--
 .../overlays/ModalProvider/useControlledDialog.ts           | 3 +++
 4 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/components/overlays/ModalProvider/ModalProvider.module.scss b/src/components/overlays/ModalProvider/ModalProvider.module.scss
index 49e7b20d..1991d481 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.module.scss
+++ b/src/components/overlays/ModalProvider/ModalProvider.module.scss
@@ -13,8 +13,6 @@
     
     cursor: default;
     
-    overflow-y: auto;
-    
     max-width: 30rem;
     max-height: 8lh;
     
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index ba66cfd9..55e1795e 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -32,15 +32,15 @@ export default {
 
 export const ModalProviderStandard: Story = {
   args: {
-    children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
+    children: ({ activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
     content: ({ close, dialogProps }) =>
-      <Dialog {...dialogProps} onCloseAction={close}><LoremIpsum paragraphs={5}/></Dialog>,
+      <Dialog {...dialogProps} title="Modal dialog" onRequestClose={close}><LoremIpsum paragraphs={5}/></Dialog>,
   },
 };
 
 export const ModalProviderWithBasicDialog: Story = {
   args: {
-    children: activate => <Button variant="primary" label="Open modal" onPress={activate}/>,
+    children: ({ activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
     content: ({ close, dialogProps }) => <dialog {...dialogProps}>Content</dialog>,
   },
 };
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index 3f50c5e2..a1e3e97f 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -14,7 +14,7 @@ export { cl as ModalProviderClassNames };
 
 export type ModalProviderProps = {
   /** The trigger that activates the modal overlay. */
-  children: (activate: () => void) => React.ReactNode,
+  children: (triggerProps: { active: boolean, activate: () => void }) => React.ReactNode,
   
   /** The content to be shown in the modal overlay. */
   content: (props: ControlledDialogProps) => React.ReactNode,
@@ -31,6 +31,8 @@ export const ModalProvider = (props: ModalProviderProps) => {
   const [active, setActive] = React.useState(activeDefault);
   const activate = React.useCallback(() => { setActive(true); }, []);
   
+  const triggerProps = { active, activate };
+  
   const dialogProps = useControlledDialog({
     active,
     onActiveStateChange: setActive,
@@ -40,7 +42,7 @@ export const ModalProvider = (props: ModalProviderProps) => {
   return (
     <>
       {active && content(dialogProps)}
-      {children(activate)}
+      {children(triggerProps)}
     </>
   );
 };
diff --git a/src/components/overlays/ModalProvider/useControlledDialog.ts b/src/components/overlays/ModalProvider/useControlledDialog.ts
index bb625f09..3ecd165b 100644
--- a/src/components/overlays/ModalProvider/useControlledDialog.ts
+++ b/src/components/overlays/ModalProvider/useControlledDialog.ts
@@ -1,3 +1,6 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import * as React from 'react';
 

From c4d208cad50ccdb147eb2be1575040d201d60b2c Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Tue, 31 Dec 2024 19:43:10 +0100
Subject: [PATCH 06/33] Tweak plopfile.

---
 plopfile.ts | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/plopfile.ts b/plopfile.ts
index 67fa7e80..3c5d12ee 100644
--- a/plopfile.ts
+++ b/plopfile.ts
@@ -64,7 +64,7 @@ const componentTemplate = {
       /** Whether this component should be unstyled. */
       unstyled?: undefined | boolean,
       
-      /** Some property specific to \`{{{component-name}}}\` */
+      /** Some property specific to \`{{{component-name}}}\`. */
       variant?: undefined | 'x' | 'y',
     }>;
     {{"\\n"~}}
@@ -173,12 +173,11 @@ const componentTemplate = {
     
     export default {
       component: {{{component-name}}},
+      tags: ['autodocs'],
       parameters: {
         layout: '{{storybook-layout}}',
       },
-      tags: ['autodocs'],
-      argTypes: {
-      },
+      argTypes: {},
       args: {
         children: 'Example',
       },
@@ -186,8 +185,12 @@ const componentTemplate = {
     } satisfies Meta<{{{component-name}}}Args>;
     
     
-    export const Standard: Story = {
-      name: '{{{component-name}}}',
+    export const {{{component-name}}}Standard: Story = {};
+    
+    export const {{{component-name}}}WithVariant: Story = {
+      args: {
+        variant: 'x',
+      },
     };
   ` + '\n',
 };

From 71d4127b62bdc79046a818fa8869a9d820e109ba Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Tue, 31 Dec 2024 19:43:26 +0100
Subject: [PATCH 07/33] New component: DialogModal.

---
 .../DialogModal/DialogModal.module.scss       | 28 +++++++++
 .../DialogModal/DialogModal.stories.tsx       | 46 +++++++++++++++
 .../overlays/DialogModal/DialogModal.tsx      | 59 +++++++++++++++++++
 3 files changed, 133 insertions(+)
 create mode 100644 src/components/overlays/DialogModal/DialogModal.module.scss
 create mode 100644 src/components/overlays/DialogModal/DialogModal.stories.tsx
 create mode 100644 src/components/overlays/DialogModal/DialogModal.tsx

diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
new file mode 100644
index 00000000..d59c67e8
--- /dev/null
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -0,0 +1,28 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+@use '../../../styling/defs.scss' as bk;
+
+@layer baklava.components {
+  .bk-dialog-modal {
+    @include bk.component-base(bk-dialog-modal);
+    
+    &.bk-dialog-modal--full-screen {
+      // FIXME: test this on mobile for potential overflow/shifting. May need to use `dvh`/`dvw` instead?
+      inset: 0;
+      margin: 0;
+      width: auto;
+      height: auto;
+    }
+    
+    &.bk-dialog-modal--slide-over {
+      inset: 0;
+      margin: 0;
+      width: auto;
+      height: auto;
+      
+      margin-inline-start: 20vw;
+    }
+  }
+}
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
new file mode 100644
index 00000000..ef89b6e1
--- /dev/null
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -0,0 +1,46 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { DialogModal } from './DialogModal.tsx';
+
+
+type DialogModalArgs = React.ComponentProps<typeof DialogModal>;
+type Story = StoryObj<DialogModalArgs>;
+
+export default {
+  component: DialogModal,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+  },
+  argTypes: {},
+  args: {
+    title: 'Modal dialog',
+  },
+  render: (args) => <DialogModal {...args}/>,
+} satisfies Meta<DialogModalArgs>;
+
+
+export const DialogModalStandard: Story = {
+};
+
+export const DialogModalFullScreen: Story = {
+  args: {
+    display: 'full-screen',
+    title: 'Full screen modal dialog',
+    showCloseAction: true,
+  },
+};
+
+export const DialogModalSlideOver: Story = {
+  args: {
+    display: 'slide-over',
+    title: 'Slide over modal dialog',
+    showCloseAction: true,
+  },
+};
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
new file mode 100644
index 00000000..adac45be
--- /dev/null
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -0,0 +1,59 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+import { classNames as cx, type ComponentProps } from '../../../util/componentUtil.ts';
+
+import { Button } from '../../actions/Button/Button.tsx';
+import { Dialog } from '../../containers/Dialog/Dialog.tsx';
+import { ModalProvider, type ModalProviderProps } from '../ModalProvider/ModalProvider.tsx';
+
+import cl from './DialogModal.module.scss';
+
+
+export { cl as DialogModalClassNames };
+
+export type DialogModalProps = ComponentProps<typeof Dialog> & {
+  /** Whether this component should be unstyled. */
+  unstyled?: undefined | boolean,
+  
+  /** How to display the modal in the viewport. Default: 'center'. */
+  display?: undefined | 'center' | 'full-screen' | 'slide-over',
+  
+  trigger: ModalProviderProps['children'],
+  
+  providerProps?: undefined | Omit<ModalProviderProps, 'children'>,
+};
+/**
+ * A dialog component displayed as a modal when activating the given trigger.
+ */
+export const DialogModal = (props: DialogModalProps) => {
+  const { unstyled = false, display = 'center', ...propsRest } = props;
+  
+  return (
+    <ModalProvider
+      content={({ close, dialogProps }) =>
+        <Dialog
+          flat={['full-screen', 'slide-over'].includes(display)}
+          {...dialogProps}
+          onRequestClose={close}
+          {...propsRest}
+          className={cx(
+            { bk: true },
+            { [cl['bk-dialog-modal']]: !unstyled },
+            { [cl['bk-dialog-modal--center']]: display === 'center' },
+            { [cl['bk-dialog-modal--full-screen']]: display === 'full-screen' },
+            { [cl['bk-dialog-modal--slide-over']]: display === 'slide-over' },
+            dialogProps.className,
+            propsRest.className,
+          )}
+        />
+      }
+    >
+      {({ active, activate }) =>
+        <Button variant="primary" label="Open modal" onPress={activate}/>
+      }
+    </ModalProvider>
+  );
+};

From a40a83754a929fdf3b0ff60cbd362f0ee7ac958b Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Thu, 2 Jan 2025 00:51:57 +0100
Subject: [PATCH 08/33] Update DialogModal transitions.

---
 .../DialogModal/DialogModal.module.scss       | 70 +++++++++++++++++++
 .../DialogModal/DialogModal.stories.tsx       |  3 +
 .../overlays/DialogModal/DialogModal.tsx      | 21 ++++--
 3 files changed, 89 insertions(+), 5 deletions(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index d59c67e8..67ecb853 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -4,10 +4,80 @@
 
 @use '../../../styling/defs.scss' as bk;
 
+@mixin dialog-entry-exit($entry-dur: 200ms, $exit-dur: 180ms) {
+  transition-property: overlay, display, opacity, scale;
+  transition-behavior: allow-discrete;
+  transition-duration: $exit-dur; // Exit
+  transition-timing-function: ease-out; // Exit
+  
+  // Open state styling
+  opacity: 1;
+  scale: 1;
+  
+  // Entry transition styling
+  @starting-style {
+    transition-duration: $entry-dur;
+    transition-timing-function: ease-in;
+    opacity: 0;
+    scale: 1.1;
+  }
+  
+  // Exit transition styling
+  &:not([open]) {
+    opacity: 0;
+    scale: 0.98;
+  }
+  
+  
+  $blur: 2px; // Should be in px, not rem (blur effect should be constant)
+  &::backdrop {
+    transition-property: overlay, display, background-color, backdrop-filter;
+    transition-behavior: allow-discrete;
+    transition-duration: $exit-dur; // Exit
+    transition-timing-function: ease-out; // Exit
+    
+    // Open state styling
+    background-color: light-dark(rgb(0 0 0 / 10%), rgb(0 0 0 / 20%));
+    backdrop-filter: blur($blur) opacity(1);
+    
+    // Entry transition styling
+    @starting-style {
+      transition-duration: $entry-dur;
+      transition-timing-function: ease-in;
+      background-color: transparent;
+      backdrop-filter: blur($blur) opacity(0);
+    }
+  }
+  // Exit transition styling
+  // Note: cannot nest the following inside `::backdrop`, since `:not()` needs to apply to the dialog not `::backdrop`
+  &:not([open])::backdrop {
+    background-color: transparent;
+    backdrop-filter: blur($blur) opacity(0);
+  }
+}
+
 @layer baklava.components {
   .bk-dialog-modal {
     @include bk.component-base(bk-dialog-modal);
     
+    // Basic modal positioning
+    position: fixed;
+    inset: 0;
+    
+    // Entry and exit animations
+    @include dialog-entry-exit;
+    
+    
+    //
+    // Display variants
+    //
+    
+    &.bk-dialog-modal--center {
+      margin: auto;
+      width: fit-content;
+      height: fit-content;
+    }
+    
     &.bk-dialog-modal--full-screen {
       // FIXME: test this on mobile for potential overflow/shifting. May need to use `dvh`/`dvw` instead?
       inset: 0;
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index ef89b6e1..6fed7c76 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -6,6 +6,8 @@ import * as React from 'react';
 
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { Button } from '../../actions/Button/Button.tsx';
+
 import { DialogModal } from './DialogModal.tsx';
 
 
@@ -21,6 +23,7 @@ export default {
   argTypes: {},
   args: {
     title: 'Modal dialog',
+    trigger: ({ active, activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
   },
   render: (args) => <DialogModal {...args}/>,
 } satisfies Meta<DialogModalArgs>;
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index adac45be..81dddf04 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -21,15 +21,26 @@ export type DialogModalProps = ComponentProps<typeof Dialog> & {
   /** How to display the modal in the viewport. Default: 'center'. */
   display?: undefined | 'center' | 'full-screen' | 'slide-over',
   
+  /** The size of the modal. Applies to modals with `display="center"`. */
+  size?: undefined | 'small' | 'medium' | 'large',
+  
+  /** The modal trigger. */
   trigger: ModalProviderProps['children'],
   
+  /** Any additional props to pass to the modal provider. */
   providerProps?: undefined | Omit<ModalProviderProps, 'children'>,
 };
 /**
  * A dialog component displayed as a modal when activating the given trigger.
  */
 export const DialogModal = (props: DialogModalProps) => {
-  const { unstyled = false, display = 'center', ...propsRest } = props;
+  const {
+    children,
+    trigger,
+    unstyled = false,
+    display = 'center',
+    ...propsRest
+  } = props;
   
   return (
     <ModalProvider
@@ -48,12 +59,12 @@ export const DialogModal = (props: DialogModalProps) => {
             dialogProps.className,
             propsRest.className,
           )}
-        />
+        >
+          {children}
+        </Dialog>
       }
     >
-      {({ active, activate }) =>
-        <Button variant="primary" label="Open modal" onPress={activate}/>
-      }
+      {trigger}
     </ModalProvider>
   );
 };

From a94260eb4235e1436012b1fb7bd3fbd9aa20c3bf Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Thu, 2 Jan 2025 20:38:59 +0100
Subject: [PATCH 09/33] Work on DialogModal.

---
 .../DialogModal/DialogModal.module.scss       | 127 +++++++++++++-----
 .../DialogModal/DialogModal.stories.tsx       |  15 ++-
 .../overlays/DialogModal/DialogModal.tsx      |   6 +-
 .../overlays/ModalProvider/ModalProvider.tsx  |  25 +++-
 .../Dialog}/useControlledDialog.ts            |   0
 src/util/hooks/useDebounce.ts                 |  36 +++++
 6 files changed, 171 insertions(+), 38 deletions(-)
 rename src/components/{overlays/ModalProvider => util/Dialog}/useControlledDialog.ts (100%)
 create mode 100644 src/util/hooks/useDebounce.ts

diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index 67ecb853..8faefb40 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -4,68 +4,99 @@
 
 @use '../../../styling/defs.scss' as bk;
 
-@mixin dialog-entry-exit($entry-dur: 200ms, $exit-dur: 180ms) {
+// Note: `$blur` should be in px, not rem (blur effect should be independent of any font size scaling)
+@mixin dialog-backdrop($entry-dur: 200ms, $exit-dur: 180ms, $blur: 2px) {
+  &::backdrop {
+    transition-property: overlay, display, background-color, backdrop-filter;
+    transition-timing-function: linear;
+    transition-behavior: allow-discrete;
+    
+    // Open state styling
+    background-color: light-dark(rgb(0 0 0 / 10%), rgb(0 0 0 / 20%));
+    backdrop-filter: blur($blur) opacity(1);
+    
+    // Entry transition styling
+    transition-duration: $entry-dur;
+    @starting-style {
+      background-color: transparent;
+      backdrop-filter: blur($blur) opacity(0);
+    }
+  }
+  // Exit transition styling
+  // Note: cannot nest the following inside `::backdrop`, since `:not()` needs to apply to the dialog not `::backdrop`
+  &:not([open])::backdrop {
+    transition-duration: $exit-dur;
+    background-color: transparent;
+    backdrop-filter: blur($blur) opacity(0);
+  }
+}
+
+@mixin dialog-fade-in($entry-dur: 200ms, $exit-dur: 180ms, $scale: 1) {
   transition-property: overlay, display, opacity, scale;
+  transition-timing-function: ease-out;
   transition-behavior: allow-discrete;
-  transition-duration: $exit-dur; // Exit
-  transition-timing-function: ease-out; // Exit
   
   // Open state styling
   opacity: 1;
   scale: 1;
   
   // Entry transition styling
+  transition-duration: $entry-dur;
   @starting-style {
-    transition-duration: $entry-dur;
-    transition-timing-function: ease-in;
     opacity: 0;
-    scale: 1.1;
+    scale: $scale;
   }
   
   // Exit transition styling
   &:not([open]) {
+    transition-duration: $exit-dur;
+    transition-timing-function: ease-in;
     opacity: 0;
-    scale: 0.98;
+    scale: calc(1 - (($scale - 1) * 0.2)); // Multiply by 0.2 to make the scale out effect a bit more subtle
   }
+}
+
+@mixin dialog-slide-over($entry-dur: 200ms, $exit-dur: 180ms) {
+  transition-property: overlay, display, translate;
+  transition-timing-function: ease-out;
+  transition-behavior: allow-discrete;
   
+  // Open state styling
+  translate: 0;
   
-  $blur: 2px; // Should be in px, not rem (blur effect should be constant)
-  &::backdrop {
-    transition-property: overlay, display, background-color, backdrop-filter;
-    transition-behavior: allow-discrete;
-    transition-duration: $exit-dur; // Exit
-    transition-timing-function: ease-out; // Exit
-    
-    // Open state styling
-    background-color: light-dark(rgb(0 0 0 / 10%), rgb(0 0 0 / 20%));
-    backdrop-filter: blur($blur) opacity(1);
-    
-    // Entry transition styling
-    @starting-style {
-      transition-duration: $entry-dur;
-      transition-timing-function: ease-in;
-      background-color: transparent;
-      backdrop-filter: blur($blur) opacity(0);
-    }
+  // Entry transition styling
+  transition-duration: $entry-dur;
+  @starting-style {
+    translate: 80vw 0;
   }
+  
   // Exit transition styling
-  // Note: cannot nest the following inside `::backdrop`, since `:not()` needs to apply to the dialog not `::backdrop`
-  &:not([open])::backdrop {
-    background-color: transparent;
-    backdrop-filter: blur($blur) opacity(0);
+  &:not([open]) {
+    transition-duration: $exit-dur;
+    transition-timing-function: ease-in;
+    translate: 80vw 0;
   }
 }
 
+
 @layer baklava.components {
   .bk-dialog-modal {
     @include bk.component-base(bk-dialog-modal);
     
+    --bk-dialog-modal-entry-dur: 200ms;
+    --bk-dialog-modal-exit-dur: 180ms;
+    --bk-dialog-modal-fade-scale: 1;
+    
     // Basic modal positioning
     position: fixed;
     inset: 0;
+    max-width: 100vw;
+    max-height: 100vh;
     
-    // Entry and exit animations
-    @include dialog-entry-exit;
+    @include dialog-backdrop(
+      $entry-dur: var(--bk-dialog-modal-entry-dur),
+      $exit-dur: var(--bk-dialog-modal-exit-dur),
+    );
     
     
     //
@@ -76,6 +107,26 @@
       margin: auto;
       width: fit-content;
       height: fit-content;
+      
+      @include dialog-fade-in(
+        $entry-dur: var(--bk-dialog-modal-entry-dur),
+        $exit-dur: var(--bk-dialog-modal-exit-dur),
+        $scale: var(--bk-dialog-modal-fade-scale),
+      );
+      
+      max-height: calc(100vh - 5vw); // The larger the viewport width, the more breathing room in height
+      &.bk-dialog-modal--small {
+        --bk-dialog-modal-fade-scale: 1.05;
+        max-width: 30vw;
+      }
+      &.bk-dialog-modal--medium {
+        --bk-dialog-modal-fade-scale: 1.04;
+        max-width: 50vw;
+      }
+      &.bk-dialog-modal--large {
+        --bk-dialog-modal-fade-scale: 1.03;
+        max-width: 60vw;
+      }
     }
     
     &.bk-dialog-modal--full-screen {
@@ -84,6 +135,13 @@
       margin: 0;
       width: auto;
       height: auto;
+      
+      --bk-dialog-modal-entry-dur: 120ms;
+      --bk-dialog-modal-exit-dur: 120ms;
+      @include dialog-fade-in(
+        $entry-dur: var(--bk-dialog-modal-entry-dur),
+        $exit-dur: var(--bk-dialog-modal-exit-dur),
+      );
     }
     
     &.bk-dialog-modal--slide-over {
@@ -93,6 +151,13 @@
       height: auto;
       
       margin-inline-start: 20vw;
+      
+      --bk-dialog-modal-entry-dur: 300ms;
+      --bk-dialog-modal-exit-dur: 250ms;
+      @include dialog-slide-over(
+        $entry-dur: var(--bk-dialog-modal-entry-dur),
+        $exit-dur: var(--bk-dialog-modal-exit-dur),
+      );
     }
   }
 }
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 6fed7c76..f7fa17f7 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -5,6 +5,7 @@
 import * as React from 'react';
 
 import type { Meta, StoryObj } from '@storybook/react';
+import { LoremIpsum } from '../../../util/storybook/LoremIpsum.tsx';
 
 import { Button } from '../../actions/Button/Button.tsx';
 
@@ -24,12 +25,24 @@ export default {
   args: {
     title: 'Modal dialog',
     trigger: ({ active, activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
+    children: <LoremIpsum paragraphs={15}/>,
   },
   render: (args) => <DialogModal {...args}/>,
 } satisfies Meta<DialogModalArgs>;
 
 
-export const DialogModalStandard: Story = {
+export const DialogModalStandard: Story = {};
+
+export const DialogModalSmall: Story = {
+  args: {
+    size: 'small',
+  },
+};
+
+export const DialogModalLarge: Story = {
+  args: {
+    size: 'large',
+  },
 };
 
 export const DialogModalFullScreen: Story = {
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 81dddf04..c9dea505 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -21,7 +21,7 @@ export type DialogModalProps = ComponentProps<typeof Dialog> & {
   /** How to display the modal in the viewport. Default: 'center'. */
   display?: undefined | 'center' | 'full-screen' | 'slide-over',
   
-  /** The size of the modal. Applies to modals with `display="center"`. */
+  /** The size of the modal. Note: does not apply to full screen modals. */
   size?: undefined | 'small' | 'medium' | 'large',
   
   /** The modal trigger. */
@@ -39,6 +39,7 @@ export const DialogModal = (props: DialogModalProps) => {
     trigger,
     unstyled = false,
     display = 'center',
+    size = 'medium',
     ...propsRest
   } = props;
   
@@ -56,6 +57,9 @@ export const DialogModal = (props: DialogModalProps) => {
             { [cl['bk-dialog-modal--center']]: display === 'center' },
             { [cl['bk-dialog-modal--full-screen']]: display === 'full-screen' },
             { [cl['bk-dialog-modal--slide-over']]: display === 'slide-over' },
+            { [cl['bk-dialog-modal--small']]: size === 'small' },
+            { [cl['bk-dialog-modal--medium']]: size === 'medium' },
+            { [cl['bk-dialog-modal--large']]: size === 'large' },
             dialogProps.className,
             propsRest.className,
           )}
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index a1e3e97f..35ce69c3 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -4,7 +4,8 @@
 
 import * as React from 'react';
 
-import { useControlledDialog, type ControlledDialogProps } from './useControlledDialog.ts';
+import { useDebounce } from '../../../util/hooks/useDebounce.ts';
+import { useControlledDialog, type ControlledDialogProps } from '../../util/Dialog/useControlledDialog.ts';
 
 import cl from './ModalProvider.module.scss';
 
@@ -21,16 +22,30 @@ export type ModalProviderProps = {
   
   /** Whether the modal should be active by default. */
   activeDefault?: undefined | boolean,
+  
+  /** How long to keep the dialog in the DOM for exit animation purposes. Default: 2 seconds. */
+  exitAnimationDelay?: undefined | number,
 };
 /**
  * Provider around a trigger (e.g. button) to display a modal overlay on trigger activation.
  */
 export const ModalProvider = (props: ModalProviderProps) => {
-  const { children, content, activeDefault = false } = props;
+  const {
+    children,
+    content,
+    activeDefault = false,
+    exitAnimationDelay = 100_000,
+  } = props;
+  
+  const [active, setActiveInternal] = React.useState(activeDefault);
+  const [activeWithDelay, setActiveWithDelay] = useDebounce(active, exitAnimationDelay);
   
-  const [active, setActive] = React.useState(activeDefault);
-  const activate = React.useCallback(() => { setActive(true); }, []);
+  const setActive = React.useCallback((active: boolean) => {
+    setActiveInternal(active);
+    if (active) { setActiveWithDelay(true); } // Skip the delay when activating (should only be for deactivation)
+  }, [setActiveWithDelay]);
   
+  const activate = React.useCallback(() => { setActive(true); }, [setActive]);
   const triggerProps = { active, activate };
   
   const dialogProps = useControlledDialog({
@@ -41,7 +56,7 @@ export const ModalProvider = (props: ModalProviderProps) => {
   
   return (
     <>
-      {active && content(dialogProps)}
+      {activeWithDelay && content(dialogProps)}
       {children(triggerProps)}
     </>
   );
diff --git a/src/components/overlays/ModalProvider/useControlledDialog.ts b/src/components/util/Dialog/useControlledDialog.ts
similarity index 100%
rename from src/components/overlays/ModalProvider/useControlledDialog.ts
rename to src/components/util/Dialog/useControlledDialog.ts
diff --git a/src/util/hooks/useDebounce.ts b/src/util/hooks/useDebounce.ts
new file mode 100644
index 00000000..5223e582
--- /dev/null
+++ b/src/util/hooks/useDebounce.ts
@@ -0,0 +1,36 @@
+
+import * as React from 'react';
+
+
+type TimeoutRef = ReturnType<typeof globalThis.setTimeout>;
+type UseDebounceResult<S> = [S, React.Dispatch<React.SetStateAction<S>>];
+
+// Adopted from: https://github.com/uidotdev/usehooks
+export const useDebounce = <S>(value: S, delay: number /* ms */): UseDebounceResult<S> => {
+  const [debouncedValue, setDebouncedValue] = React.useState(value);
+  const timeoutHandleRef = React.useRef<TimeoutRef>(null);
+  
+  React.useEffect(() => {
+    timeoutHandleRef.current = globalThis.setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+    
+    return () => {
+      const timeoutHandle = timeoutHandleRef.current;
+      if (timeoutHandle) {
+        globalThis.clearTimeout(timeoutHandle);
+      }
+    };
+  }, [value, delay]);
+  
+  const setDebouncedManually = React.useCallback((value: React.SetStateAction<S>) => {
+    setDebouncedValue(value);
+    
+    const timeoutHandle = timeoutHandleRef.current;
+    if (timeoutHandle) {
+      globalThis.clearTimeout(timeoutHandle);
+    }
+  }, []);
+  
+  return [debouncedValue, setDebouncedManually];
+};

From eb331f7b2f6783cf6ce4c30d38c5002831b82285 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Thu, 2 Jan 2025 20:54:02 +0100
Subject: [PATCH 10/33] Remove biome exception.

---
 biome.jsonc | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/biome.jsonc b/biome.jsonc
index fbb44450..255afc92 100644
--- a/biome.jsonc
+++ b/biome.jsonc
@@ -33,12 +33,6 @@
       "style": {
         "useImportType": "off",
         "noUnusedTemplateLiteral": "off"
-      },
-      "a11y": {
-        // Putting `tabindex` on non-interactive elements is often necessary, for example for scrolling content.
-        // https://ux.stackexchange.com/questions/119952/when-is-it-wrong-to-put-tabindex-0-on-non-interactive-content
-        // https://stackoverflow.com/questions/53597209/tabindex-on-el-that-are-interactive-under-certain-conditions
-        "noNoninteractiveTabindex": "off"
       }
     }
   }

From 99da117692f6fefa095d6a2df209bb58bf4b0cf6 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Thu, 2 Jan 2025 20:54:53 +0100
Subject: [PATCH 11/33] Remove overflow-y: auto.

---
 src/components/containers/Panel/Panel.module.scss | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/components/containers/Panel/Panel.module.scss b/src/components/containers/Panel/Panel.module.scss
index 6abd9082..21b1f72b 100644
--- a/src/components/containers/Panel/Panel.module.scss
+++ b/src/components/containers/Panel/Panel.module.scss
@@ -9,7 +9,6 @@
   --bk-panel-border-color: #{bk.$theme-card-border-default};
   
   overflow: hidden;
-  overflow-y: auto;
   
   min-height: 4rem;
   padding: 22px 26px; // FIXME

From 2244274c4c28b1984e5f25d96352ad17d1f832d4 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Fri, 3 Jan 2025 01:03:56 +0100
Subject: [PATCH 12/33] Update Dialog styling.

---
 .../actions/Button/Button.module.scss         |   1 +
 src/components/actions/Button/Button.tsx      |   2 +-
 src/components/containers/Banner/Banner.tsx   |   8 +-
 .../containers/Dialog/Dialog.module.scss      |  38 ++--
 .../containers/Dialog/Dialog.stories.tsx      |  28 +--
 src/components/containers/Dialog/Dialog.tsx   | 163 +++++++++++-------
 src/styling/context/theming.scss              |   2 +-
 src/typography/Heading/Heading.mixins.scss    |  12 +-
 8 files changed, 151 insertions(+), 103 deletions(-)

diff --git a/src/components/actions/Button/Button.module.scss b/src/components/actions/Button/Button.module.scss
index 06e2c3c5..58d1c6a3 100644
--- a/src/components/actions/Button/Button.module.scss
+++ b/src/components/actions/Button/Button.module.scss
@@ -14,6 +14,7 @@
     align-self: flex-start;
     
     cursor: pointer;
+    user-select: none;
     
     margin: 0;
     padding: 0;
diff --git a/src/components/actions/Button/Button.tsx b/src/components/actions/Button/Button.tsx
index 2f048b50..a990ec51 100644
--- a/src/components/actions/Button/Button.tsx
+++ b/src/components/actions/Button/Button.tsx
@@ -122,7 +122,7 @@ export const Button = (props: ButtonProps) => {
   // context. Use `SubmitButton` instead.
   // biome-ignore lint/suspicious/noExplicitAny: `type` is not in the public type but can be there for internal use
   const type: unknown = (propsRest as any).type;
-  let buttonType: undefined | 'submit' = undefined;
+  let buttonType: 'button' | 'submit' = 'button';
   
   if (type === 'submit') {
     throw new Error(`Button component cannot have type 'submit', use SubmitButton instead.`);
diff --git a/src/components/containers/Banner/Banner.tsx b/src/components/containers/Banner/Banner.tsx
index eff16511..257c4100 100644
--- a/src/components/containers/Banner/Banner.tsx
+++ b/src/components/containers/Banner/Banner.tsx
@@ -36,11 +36,11 @@ const BannerVariantIcon = ({ variant, ...propsRest }: BannerVariantIconProps) =>
 };
 
 
-export type ActionButtonProps = ComponentProps<typeof Button>;
+type ActionButtonProps = ComponentProps<typeof Button>;
 /**
  * A customized version of the `<Button/>` component specifically meant to be used for banner actions.
  */
-export const ActionButton = (props: ActionButtonProps) => {
+const ActionButton = (props: ActionButtonProps) => {
   return (
     <Button trimmed
       {...props}
@@ -49,7 +49,7 @@ export const ActionButton = (props: ActionButtonProps) => {
   );
 };
 
-export type ActionIconProps = ComponentProps<typeof Button> & {
+type ActionIconProps = ComponentProps<typeof Button> & {
   /** There must be `label` on an icon-only button, for accessibility. */
   label: Required<ComponentProps<typeof Button>>['label'],
   
@@ -59,7 +59,7 @@ export type ActionIconProps = ComponentProps<typeof Button> & {
 /**
  * An action that is rendered as just an icon.
  */
-export const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
+const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
   return (
     <TooltipProvider compact tooltip={typeof tooltip !== 'undefined' ? tooltip : buttonProps.label}>
       <Button trimmed
diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index d1c6e82a..7956e9bd 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -17,7 +17,6 @@
     margin: 0;
     padding: 0; // Do not apply padding on the outermost container (do it on the lower level elements instead)
     
-    //box-shadow: 0 8px 10px 1px rgba(0 0 0 / 14%), 0 3px 14px 2px rgba(0 0 0 / 12%), 0 5px 5px -3px rgba(0 0 0 / 3%);
     border-radius: bk.$radius-3;
     &.bk-dialog--flat {
       border: none;
@@ -36,40 +35,47 @@
       top: 0;
       z-index: 1;
       
-      padding-block: var(--bk-dialog-padding-block) 0;
+      padding-block: var(--bk-dialog-padding-block) (bk.$spacing-7 / 2);
       padding-inline: var(--bk-dialog-padding-inline);
-      
       background: var(--bk-dialog-background-color);
       
-      --header-shadow-size: calc(var(--bk-sizing-1) / 2);
-      //box-shadow: 0 var(--header-shadow-size) 0 0 rgba(0 0 0 / 12%);
-      /* Clip everything except the bottom shadow (-1px for weird clipping behavior with scroll) */
-      //clip-path: inset(-1px -1px calc(-1 * var(--header-shadow-size)) -1px);
-      
       display: flex;
       flex-direction: row;
-      align-items: baseline;
+      align-items: center;
+      gap: bk.$spacing-4;
       
-      .bk-dialog__action { --keep: ; }
-      :nth-child(1 of .bk-dialog__action) { // XXX https://github.com/parcel-bundler/lightningcss/issues/883
+      .bk-dialog__header__title {
+        @include bk.text-one-line;
+      }
+      
+      .bk-dialog__header__actions {
         margin-inline-start: auto;
       }
     }
     
     .bk-dialog__content {
-      flex: 1; /* Make sure we cover all available space */
+      flex: 1;
       
-      margin-block: bk.$spacing-7 bk.$spacing-9;
+      margin-block: (bk.$spacing-7 / 2) (bk.$spacing-7 / 2);
       padding-inline: var(--bk-dialog-padding-inline);
     }
     
     .bk-dialog__actions {
-      padding: var(--bk-dialog-inset);
-      padding-top: 0;
+      position: sticky;
+      bottom: 0;
+      z-index: 1;
+      
+      padding-block: (bk.$spacing-7 / 2) bk.$spacing-9;
+      padding-inline: var(--bk-dialog-padding-inline);
+      // In Figma, actions have an indent. But that might be only if the content itself has an indent, need to check.
+      //padding-inline-start: calc(var(--bk-dialog-padding-inline) + bk.$spacing-8);
+      
+      background: var(--bk-dialog-background-color);
       
       display: flex;
       flex-direction: row;
-      gap: 0.8rem;
+      align-items: center;
+      gap: bk.$spacing-4;
     }
     
     // State: focus
diff --git a/src/components/containers/Dialog/Dialog.stories.tsx b/src/components/containers/Dialog/Dialog.stories.tsx
index bbdd21f6..8a534d4d 100644
--- a/src/components/containers/Dialog/Dialog.stories.tsx
+++ b/src/components/containers/Dialog/Dialog.stories.tsx
@@ -6,8 +6,9 @@ import * as React from 'react';
 
 import type { Meta, StoryObj } from '@storybook/react';
 import { LayoutDecorator } from '../../../util/storybook/LayoutDecorator.tsx';
+import { loremIpsum, LoremIpsum } from '../../../util/storybook/LoremIpsum.tsx';
 
-import { LoremIpsum } from '../../../util/storybook/LoremIpsum.tsx';
+import { Button } from '../../actions/Button/Button.tsx';
 
 import { Dialog } from './Dialog.tsx';
 
@@ -22,40 +23,41 @@ export default {
     layout: 'padded',
   },
   decorators: [
-    Story => <LayoutDecorator size="large" style={{ maxHeight: '15lh' }}><Story/></LayoutDecorator>,
+    Story => <LayoutDecorator size="large" style={{ maxHeight: '20lh' }}><Story/></LayoutDecorator>,
   ],
   args: {
     title: 'Dialog title',
+    children: <LoremIpsum paragraphs={3}/>,
+    actions: (
+      <Button variant="primary" label="Submit"/>
+    ),
     onRequestClose: () => {},
   },
 } satisfies Meta<DialogArgs>;
 
 
-export const DialogStandard: Story = {
+export const DialogStandard: Story = {};
+
+export const DialogWithoutClose: Story = {
   args: {
-    children: <LoremIpsum paragraphs={3}/>,
+    showCloseIcon: false,
   },
 };
 
-export const DialogWithClose: Story = {
+export const DialogWithFocus: Story = {
   args: {
-    children: <LoremIpsum paragraphs={3}/>,
-    showCloseAction: true,
+    className: 'pseudo-focus-visible',
   },
 };
 
-export const DialogWithFocus: Story = {
+export const DialogWithTitleOverflow: Story = {
   args: {
-    className: 'pseudo-focus-visible',
-    children: <LoremIpsum paragraphs={3}/>,
-    showCloseAction: true,
+    title: loremIpsum(),
   },
 };
 
 export const DialogFlat: Story = {
   args: {
-    children: <LoremIpsum paragraphs={3}/>,
     flat: true,
-    showCloseAction: true,
   },
 };
diff --git a/src/components/containers/Dialog/Dialog.tsx b/src/components/containers/Dialog/Dialog.tsx
index 03b23cea..a4260516 100644
--- a/src/components/containers/Dialog/Dialog.tsx
+++ b/src/components/containers/Dialog/Dialog.tsx
@@ -17,7 +17,7 @@ import cl from './Dialog.module.scss';
 
 export { cl as DialogClassNames };
 
-export type ActionIconProps = ComponentProps<typeof Button> & {
+type ActionIconProps = ComponentProps<typeof Button> & {
   /** There must be `label` on an icon-only button, for accessibility. */
   label: Required<ComponentProps<typeof Button>>['label'],
   
@@ -27,7 +27,7 @@ export type ActionIconProps = ComponentProps<typeof Button> & {
 /**
  * An action that is rendered as just an icon.
  */
-export const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
+const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
   return (
     <TooltipProvider compact tooltip={typeof tooltip !== 'undefined' ? tooltip : buttonProps.label}>
       <Button unstyled
@@ -38,6 +38,27 @@ export const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
   );
 };
 
+type ActionButtonProps = ComponentProps<typeof Button> & {
+  /** Optional tooltip text. */
+  tooltip?: undefined | ComponentProps<typeof TooltipProvider>['tooltip'],
+};
+/**
+ * An action that is rendered as just an icon.
+ */
+const ActionButton = ({ tooltip = null, ...buttonProps }: ActionButtonProps) => {
+  return (
+    <TooltipProvider compact tooltip={typeof tooltip !== 'undefined' ? tooltip : null}>
+      <Button unstyled
+        {...buttonProps}
+        className={cx(cl['bk-dialog__action'], cl['bk-dialog__action--button'], buttonProps.className)}
+      />
+    </TooltipProvider>
+  );
+};
+
+const CancelAction = (props: ComponentProps<typeof Button>) =>
+  <Button variant="secondary" label="Cancel" {...props}/>;
+
 export type DialogProps = Omit<ComponentProps<'dialog'>, 'title'> & {
   /** Whether the component should include the default styling. Default: false. */
   unstyled?: undefined | boolean,
@@ -48,70 +69,88 @@ export type DialogProps = Omit<ComponentProps<'dialog'>, 'title'> & {
   /** The title of the dialog, to be displayed in the dialog header. */
   title: React.ReactNode,
   
-  /** If specified, a close action is displayed. Default: true. */
-  showCloseAction?: undefined | boolean,
+  /** If specified, a close icon is displayed in the header. Default: true. */
+  showCloseIcon?: undefined | boolean,
+  
+  /** If specified, a close action is displayed in the footer. Default: true. */
+  showCancelAction?: undefined | boolean,
   
   /** Callback that is called when the user requests the dialog to close. */
   onRequestClose?: undefined | (() => void), // Note: cannot name this `onClose`, dialog already has an `onClose` prop
+  
+  /** Any additional actions to be shown in the dialog. */
+  actions?: undefined | React.ReactNode,
 };
 /**
  * The Dialog component displays an interaction with the user, for example a confirmation, or a form to be submitted.
  */
-export const Dialog = (props: DialogProps) => {
-  const {
-    children,
-    unstyled = false,
-    flat = false,
-    title,
-    showCloseAction = true,
-    onRequestClose,
-    ...propsRest
-  } = props;
-  
-  const dialogRef = React.useRef<HTMLDialogElement>(null);
-  const scrollerProps = useScroller();
-  
-  if (showCloseAction && typeof onRequestClose !== 'function') {
-    console.error(`Missing prop in <Dialog/>: 'onRequestClose' function`);
-  }
-  
-  return (
-    <dialog
-      open
-      {...scrollerProps}
-      {...propsRest}
-      ref={mergeRefs(dialogRef, propsRest.ref)}
-      className={cx(
-        'bk',
-        { [cl['bk-dialog']]: !unstyled },
-        { [cl['bk-dialog--flat']]: flat },
-        scrollerProps.className,
-        propsRest.className,
-      )}
-    >
-      <header className={cx(cl['bk-dialog__header'])}>
-        <H5>{title}</H5>
-        
-        {showCloseAction &&
-          <ActionIcon
-            label="Close dialog"
-            tooltip={null}
-            className={cx(cl['bk-dialog__action'], cl['bk-dialog__action-close'])}
-            onPress={onRequestClose}
-          >
-            <Icon icon="cross"/>
-          </ActionIcon>
-        }
-      </header>
-      
-      <section className={cx(cl['bk-dialog__content'], 'bk-body-text')}>
-        {children}
-      </section>
-      
-      {/* <footer className={cx(cl['bk-dialog__actions'])}>
-        <Button autoFocus variant="secondary" label="Cancel"/>
-        <Button variant="primary" label="Submit"/>
-      </footer> */}
-    </dialog>
-  );
-};
+export const Dialog = Object.assign(
+  (props: DialogProps) => {
+    const {
+      children,
+      unstyled = false,
+      flat = false,
+      title,
+      showCloseIcon = true,
+      showCancelAction = true,
+      onRequestClose,
+      actions,
+      ...propsRest
+    } = props;
+    
+    const dialogRef = React.useRef<HTMLDialogElement>(null);
+    const scrollerProps = useScroller();
+    
+    if ((showCloseIcon || showCancelAction) && typeof onRequestClose !== 'function') {
+      console.error(`Missing prop in <Dialog/>: 'onRequestClose' function`);
+    }
+    
+    return (
+      <dialog
+        open
+        {...scrollerProps}
+        {...propsRest}
+        ref={mergeRefs(dialogRef, propsRest.ref)}
+        className={cx(
+          'bk',
+          { [cl['bk-dialog']]: !unstyled },
+          { [cl['bk-dialog--flat']]: flat },
+          scrollerProps.className,
+          propsRest.className,
+        )}
+      >
+        <form>
+          <header className={cx(cl['bk-dialog__header'])}>
+            <H5 className={cx(cl['bk-dialog__header__title'])}>{title}</H5>
+            
+            <div className={cx(cl['bk-dialog__header__actions'])}>
+              {showCloseIcon &&
+                <ActionIcon
+                  autoFocus
+                  label="Close dialog"
+                  tooltip={null}
+                  className={cx(cl['bk-dialog__action'], cl['bk-dialog__action-close'])}
+                  onPress={onRequestClose}
+                >
+                  <Icon icon="cross"/>
+                </ActionIcon>
+              }
+            </div>
+          </header>
+          
+          <section className={cx(cl['bk-dialog__content'], 'bk-body-text')}>
+            {children}
+          </section>
+          
+          <footer className={cx(cl['bk-dialog__actions'])}>
+            {showCancelAction && <CancelAction/>}
+            {actions}
+          </footer>
+        </form>
+      </dialog>
+    );
+  },
+  {
+    CancelAction,
+  },
+);
diff --git a/src/styling/context/theming.scss b/src/styling/context/theming.scss
index 04596886..c3c1b505 100644
--- a/src/styling/context/theming.scss
+++ b/src/styling/context/theming.scss
@@ -15,7 +15,7 @@ a `light-dark()` expression in a variable and reuse that in a different theme. M
   --bk-page-color-text: #{bk.$theme-text-body-default};
   --bk-page-color-background: #{bk.$theme-page-default};
   --bk-focus-outline-color: light-dark(#81bcec, #81bcec); // FIXME: need the outline colors
-  --bk-focus-outline-width: 0.125rem;
+  --bk-focus-outline-width: 0.2rem;
 }
 
 /* This mixin should be used after every usage of `color-scheme` */
diff --git a/src/typography/Heading/Heading.mixins.scss b/src/typography/Heading/Heading.mixins.scss
index 1fec9b6f..a6b48df0 100644
--- a/src/typography/Heading/Heading.mixins.scss
+++ b/src/typography/Heading/Heading.mixins.scss
@@ -12,31 +12,31 @@
 
 @mixin h1 {
   @include heading;
-  font-size: 42px;
+  font-size: bk.$font-size-xxxl;
   font-weight: 300;
 }
 @mixin h2 {
   @include heading;
-  font-size: 30px;
+  font-size: bk.rem-from-px(30); // FIXME: token
   font-weight: 400;
 }
 @mixin h3 {
   @include heading;
-  font-size: 24px;
+  font-size: bk.rem-from-px(24); // FIXME: token
   font-weight: 400;
 }
 @mixin h4 {
   @include heading;
-  font-size: 20px;
+  font-size: bk.rem-from-px(20); // FIXME: token
   font-weight: 400;
 }
 @mixin h5 {
   @include heading;
-  font-size: 16px;
+  font-size: bk.rem-from-px(16); // FIXME: token
   font-weight: 600;
 }
 @mixin h6 {
   @include heading;
-  font-size: 16px;
+  font-size: bk.rem-from-px(16); // FIXME: token
   font-weight: 500;
 }

From 8ad56a81e272422152c7560752703602bb87df0c Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Fri, 3 Jan 2025 01:04:21 +0100
Subject: [PATCH 13/33] Update DialogModal styling.

---
 src/components/overlays/DialogModal/DialogModal.stories.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index f7fa17f7..f053c3c8 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -19,7 +19,7 @@ export default {
   component: DialogModal,
   tags: ['autodocs'],
   parameters: {
-    layout: 'fullscreen',
+    layout: 'padded',
   },
   argTypes: {},
   args: {
@@ -27,7 +27,7 @@ export default {
     trigger: ({ active, activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
     children: <LoremIpsum paragraphs={15}/>,
   },
-  render: (args) => <DialogModal {...args}/>,
+  render: (args) => <><LoremIpsum paragraphs={2}/> <DialogModal {...args}/> <LoremIpsum paragraphs={2}/></>,
 } satisfies Meta<DialogModalArgs>;
 
 

From 6d4bab0118c0d8dfd655868480616d41ec203a37 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Fri, 3 Jan 2025 22:34:45 +0100
Subject: [PATCH 14/33] Fix fractional px value rounding issues.

---
 .../Accordion/Accordion.module.scss           |  2 +-
 src/styling/defs.scss                         |  2 +-
 src/styling/global/global.scss                |  2 +-
 src/styling/global/reset.scss                 |  1 -
 src/styling/variables.scss                    | 36 +++++++++----------
 5 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/src/components/containers/Accordion/Accordion.module.scss b/src/components/containers/Accordion/Accordion.module.scss
index 727f3fe4..b22ed518 100644
--- a/src/components/containers/Accordion/Accordion.module.scss
+++ b/src/components/containers/Accordion/Accordion.module.scss
@@ -13,10 +13,10 @@
     
     .bk-accordion__item + .bk-accordion__item {
       --bk-disclosure-border-radius-top: 0;
-      border-top-width: 0;
     }
     .bk-accordion__item:has(+ .bk-accordion__item) {
       --bk-disclosure-border-radius-bottom: 0;
+      border-bottom-width: 0;
     }
   }
 }
diff --git a/src/styling/defs.scss b/src/styling/defs.scss
index c08437f0..dcd73e64 100644
--- a/src/styling/defs.scss
+++ b/src/styling/defs.scss
@@ -59,5 +59,5 @@
 }
 
 @function rem-from-px($size-in-px) {
-  @return math.div($size-in-px, 14) * 1rem;
+  @return round(math.div($size-in-px, 14) * 1rem, 1px);
 }
diff --git a/src/styling/global/global.scss b/src/styling/global/global.scss
index ebaead2b..f2043e5c 100644
--- a/src/styling/global/global.scss
+++ b/src/styling/global/global.scss
@@ -38,7 +38,7 @@
     // https://royalfig.github.io/fluid-typography-calculator
     //font-size: clamp(0.8rem, 0.76rem + 0.19999999999999996vw, 1rem);
     // https://utopia.fyi/type/calculator?c=320,12,1.2,1440,14,1.25,4,2,&s=0.75|0.5|0.25,1.5|2|3|4|6,s-l&g=s,l,xl,12
-    font-size: clamp(0.75rem, 0.7143rem + 0.1786vi, 0.875rem); // 1rem ~ 14px at 1440px max viewport size
+    font-size: round(clamp(0.75rem, 0.7143rem + 0.1786vi, 0.875rem), 1px); // 1rem ~ 14px at 1440px max viewport size
     
     /* https://css-tricks.com/how-to-tame-line-height-in-css/ */
     line-height: 1.6;
diff --git a/src/styling/global/reset.scss b/src/styling/global/reset.scss
index 87105419..ab26f7ee 100644
--- a/src/styling/global/reset.scss
+++ b/src/styling/global/reset.scss
@@ -7,7 +7,6 @@
 @mixin styles {
   @include meta.load-css('../lib/reset.css');
   
-  
   /* Custom reset overrides */
   
   // :focus-visible {
diff --git a/src/styling/variables.scss b/src/styling/variables.scss
index ddf41a9b..161b2c43 100644
--- a/src/styling/variables.scss
+++ b/src/styling/variables.scss
@@ -46,24 +46,24 @@ $sizing-xxl: $sizing-9 !default;
 
 // NEW
 // Reference: 1rem ~ 14px (at max 1440px size, and with default 1rem=16px browser font size)
-$spacing-1: math.div(4, 14) * 1rem !default; // ~4px
-$spacing-2: math.div(8, 14) * 1rem !default; // ~8px
-$spacing-3: math.div(12, 14) * 1rem !default; // ~12px
-$spacing-4: math.div(16, 14) * 1rem !default; // ~16px
-$spacing-5: math.div(18, 14) * 1rem !default; // ~18px
-$spacing-6: math.div(20, 14) * 1rem !default; // ~20px
-$spacing-7: math.div(24, 14) * 1rem !default; // ~24px
-$spacing-8: math.div(32, 14) * 1rem !default; // ~32px
-$spacing-9: math.div(40, 14) * 1rem !default; // ~40px
-$spacing-10: math.div(48, 14) * 1rem !default; // ~48px
-$spacing-11: math.div(64, 14) * 1rem !default; // ~64px
-$spacing-12: math.div(80, 14) * 1rem !default; // ~80px
-$spacing-13: math.div(96, 14) * 1rem !default; // ~96px
-$spacing-14: math.div(128, 14) * 1rem !default; // ~128px
-$spacing-15: math.div(160, 14) * 1rem !default; // ~160px
-$spacing-16: math.div(192, 14) * 1rem !default; // ~192px
-$spacing-17: math.div(224, 14) * 1rem !default; // ~224px
-$spacing-18: math.div(256, 14) * 1rem !default; // ~256px
+$spacing-1: round(math.div(4, 14) * 1rem, 1px) !default; // ~4px
+$spacing-2: round(math.div(8, 14) * 1rem, 1px) !default; // ~8px
+$spacing-3: round(math.div(12, 14) * 1rem, 1px) !default; // ~12px
+$spacing-4: round(math.div(16, 14) * 1rem, 1px) !default; // ~16px
+$spacing-5: round(math.div(18, 14) * 1rem, 1px) !default; // ~18px
+$spacing-6: round(math.div(20, 14) * 1rem, 1px) !default; // ~20px
+$spacing-7: round(math.div(24, 14) * 1rem, 1px) !default; // ~24px
+$spacing-8: round(math.div(32, 14) * 1rem, 1px) !default; // ~32px
+$spacing-9: round(math.div(40, 14) * 1rem, 1px) !default; // ~40px
+$spacing-10: round(math.div(48, 14) * 1rem, 1px) !default; // ~48px
+$spacing-11: round(math.div(64, 14) * 1rem, 1px) !default; // ~64px
+$spacing-12: round(math.div(80, 14) * 1rem, 1px) !default; // ~80px
+$spacing-13: round(math.div(96, 14) * 1rem, 1px) !default; // ~96px
+$spacing-14: round(math.div(128, 14) * 1rem, 1px) !default; // ~128px
+$spacing-15: round(math.div(160, 14) * 1rem, 1px) !default; // ~160px
+$spacing-16: round(math.div(192, 14) * 1rem, 1px) !default; // ~192px
+$spacing-17: round(math.div(224, 14) * 1rem, 1px) !default; // ~224px
+$spacing-18: round(math.div(256, 14) * 1rem, 1px) !default; // ~256px
 
 // these sizes do not match Figma variables
 $size-1: math.div(1, 14) * 1rem !default; // ~1px

From dbd42da9ef73719a525da8da4eec8fb72837d97d Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Fri, 3 Jan 2025 23:01:18 +0100
Subject: [PATCH 15/33] Fix broken sizing calculations.

---
 src/components/containers/Banner/Banner.module.scss         | 2 +-
 src/components/containers/Dialog/Dialog.module.scss         | 6 +++---
 .../forms/fields/CheckboxField/CheckboxField.module.scss    | 1 -
 .../forms/fields/RadioField/RadioField.module.scss          | 1 -
 4 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/components/containers/Banner/Banner.module.scss b/src/components/containers/Banner/Banner.module.scss
index 354174fc..0caae80e 100644
--- a/src/components/containers/Banner/Banner.module.scss
+++ b/src/components/containers/Banner/Banner.module.scss
@@ -16,7 +16,7 @@
     overflow: hidden; // Banners shouldn't scroll (max height on a banner doesn't really make sense)
     
     padding-block: bk.$spacing-2;
-    padding-inline: bk.$spacing-4 - bk.$radius-2;
+    padding-inline: calc(bk.$spacing-4 - bk.$radius-2);
     padding-inline-start: var(--bk-banner-indent); // Indent all of the content (e.g. for when the message wraps)
     
     border: bk.$size-1 var(--bk-banner-color-foreground) solid;
diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index 71eba6c2..2270b6fa 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -35,7 +35,7 @@
       top: 0;
       z-index: 1;
       
-      padding-block: var(--bk-dialog-padding-block) (bk.$spacing-7 / 2);
+      padding-block: var(--bk-dialog-padding-block) calc(bk.$spacing-7 / 2);
       padding-inline: var(--bk-dialog-padding-inline);
       background: var(--bk-dialog-background-color);
       
@@ -58,7 +58,7 @@
     .bk-dialog__content {
       flex: 1;
       
-      margin-block: (bk.$spacing-7 / 2) (bk.$spacing-7 / 2);
+      margin-block: calc(bk.$spacing-7 / 2) calc(bk.$spacing-7 / 2);
       padding-inline: var(--bk-dialog-padding-inline);
     }
     
@@ -67,7 +67,7 @@
       bottom: 0;
       z-index: 1;
       
-      padding-block: (bk.$spacing-7 / 2) bk.$spacing-9;
+      padding-block: calc(bk.$spacing-7 / 2) bk.$spacing-9;
       padding-inline: var(--bk-dialog-padding-inline);
       // In Figma, actions have an indent. But that might be only if the content itself has an indent, need to check.
       //padding-inline-start: calc(var(--bk-dialog-padding-inline) + bk.$spacing-8);
diff --git a/src/components/forms/fields/CheckboxField/CheckboxField.module.scss b/src/components/forms/fields/CheckboxField/CheckboxField.module.scss
index 981b7325..8a66d2c0 100644
--- a/src/components/forms/fields/CheckboxField/CheckboxField.module.scss
+++ b/src/components/forms/fields/CheckboxField/CheckboxField.module.scss
@@ -14,7 +14,6 @@
       margin-bottom: bk.$spacing-1;
 
       .bk-checkbox-field__title__icon {
-        font-size: 18px;
         margin-left: bk.$spacing-1;
       }
 
diff --git a/src/components/forms/fields/RadioField/RadioField.module.scss b/src/components/forms/fields/RadioField/RadioField.module.scss
index 3f175c23..85a4e1c9 100644
--- a/src/components/forms/fields/RadioField/RadioField.module.scss
+++ b/src/components/forms/fields/RadioField/RadioField.module.scss
@@ -14,7 +14,6 @@
       margin-bottom: bk.$spacing-1;
 
       .bk-radio-field__title__icon {
-        font-size: 18px;
         margin-left: bk.$spacing-1;
       }
 

From 57b760b31e889b4585d0fd036bcf06760492dacd Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Fri, 3 Jan 2025 23:35:42 +0100
Subject: [PATCH 16/33] Implement slideOverPosition.

---
 src/components/containers/Banner/Banner.tsx   |  2 +-
 .../containers/Dialog/Dialog.module.scss      |  6 ++
 src/components/containers/Dialog/Dialog.tsx   | 58 ++++++++++---------
 .../DialogModal/DialogModal.module.scss       | 44 +++++++++-----
 .../overlays/DialogModal/DialogModal.tsx      | 12 +++-
 5 files changed, 74 insertions(+), 48 deletions(-)

diff --git a/src/components/containers/Banner/Banner.tsx b/src/components/containers/Banner/Banner.tsx
index 257c4100..00d627c1 100644
--- a/src/components/containers/Banner/Banner.tsx
+++ b/src/components/containers/Banner/Banner.tsx
@@ -72,7 +72,7 @@ const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
 
 
 export type BannerProps = Omit<ComponentProps<'div'>, 'title'> & {
-  /** Whether the component should include the default styling. Defaults to false. */
+  /** Whether this component should be unstyled. */
   unstyled?: undefined | boolean,
   
   /** Whether to trim this component (strip any spacing around the element). */
diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index 2270b6fa..2eb73023 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -14,6 +14,10 @@
     --bk-dialog-padding-block: #{bk.$spacing-8};
     --bk-dialog-padding-inline: #{bk.$spacing-8};
     
+    // The default `auto` inherits from the parent, which we do not want. In the future if `contain: user-select`
+    // becomes supported, we could use that instead.
+    user-select: text;
+    
     margin: 0;
     padding: 0; // Do not apply padding on the outermost container (do it on the lower level elements instead)
     
@@ -22,6 +26,8 @@
       border: none;
       border-radius: 0;
     }
+    background: var(--bk-dialog-background-color);
+    color: bk.$theme-modal-text-default;
     
     display: flex;
     flex-direction: column;
diff --git a/src/components/containers/Dialog/Dialog.tsx b/src/components/containers/Dialog/Dialog.tsx
index b9a4e964..dd2d495e 100644
--- a/src/components/containers/Dialog/Dialog.tsx
+++ b/src/components/containers/Dialog/Dialog.tsx
@@ -60,7 +60,7 @@ const CancelAction = (props: ComponentProps<typeof Button>) =>
   <Button variant="secondary" label="Cancel" {...props}/>;
 
 export type DialogProps = Omit<ComponentProps<'dialog'>, 'title'> & {
-  /** Whether the component should include the default styling. Default: false. */
+  /** Whether this component should be unstyled. Default: false. */
   unstyled?: undefined | boolean,
   
   /** Whether the dialog should be displayed as a flat panel (no shadows/borders/rounding). Default: false. */
@@ -80,6 +80,9 @@ export type DialogProps = Omit<ComponentProps<'dialog'>, 'title'> & {
   
   /** Any additional actions to be shown in the dialog. */
   actions?: undefined | React.ReactNode,
+  
+  /** Whether to set autofocus on the close button. Default: false. */
+  autoFocusClose?: undefined | boolean,
 };
 /**
  * The Dialog component displays an interaction with the user, for example a confirmation, or a form to be submitted.
@@ -95,6 +98,7 @@ export const Dialog = Object.assign(
       showCancelAction = true,
       onRequestClose,
       actions,
+      autoFocusClose = false,
       ...propsRest
     } = props;
     
@@ -119,34 +123,32 @@ export const Dialog = Object.assign(
           propsRest.className,
         )}
       >
-        <form>
-          <header className={cx(cl['bk-dialog__header'])}>
-            <H5 className={cx(cl['bk-dialog__header__title'])}>{title}</H5>
-            
-            <div className={cx(cl['bk-dialog__header__actions'])}>
-              {showCloseIcon &&
-                <ActionIcon
-                  autoFocus
-                  label="Close dialog"
-                  tooltip={null}
-                  className={cx(cl['bk-dialog__header-action-close'])}
-                  onPress={onRequestClose}
-                >
-                  <Icon icon="cross"/>
-                </ActionIcon>
-              }
-            </div>
-          </header>
-          
-          <section className={cx(cl['bk-dialog__content'], 'bk-body-text')}>
-            {children}
-          </section>
+        <header className={cx(cl['bk-dialog__header'])}>
+          <H5 className={cx(cl['bk-dialog__header__title'])}>{title}</H5>
           
-          <footer className={cx(cl['bk-dialog__actions'])}>
-            {showCancelAction && <CancelAction/>}
-            {actions}
-          </footer>
-        </form>
+          <div className={cx(cl['bk-dialog__header__actions'])}>
+            {showCloseIcon &&
+              <ActionIcon
+                autoFocus={autoFocusClose}
+                label="Close dialog"
+                tooltip={null}
+                className={cx(cl['bk-dialog__header-action-close'])}
+                onPress={onRequestClose}
+              >
+                <Icon icon="cross"/>
+              </ActionIcon>
+            }
+          </div>
+        </header>
+        
+        <section className={cx(cl['bk-dialog__content'], 'bk-body-text')}>
+          {children}
+        </section>
+        
+        <footer className={cx(cl['bk-dialog__actions'])}>
+          {showCancelAction && <CancelAction/>}
+          {actions}
+        </footer>
       </dialog>
     );
   },
diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index 8faefb40..e2631c3a 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -56,7 +56,9 @@
   }
 }
 
-@mixin dialog-slide-over($entry-dur: 200ms, $exit-dur: 180ms) {
+@mixin dialog-slide-over($entry-dur: 200ms, $exit-dur: 180ms, $origin: right) {
+  $dir: if($origin==right, 1, -1);
+  
   transition-property: overlay, display, translate;
   transition-timing-function: ease-out;
   transition-behavior: allow-discrete;
@@ -67,14 +69,14 @@
   // Entry transition styling
   transition-duration: $entry-dur;
   @starting-style {
-    translate: 80vw 0;
+    translate: ($dir * 80vi) 0;
   }
   
   // Exit transition styling
   &:not([open]) {
     transition-duration: $exit-dur;
     transition-timing-function: ease-in;
-    translate: 80vw 0;
+    translate: ($dir * 80vi) 0;
   }
 }
 
@@ -90,8 +92,8 @@
     // Basic modal positioning
     position: fixed;
     inset: 0;
-    max-width: 100vw;
-    max-height: 100vh;
+    max-width: 100vi;
+    max-height: 100vb;
     
     @include dialog-backdrop(
       $entry-dur: var(--bk-dialog-modal-entry-dur),
@@ -114,23 +116,23 @@
         $scale: var(--bk-dialog-modal-fade-scale),
       );
       
-      max-height: calc(100vh - 5vw); // The larger the viewport width, the more breathing room in height
+      max-height: calc(100vb - 5vi); // The larger the viewport width, the more breathing room in height
       &.bk-dialog-modal--small {
         --bk-dialog-modal-fade-scale: 1.05;
-        max-width: 30vw;
+        max-width: 30vi;
       }
       &.bk-dialog-modal--medium {
         --bk-dialog-modal-fade-scale: 1.04;
-        max-width: 50vw;
+        max-width: 50vi;
       }
       &.bk-dialog-modal--large {
         --bk-dialog-modal-fade-scale: 1.03;
-        max-width: 60vw;
+        max-width: 60vi;
       }
     }
     
     &.bk-dialog-modal--full-screen {
-      // FIXME: test this on mobile for potential overflow/shifting. May need to use `dvh`/`dvw` instead?
+      // FIXME: test this on mobile for potential overflow/shifting. May need to use `dvb`/`dvi` instead?
       inset: 0;
       margin: 0;
       width: auto;
@@ -150,14 +152,24 @@
       width: auto;
       height: auto;
       
-      margin-inline-start: 20vw;
-      
       --bk-dialog-modal-entry-dur: 300ms;
       --bk-dialog-modal-exit-dur: 250ms;
-      @include dialog-slide-over(
-        $entry-dur: var(--bk-dialog-modal-entry-dur),
-        $exit-dur: var(--bk-dialog-modal-exit-dur),
-      );
+      &.bk-dialog-modal--slide-over--left {
+        margin-inline-end: 20vi;
+        @include dialog-slide-over(
+          $entry-dur: var(--bk-dialog-modal-entry-dur),
+          $exit-dur: var(--bk-dialog-modal-exit-dur),
+          $origin: left,
+        );
+      }
+      &.bk-dialog-modal--slide-over--right {
+        margin-inline-start: 20vi;
+        @include dialog-slide-over(
+          $entry-dur: var(--bk-dialog-modal-entry-dur),
+          $exit-dur: var(--bk-dialog-modal-exit-dur),
+          $origin: right,
+        );
+      }
     }
   }
 }
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index c9dea505..7cc94e72 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -2,10 +2,8 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-import * as React from 'react';
 import { classNames as cx, type ComponentProps } from '../../../util/componentUtil.ts';
 
-import { Button } from '../../actions/Button/Button.tsx';
 import { Dialog } from '../../containers/Dialog/Dialog.tsx';
 import { ModalProvider, type ModalProviderProps } from '../ModalProvider/ModalProvider.tsx';
 
@@ -21,6 +19,9 @@ export type DialogModalProps = ComponentProps<typeof Dialog> & {
   /** How to display the modal in the viewport. Default: 'center'. */
   display?: undefined | 'center' | 'full-screen' | 'slide-over',
   
+  /** If `display` is `slide-over`, from which side the modal should originate. */
+  slideOverPosition?: undefined | 'left' | 'right',
+  
   /** The size of the modal. Note: does not apply to full screen modals. */
   size?: undefined | 'small' | 'medium' | 'large',
   
@@ -39,6 +40,7 @@ export const DialogModal = (props: DialogModalProps) => {
     trigger,
     unstyled = false,
     display = 'center',
+    slideOverPosition = 'right',
     size = 'medium',
     ...propsRest
   } = props;
@@ -49,14 +51,18 @@ export const DialogModal = (props: DialogModalProps) => {
         <Dialog
           flat={['full-screen', 'slide-over'].includes(display)}
           {...dialogProps}
+          showCloseIcon
+          autoFocusClose
           onRequestClose={close}
           {...propsRest}
           className={cx(
-            { bk: true },
+            'bk',
             { [cl['bk-dialog-modal']]: !unstyled },
             { [cl['bk-dialog-modal--center']]: display === 'center' },
             { [cl['bk-dialog-modal--full-screen']]: display === 'full-screen' },
             { [cl['bk-dialog-modal--slide-over']]: display === 'slide-over' },
+            { [cl['bk-dialog-modal--slide-over--left']]: slideOverPosition === 'left' },
+            { [cl['bk-dialog-modal--slide-over--right']]: slideOverPosition === 'right' },
             { [cl['bk-dialog-modal--small']]: size === 'small' },
             { [cl['bk-dialog-modal--medium']]: size === 'medium' },
             { [cl['bk-dialog-modal--large']]: size === 'large' },

From cf7a3f9605cb4e2e30c5964c22d659dd2bb7d45d Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 00:14:37 +0100
Subject: [PATCH 17/33] Implement ModalProviderRef.

---
 .../containers/Dialog/Dialog.module.scss      |   1 -
 .../containers/Dialog/Dialog.stories.tsx      |   4 +-
 src/components/containers/Dialog/Dialog.tsx   |  44 ++++----
 .../DialogModal/DialogModal.stories.tsx       |  13 ++-
 .../overlays/DialogModal/DialogModal.tsx      | 100 ++++++++++--------
 .../ModalProvider/ModalProvider.stories.tsx   |  19 ++++
 .../overlays/ModalProvider/ModalProvider.tsx  |  16 ++-
 src/styling/global/reset.scss                 |   4 +
 8 files changed, 127 insertions(+), 74 deletions(-)

diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index 2eb73023..bbbeab6c 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -87,7 +87,6 @@
       
       .bk-dialog__action { --keep: ; }
       .bk-dialog__action--icon { --keep: ; }
-      .bk-dialog__action--button { --keep: ; }
     }
     
     // State: focus
diff --git a/src/components/containers/Dialog/Dialog.stories.tsx b/src/components/containers/Dialog/Dialog.stories.tsx
index 8a534d4d..a5af8adc 100644
--- a/src/components/containers/Dialog/Dialog.stories.tsx
+++ b/src/components/containers/Dialog/Dialog.stories.tsx
@@ -28,9 +28,7 @@ export default {
   args: {
     title: 'Dialog title',
     children: <LoremIpsum paragraphs={3}/>,
-    actions: (
-      <Button variant="primary" label="Submit"/>
-    ),
+    actions: <Dialog.SubmitAction/>,
     onRequestClose: () => {},
   },
 } satisfies Meta<DialogArgs>;
diff --git a/src/components/containers/Dialog/Dialog.tsx b/src/components/containers/Dialog/Dialog.tsx
index dd2d495e..b33c2912 100644
--- a/src/components/containers/Dialog/Dialog.tsx
+++ b/src/components/containers/Dialog/Dialog.tsx
@@ -17,47 +17,43 @@ import cl from './Dialog.module.scss';
 
 export { cl as DialogClassNames };
 
-type ActionIconProps = ComponentProps<typeof Button> & {
-  /** There must be `label` on an icon-only button, for accessibility. */
-  label: Required<ComponentProps<typeof Button>>['label'],
-  
-  /** Optional custom tooltip text, if different from `label`. */
+type ActionProps = ComponentProps<typeof Button> & {
+  /** Optional tooltip text. */
   tooltip?: undefined | ComponentProps<typeof TooltipProvider>['tooltip'],
 };
 /**
- * An action that is rendered as just an icon.
+ * An action button to be displayed in the dialog footer.
  */
-const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
+const Action = ({ tooltip = null, ...buttonProps }: ActionProps) => {
   return (
-    <TooltipProvider compact tooltip={typeof tooltip !== 'undefined' ? tooltip : buttonProps.label}>
-      <Button unstyled
+    <TooltipProvider compact tooltip={typeof tooltip !== 'undefined' ? tooltip : null}>
+      <Button
         {...buttonProps}
-        className={cx(cl['bk-dialog__action'], cl['bk-dialog__action--icon'], buttonProps.className)}
+        className={cx(cl['bk-dialog__action'], buttonProps.className)}
       />
     </TooltipProvider>
   );
 };
 
-type ActionButtonProps = ComponentProps<typeof Button> & {
-  /** Optional tooltip text. */
-  tooltip?: undefined | ComponentProps<typeof TooltipProvider>['tooltip'],
+type ActionIconProps = Omit<ActionProps, 'label'> & {
+  /** There must be `label` on an icon-only button, for accessibility. */
+  label: Required<ComponentProps<typeof Button>>['label'],
 };
 /**
  * An action that is rendered as just an icon.
  */
-const ActionButton = ({ tooltip = null, ...buttonProps }: ActionButtonProps) => {
+const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
   return (
-    <TooltipProvider compact tooltip={typeof tooltip !== 'undefined' ? tooltip : null}>
-      <Button unstyled
-        {...buttonProps}
-        className={cx(cl['bk-dialog__action'], cl['bk-dialog__action--button'], buttonProps.className)}
-      />
-    </TooltipProvider>
+    <Action unstyled
+      {...buttonProps}
+      tooltip={typeof tooltip !== 'undefined' ? tooltip : buttonProps.label}
+      className={cx(cl['bk-dialog__action--icon'], buttonProps.className)}
+    />
   );
 };
 
-const CancelAction = (props: ComponentProps<typeof Button>) =>
-  <Button variant="secondary" label="Cancel" {...props}/>;
+const CancelAction = (props: ActionProps) => <Action variant="secondary" label="Cancel" {...props}/>;
+const SubmitAction = (props: ActionProps) => <Action variant="primary" label="Submit" {...props}/>;
 
 export type DialogProps = Omit<ComponentProps<'dialog'>, 'title'> & {
   /** Whether this component should be unstyled. Default: false. */
@@ -153,7 +149,9 @@ export const Dialog = Object.assign(
     );
   },
   {
-    ActionButton,
+    Action,
+    ActionIcon,
     CancelAction,
+    SubmitAction,
   },
 );
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index f053c3c8..77a2351b 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -49,7 +49,6 @@ export const DialogModalFullScreen: Story = {
   args: {
     display: 'full-screen',
     title: 'Full screen modal dialog',
-    showCloseAction: true,
   },
 };
 
@@ -57,6 +56,16 @@ export const DialogModalSlideOver: Story = {
   args: {
     display: 'slide-over',
     title: 'Slide over modal dialog',
-    showCloseAction: true,
+  },
+};
+
+export const ConfirmationDialog: Story = {
+  args: {
+    trigger: ({ active, activate }) => <Button variant="primary" label="Delete" onPress={activate}/>,
+    display: 'center',
+    size: 'small',
+    title: 'Confirmation',
+    children: <>Are you sure you want to delete this item?</>,
+    actions: <DialogModal.SubmitAction label="Delete" onPress={() => { window.alert('Confirmed'); }}/>,
   },
 };
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 7cc94e72..925d0516 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -13,6 +13,8 @@ import cl from './DialogModal.module.scss';
 export { cl as DialogModalClassNames };
 
 export type DialogModalProps = ComponentProps<typeof Dialog> & {
+  modalRef?: undefined | React.RefObject<null | React.ComponentRef<typeof ModalProvider>>,
+  
   /** Whether this component should be unstyled. */
   unstyled?: undefined | boolean,
   
@@ -34,47 +36,57 @@ export type DialogModalProps = ComponentProps<typeof Dialog> & {
 /**
  * A dialog component displayed as a modal when activating the given trigger.
  */
-export const DialogModal = (props: DialogModalProps) => {
-  const {
-    children,
-    trigger,
-    unstyled = false,
-    display = 'center',
-    slideOverPosition = 'right',
-    size = 'medium',
-    ...propsRest
-  } = props;
-  
-  return (
-    <ModalProvider
-      content={({ close, dialogProps }) =>
-        <Dialog
-          flat={['full-screen', 'slide-over'].includes(display)}
-          {...dialogProps}
-          showCloseIcon
-          autoFocusClose
-          onRequestClose={close}
-          {...propsRest}
-          className={cx(
-            'bk',
-            { [cl['bk-dialog-modal']]: !unstyled },
-            { [cl['bk-dialog-modal--center']]: display === 'center' },
-            { [cl['bk-dialog-modal--full-screen']]: display === 'full-screen' },
-            { [cl['bk-dialog-modal--slide-over']]: display === 'slide-over' },
-            { [cl['bk-dialog-modal--slide-over--left']]: slideOverPosition === 'left' },
-            { [cl['bk-dialog-modal--slide-over--right']]: slideOverPosition === 'right' },
-            { [cl['bk-dialog-modal--small']]: size === 'small' },
-            { [cl['bk-dialog-modal--medium']]: size === 'medium' },
-            { [cl['bk-dialog-modal--large']]: size === 'large' },
-            dialogProps.className,
-            propsRest.className,
-          )}
-        >
-          {children}
-        </Dialog>
-      }
-    >
-      {trigger}
-    </ModalProvider>
-  );
-};
+export const DialogModal = Object.assign(
+  (props: DialogModalProps) => {
+    const {
+      children,
+      modalRef,
+      trigger,
+      unstyled = false,
+      display = 'center',
+      slideOverPosition = 'right',
+      size = 'medium',
+      ...propsRest
+    } = props;
+    
+    return (
+      <ModalProvider
+        ref={modalRef}
+        content={({ close, dialogProps }) =>
+          <Dialog
+            flat={['full-screen', 'slide-over'].includes(display)}
+            {...dialogProps}
+            showCloseIcon
+            autoFocusClose
+            onRequestClose={close}
+            {...propsRest}
+            className={cx(
+              'bk',
+              { [cl['bk-dialog-modal']]: !unstyled },
+              { [cl['bk-dialog-modal--center']]: display === 'center' },
+              { [cl['bk-dialog-modal--full-screen']]: display === 'full-screen' },
+              { [cl['bk-dialog-modal--slide-over']]: display === 'slide-over' },
+              { [cl['bk-dialog-modal--slide-over--left']]: slideOverPosition === 'left' },
+              { [cl['bk-dialog-modal--slide-over--right']]: slideOverPosition === 'right' },
+              { [cl['bk-dialog-modal--small']]: size === 'small' },
+              { [cl['bk-dialog-modal--medium']]: size === 'medium' },
+              { [cl['bk-dialog-modal--large']]: size === 'large' },
+              dialogProps.className,
+              propsRest.className,
+            )}
+          >
+            {children}
+          </Dialog>
+        }
+      >
+        {trigger}
+      </ModalProvider>
+    );
+  },
+  {
+    Action: Dialog.Action,
+    ActionIcon: Dialog.ActionIcon,
+    CancelAction: Dialog.CancelAction,
+    SubmitAction: Dialog.SubmitAction,
+  },
+);
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index 55e1795e..3ae39bfd 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -44,3 +44,22 @@ export const ModalProviderWithBasicDialog: Story = {
     content: ({ close, dialogProps }) => <dialog {...dialogProps}>Content</dialog>,
   },
 };
+
+const ModalProviderWithRefControlled = (props: React.ComponentProps<typeof ModalProvider>) => {
+  const ref = React.useRef<React.ComponentRef<typeof ModalProvider>>(null);
+  
+  React.useEffect(() => {
+    globalThis.setTimeout(() => {
+      ref.current?.activate();
+    }, 1000);
+  });
+  
+  return <ModalProvider ref={ref} {...props}/>;
+};
+export const ModalProviderWithRef: Story = {
+  render: args => <ModalProviderWithRefControlled {...args}/>,
+  args: {
+    children: () => <>Modal will open automatically</>,
+    content: ({ dialogProps }) => <dialog {...dialogProps}>This modal was opened through a ref.</dialog>,
+  }
+};
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index 35ce69c3..ffb6f1b0 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -13,7 +13,14 @@ import cl from './ModalProvider.module.scss';
 export { cl as ModalProviderClassNames };
 
 
+export type ModalProviderRef = {
+  activate: () => void,
+  deactivate: () => void,
+};
+
 export type ModalProviderProps = {
+  ref?: undefined | React.RefObject<null | ModalProviderRef>,
+  
   /** The trigger that activates the modal overlay. */
   children: (triggerProps: { active: boolean, activate: () => void }) => React.ReactNode,
   
@@ -31,10 +38,11 @@ export type ModalProviderProps = {
  */
 export const ModalProvider = (props: ModalProviderProps) => {
   const {
+    ref,
     children,
     content,
     activeDefault = false,
-    exitAnimationDelay = 100_000,
+    exitAnimationDelay = 3000, // ms
   } = props;
   
   const [active, setActiveInternal] = React.useState(activeDefault);
@@ -46,6 +54,7 @@ export const ModalProvider = (props: ModalProviderProps) => {
   }, [setActiveWithDelay]);
   
   const activate = React.useCallback(() => { setActive(true); }, [setActive]);
+  const deactivate = React.useCallback(() => { setActive(false); }, [setActive]);
   const triggerProps = { active, activate };
   
   const dialogProps = useControlledDialog({
@@ -54,6 +63,11 @@ export const ModalProvider = (props: ModalProviderProps) => {
     allowUserClose: true,
   });
   
+  React.useImperativeHandle(ref, () => ({
+    activate,
+    deactivate,
+  }), [activate, deactivate]);
+  
   return (
     <>
       {activeWithDelay && content(dialogProps)}
diff --git a/src/styling/global/reset.scss b/src/styling/global/reset.scss
index ab26f7ee..129e5c55 100644
--- a/src/styling/global/reset.scss
+++ b/src/styling/global/reset.scss
@@ -58,6 +58,10 @@
     all: unset;
     display: revert;
     box-sizing: border-box;
+    
+    // Issue: if the parent has `user-select: none` (e.g. button), then the dialog will inherit this by default.
+    // In the future, if `contain: user-select` is implemented, we could use that instead.
+    user-select: text;
   }
   
   // Re-apply a few sensible defaults for dialogs. For reference, see the default user agent styling rules here:

From 5635351093c4cc50e7cf419c98c882d6d4bfecbd Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 00:22:35 +0100
Subject: [PATCH 18/33] Disable DialogModal animations when user has
 prefers-reduced-motion.

---
 .../overlays/DialogModal/DialogModal.module.scss     | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index e2631c3a..bf680d7a 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -16,7 +16,7 @@
     backdrop-filter: blur($blur) opacity(1);
     
     // Entry transition styling
-    transition-duration: $entry-dur;
+    @media (prefers-reduced-motion: no-preference) { transition-duration: $entry-dur; }
     @starting-style {
       background-color: transparent;
       backdrop-filter: blur($blur) opacity(0);
@@ -25,7 +25,7 @@
   // Exit transition styling
   // Note: cannot nest the following inside `::backdrop`, since `:not()` needs to apply to the dialog not `::backdrop`
   &:not([open])::backdrop {
-    transition-duration: $exit-dur;
+    @media (prefers-reduced-motion: no-preference) { transition-duration: $exit-dur; }
     background-color: transparent;
     backdrop-filter: blur($blur) opacity(0);
   }
@@ -41,7 +41,7 @@
   scale: 1;
   
   // Entry transition styling
-  transition-duration: $entry-dur;
+  @media (prefers-reduced-motion: no-preference) { transition-duration: $entry-dur; }
   @starting-style {
     opacity: 0;
     scale: $scale;
@@ -49,7 +49,7 @@
   
   // Exit transition styling
   &:not([open]) {
-    transition-duration: $exit-dur;
+    @media (prefers-reduced-motion: no-preference) { transition-duration: $exit-dur; }
     transition-timing-function: ease-in;
     opacity: 0;
     scale: calc(1 - (($scale - 1) * 0.2)); // Multiply by 0.2 to make the scale out effect a bit more subtle
@@ -67,14 +67,14 @@
   translate: 0;
   
   // Entry transition styling
-  transition-duration: $entry-dur;
+  @media (prefers-reduced-motion: no-preference) { transition-duration: $entry-dur; }
   @starting-style {
     translate: ($dir * 80vi) 0;
   }
   
   // Exit transition styling
   &:not([open]) {
-    transition-duration: $exit-dur;
+    @media (prefers-reduced-motion: no-preference) { transition-duration: $exit-dur; }
     transition-timing-function: ease-in;
     translate: ($dir * 80vi) 0;
   }

From 6c2eb635bb0951873b04b3d91cbcfe8d0903af3d Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 14:05:49 +0100
Subject: [PATCH 19/33] Fix Dialog footer 1px bleed through.

---
 src/components/containers/Dialog/Dialog.module.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index bbbeab6c..17a0ef4f 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -70,10 +70,10 @@
     
     .bk-dialog__actions {
       position: sticky;
-      bottom: 0;
+      bottom: -1px; // -1px to prevent bleed through due to pixel rounding
       z-index: 1;
       
-      padding-block: calc(bk.$spacing-7 / 2) bk.$spacing-9;
+      padding-block: calc(bk.$spacing-7 / 2) calc(bk.$spacing-9 + 1px); // 1px to compensate for `bottom: -1px`
       padding-inline: var(--bk-dialog-padding-inline);
       // In Figma, actions have an indent. But that might be only if the content itself has an indent, need to check.
       //padding-inline-start: calc(var(--bk-dialog-padding-inline) + bk.$spacing-8);

From bb0be0bf764555560ea87d47991824355ffa52b8 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 16:33:18 +0100
Subject: [PATCH 20/33] Refactor useControlledDialog -> useModalDialog.

---
 .../DialogModal/DialogModal.module.scss       |  10 +-
 .../DialogModal/DialogModal.stories.tsx       |  25 ++++
 .../overlays/DialogModal/DialogModal.tsx      |  32 +++--
 .../ModalProvider/ModalProvider.stories.tsx   |  21 ++--
 .../overlays/ModalProvider/ModalProvider.tsx  | 114 +++++++++++-------
 ...eControlledDialog.ts => useModalDialog.ts} |  94 ++++++++++-----
 6 files changed, 197 insertions(+), 99 deletions(-)
 rename src/components/util/Dialog/{useControlledDialog.ts => useModalDialog.ts} (54%)

diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index bf680d7a..3bda69a5 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -116,18 +116,20 @@
         $scale: var(--bk-dialog-modal-fade-scale),
       );
       
-      max-height: calc(100vb - 5vi); // The larger the viewport width, the more breathing room in height
+      // The larger the viewport width, the more breathing room in height
+      max-height: calc(100vb - min(5vi, 3lh));
+      
       &.bk-dialog-modal--small {
         --bk-dialog-modal-fade-scale: 1.05;
-        max-width: 30vi;
+        max-width: 60ch;
       }
       &.bk-dialog-modal--medium {
         --bk-dialog-modal-fade-scale: 1.04;
-        max-width: 50vi;
+        max-width: 100ch;
       }
       &.bk-dialog-modal--large {
         --bk-dialog-modal-fade-scale: 1.03;
-        max-width: 60vi;
+        max-width: 140ch;
       }
     }
     
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 77a2351b..1c4a16d9 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -59,6 +59,31 @@ export const DialogModalSlideOver: Story = {
   },
 };
 
+const DialogModalAutoOpen = (props: React.ComponentProps<typeof DialogModal>) => {
+  const ref = DialogModal.useModalRef(null);
+  
+  // biome-ignore lint/correctness/useExhaustiveDependencies: want to only trigger this once
+    React.useEffect(() => {
+    globalThis.setTimeout(() => {
+      ref.current?.activate();
+    }, 2000);
+  }, []);
+  
+  return <DialogModal modalRef={ref} {...props}/>;
+};
+export const DialogModalWithRef: Story = {
+  args: {
+    trigger: undefined,
+    children: 'This modal was automatically opened through a ref.',
+  },
+  render: (args) => (
+    <>
+      A modal will automatically open after 2 seconds.
+      <DialogModalAutoOpen {...args}/>
+    </>
+  ),
+};
+
 export const ConfirmationDialog: Story = {
   args: {
     trigger: ({ active, activate }) => <Button variant="primary" label="Delete" onPress={activate}/>,
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 925d0516..5a8ae634 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -2,6 +2,7 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+import { mergeRefs } from '../../../util/reactUtil.ts';
 import { classNames as cx, type ComponentProps } from '../../../util/componentUtil.ts';
 
 import { Dialog } from '../../containers/Dialog/Dialog.tsx';
@@ -10,10 +11,12 @@ import { ModalProvider, type ModalProviderProps } from '../ModalProvider/ModalPr
 import cl from './DialogModal.module.scss';
 
 
+type Test = React.ComponentProps<typeof Dialog>['ref'];
+
 export { cl as DialogModalClassNames };
 
 export type DialogModalProps = ComponentProps<typeof Dialog> & {
-  modalRef?: undefined | React.RefObject<null | React.ComponentRef<typeof ModalProvider>>,
+  modalRef?: undefined | React.Ref<React.ComponentRef<typeof ModalProvider>>,
   
   /** Whether this component should be unstyled. */
   unstyled?: undefined | boolean,
@@ -27,8 +30,14 @@ export type DialogModalProps = ComponentProps<typeof Dialog> & {
   /** The size of the modal. Note: does not apply to full screen modals. */
   size?: undefined | 'small' | 'medium' | 'large',
   
-  /** The modal trigger. */
-  trigger: ModalProviderProps['children'],
+  /**
+   * A modal trigger to render. Will be passed an `activate` callback to open the modal. Optional, if not specified
+   * you can manually trigger the modal through `modalRef` instead.
+   */
+  trigger?: undefined | ModalProviderProps['children'],
+  
+  /** Whether to allow users to close the dialog manually. */
+  allowUserClose?: undefined | boolean,
   
   /** Any additional props to pass to the modal provider. */
   providerProps?: undefined | Omit<ModalProviderProps, 'children'>,
@@ -41,24 +50,26 @@ export const DialogModal = Object.assign(
     const {
       children,
       modalRef,
-      trigger,
       unstyled = false,
       display = 'center',
       slideOverPosition = 'right',
       size = 'medium',
+      trigger = () => null,
+      allowUserClose = true,
+      providerProps,
       ...propsRest
     } = props;
     
     return (
       <ModalProvider
-        ref={modalRef}
-        content={({ close, dialogProps }) =>
+        allowUserClose={allowUserClose}
+        dialog={({ close, dialogProps }) =>
           <Dialog
             flat={['full-screen', 'slide-over'].includes(display)}
             {...dialogProps}
-            showCloseIcon
-            autoFocusClose
-            onRequestClose={close}
+            showCloseIcon={allowUserClose}
+            autoFocusClose={allowUserClose}
+            onRequestClose={allowUserClose ? close : undefined}
             {...propsRest}
             className={cx(
               'bk',
@@ -78,12 +89,15 @@ export const DialogModal = Object.assign(
             {children}
           </Dialog>
         }
+        {...providerProps}
+        ref={mergeRefs(modalRef, providerProps?.ref)}
       >
         {trigger}
       </ModalProvider>
     );
   },
   {
+    useModalRef: ModalProvider.useRef,
     Action: Dialog.Action,
     ActionIcon: Dialog.ActionIcon,
     CancelAction: Dialog.CancelAction,
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index 3ae39bfd..c6a8c05e 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -33,7 +33,7 @@ export default {
 export const ModalProviderStandard: Story = {
   args: {
     children: ({ activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
-    content: ({ close, dialogProps }) =>
+    dialog: ({ close, dialogProps }) =>
       <Dialog {...dialogProps} title="Modal dialog" onRequestClose={close}><LoremIpsum paragraphs={5}/></Dialog>,
   },
 };
@@ -41,25 +41,26 @@ export const ModalProviderStandard: Story = {
 export const ModalProviderWithBasicDialog: Story = {
   args: {
     children: ({ activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
-    content: ({ close, dialogProps }) => <dialog {...dialogProps}>Content</dialog>,
+    dialog: ({ close, dialogProps }) => <dialog {...dialogProps}>Content</dialog>,
   },
 };
 
-const ModalProviderWithRefControlled = (props: React.ComponentProps<typeof ModalProvider>) => {
-  const ref = React.useRef<React.ComponentRef<typeof ModalProvider>>(null);
+const ModalProviderAutoOpen = (props: React.ComponentProps<typeof ModalProvider>) => {
+  const ref = ModalProvider.useRef(null);
   
-  React.useEffect(() => {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: want to only trigger this once
+    React.useEffect(() => {
     globalThis.setTimeout(() => {
       ref.current?.activate();
-    }, 1000);
-  });
+    }, 2000);
+  }, []);
   
   return <ModalProvider ref={ref} {...props}/>;
 };
 export const ModalProviderWithRef: Story = {
-  render: args => <ModalProviderWithRefControlled {...args}/>,
+  render: args => <ModalProviderAutoOpen {...args}/>,
   args: {
-    children: () => <>Modal will open automatically</>,
-    content: ({ dialogProps }) => <dialog {...dialogProps}>This modal was opened through a ref.</dialog>,
+    children: () => <>Modal will open automatically after 2 seconds.</>,
+    dialog: ({ dialogProps }) => <dialog {...dialogProps}>This modal was opened through a ref.</dialog>,
   }
 };
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index ffb6f1b0..404552cf 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -5,7 +5,7 @@
 import * as React from 'react';
 
 import { useDebounce } from '../../../util/hooks/useDebounce.ts';
-import { useControlledDialog, type ControlledDialogProps } from '../../util/Dialog/useControlledDialog.ts';
+import { useModalDialog, type ModalDialogProps } from '../../util/Dialog/useModalDialog.ts';
 
 import cl from './ModalProvider.module.scss';
 
@@ -13,65 +13,87 @@ import cl from './ModalProvider.module.scss';
 export { cl as ModalProviderClassNames };
 
 
-export type ModalProviderRef = {
+// Use an active state, but with a delay in unmounting to allow exit transitions time to animate
+export const useActiveWithUnmountDelay = (
+  activeDefault: boolean | (() => boolean),
+  unmountDelay = 3000, /*ms*/
+): [boolean, boolean, React.Dispatch<React.SetStateAction<boolean>>] => {
+  const [active, setActive] = React.useState(activeDefault);
+  const [shouldMount, setShouldMount] = useDebounce(active, unmountDelay);
+  
+  const setActiveWithUnmountDelay = React.useCallback((active: React.SetStateAction<boolean>) => {
+    setActive(active);
+    if (active) { setShouldMount(true); } // Skip the delay when activating (should only be for deactivation)
+  }, [setShouldMount]);
+  
+  React.useDebugValue(`Active: ${active} / Mounted: ${shouldMount}`);
+  
+  return [active, shouldMount, setActiveWithUnmountDelay];
+};
+
+export type ModalRef = {
+  active: boolean,
   activate: () => void,
   deactivate: () => void,
 };
 
+export const useRef = React.useRef<ModalRef>;
+
 export type ModalProviderProps = {
-  ref?: undefined | React.RefObject<null | ModalProviderRef>,
+  ref?: undefined | React.Ref<ModalRef>,
   
   /** The trigger that activates the modal overlay. */
   children: (triggerProps: { active: boolean, activate: () => void }) => React.ReactNode,
   
-  /** The content to be shown in the modal overlay. */
-  content: (props: ControlledDialogProps) => React.ReactNode,
+  /** The dialog to be shown in the modal overlay. */
+  dialog: (props: ModalDialogProps) => React.ReactNode,
   
   /** Whether the modal should be active by default. */
   activeDefault?: undefined | boolean,
   
-  /** How long to keep the dialog in the DOM for exit animation purposes. Default: 2 seconds. */
-  exitAnimationDelay?: undefined | number,
+  /** Whether to allow users to close the modal manually. */
+  allowUserClose?: undefined | boolean,
+  
+  /** How long to keep the dialog in the DOM for exit animation purposes. Default: 3 seconds. */
+  unmountDelay?: undefined | number,
 };
 /**
  * Provider around a trigger (e.g. button) to display a modal overlay on trigger activation.
  */
-export const ModalProvider = (props: ModalProviderProps) => {
-  const {
-    ref,
-    children,
-    content,
-    activeDefault = false,
-    exitAnimationDelay = 3000, // ms
-  } = props;
-  
-  const [active, setActiveInternal] = React.useState(activeDefault);
-  const [activeWithDelay, setActiveWithDelay] = useDebounce(active, exitAnimationDelay);
-  
-  const setActive = React.useCallback((active: boolean) => {
-    setActiveInternal(active);
-    if (active) { setActiveWithDelay(true); } // Skip the delay when activating (should only be for deactivation)
-  }, [setActiveWithDelay]);
-  
-  const activate = React.useCallback(() => { setActive(true); }, [setActive]);
-  const deactivate = React.useCallback(() => { setActive(false); }, [setActive]);
-  const triggerProps = { active, activate };
-  
-  const dialogProps = useControlledDialog({
-    active,
-    onActiveStateChange: setActive,
-    allowUserClose: true,
-  });
-  
-  React.useImperativeHandle(ref, () => ({
-    activate,
-    deactivate,
-  }), [activate, deactivate]);
-  
-  return (
-    <>
-      {activeWithDelay && content(dialogProps)}
-      {children(triggerProps)}
-    </>
-  );
-};
+export const ModalProvider = Object.assign(
+  (props: ModalProviderProps) => {
+    const {
+      ref,
+      children,
+      dialog,
+      activeDefault = false,
+      allowUserClose = false,
+      unmountDelay = 3000, // ms
+    } = props;
+    
+    const [active, shouldMount, setActive] = useActiveWithUnmountDelay(activeDefault, unmountDelay);
+    
+    const modalRef = React.useMemo<ModalRef>(() => ({
+      active,
+      activate: () => { setActive(true); },
+      deactivate: () => { setActive(false); },
+    }), [active, setActive]);
+    
+    React.useImperativeHandle(ref, () => modalRef, [modalRef]);
+    
+    const dialogProps = useModalDialog(modalRef, {
+      allowUserClose,
+      shouldCloseOnBackdropClick: allowUserClose,
+    });
+    
+    return (
+      <>
+        {shouldMount && dialog(dialogProps)}
+        {children(modalRef)}
+      </>
+    );
+  },
+  {
+    useRef,
+  },
+);
diff --git a/src/components/util/Dialog/useControlledDialog.ts b/src/components/util/Dialog/useModalDialog.ts
similarity index 54%
rename from src/components/util/Dialog/useControlledDialog.ts
rename to src/components/util/Dialog/useModalDialog.ts
index 3ecd165b..54a93213 100644
--- a/src/components/util/Dialog/useControlledDialog.ts
+++ b/src/components/util/Dialog/useModalDialog.ts
@@ -5,41 +5,46 @@
 import * as React from 'react';
 
 
-export type UseControlledDialogArgs = {
-  /** Whether the dialog is currently active. */
+export type ModalDialogController = {
+  /** Whether the dialog should be active. */
   active: boolean,
-  
-  /** A callback that will be called when the dialog changes active state. */
-  onActiveStateChange: (active: boolean) => void,
-  
+  /** Notify that the dialog has been opened. Change must be respected (otherwise no longer in sync). */
+  activate: () => void,
+  /** Notify that the dialog has been closed. Change must be respected (otherwise no longer in sync). */
+  deactivate: () => void,
+};
+
+export type UseModalDialogOptions = {
   /**
    * Whether to allow the user to close the modal through the browser (e.g. with the Escape key). Disabling this may
-   * be useful in cases where we need the user to stay in the modal (e.g. pending confirmation, pending form submit).
+   * be useful in cases where we need the user to stay in the modal (e.g. form validation, mandatory onboarding flows).
+   * Note: closing cannot be always be prevented (e.g. browser may force the dialog to close, or closed through JS).
    */
   allowUserClose?: undefined | boolean,
   
-  /** Whether the user clicking the backdrop should close the modal. */
+  /** Whether the user clicking the backdrop should close the modal. Only valid if `allowUserClose` is true. */
   shouldCloseOnBackdropClick?: undefined | boolean,
 };
 
-export type ControlledDialogProps = {
+export type ModalDialogProps = {
   close: () => void,
   dialogProps: React.ComponentProps<'dialog'>,
 };
 
-/**
- * Control the activation state of the given `<dialog>` element through the given `active` boolean.
+/*
+ * A utility hook to control the state of a <dialog> element used as a modal (with `.showModal()`).
  */
-export const useControlledDialog = (args: UseControlledDialogArgs): ControlledDialogProps => {
+export const useModalDialog = (
+  controller: ModalDialogController,
+  options: UseModalDialogOptions,
+): ModalDialogProps => {
   const {
-    active,
-    onActiveStateChange,
     allowUserClose = true,
     shouldCloseOnBackdropClick = true,
-  } = args;
+  } = options;
   
   const dialogRef = React.useRef<HTMLDialogElement>(null);
-  //const lastActiveElementRef = React.useRef<Element>(null);
+  //const lastActiveElementRef = React.useRef<Element>(null); // Note: browsers track this automatically now
   
   const requestDialogClose = React.useCallback(() => {
     const dialog = dialogRef.current;
@@ -55,26 +60,53 @@ export const useControlledDialog = (args: UseControlledDialogArgs): ControlledDi
   // Sync active state with <dialog> DOM state
   React.useEffect(() => {
     const dialog = dialogRef.current;
-    if (!dialog) { return; }
+    if (!dialog) { return; } // Nothing to sync with
     
-    const isDialogOpen = dialog.matches(':modal');
-    if (active && !isDialogOpen) {
+    const isDialogOpenModal = dialog.open && dialog.matches(':modal');
+    
+    if (controller.active && !isDialogOpenModal) { // Should be active but isn't
       // Save a reference to the last focused element before opening the modal
       //lastActiveElementRef.current = document.activeElement;
       
       try {
-        dialog.open = false; // Make sure the <dialog> does not already have a non-modal `open`
+        dialog.open = false; // Make sure the dialog is not open as a non-modal (i.e. through `.show()`)
         dialog.showModal();
       } catch (error: unknown) {
         console.error(`Unable to open modal dialog`, error);
-        onActiveStateChange(false);
+        controller.deactivate();
       }
-    } else if (!active && isDialogOpen) {
-      dialog.close();
+    } else if (!controller.active && isDialogOpenModal) { // Should not be active but is
+      try {
+        dialog.close();
+      } catch (error: unknown) {
+        console.error(`Unable to close modal dialog`, error);
+        controller.activate();
+      }
+    }
+  }, [controller]);
+  
+  // The `beforetoggle` event can be used to detect when a modal opens. Note: browser support is poor currently, but
+  // it's okay since we generally control the activation, not the user. In non-supporting browsers, if someone were to
+  // // manually call `.showModal()` through devtools they could potentially cause a desync.
+  // https://caniuse.com/mdn-api_htmlelement_toggle_event_dialog_elements
+  const handleDialogBeforeToggle = React.useCallback((event: React.ToggleEvent<HTMLDialogElement>) => {
+    if (event.newState === 'open') {
+      controller.activate();
+    }
+  }, [controller]);
+  
+  // Handle dialog `cancel` event. This event is called when the user requests the dialog to close (e.g. with Escape
+  // key). Can be canceled, though browsers do not always respect the cancelation (e.g. Chrome still closes when the
+  // Escape key is hit twice).
+  // https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close_event
+  const handleDialogCancel = React.useCallback((event: React.SyntheticEvent<HTMLDialogElement>) => {
+    if (!allowUserClose) {
+      event.preventDefault();
     }
-  }, [active, onActiveStateChange]);
+  }, [allowUserClose]);
   
-  // Handle dialog `close` event
+  // Handle dialog `close` event. This event is called when the dialog has already been closed (cannot be canceled).
+  // https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close_event
   const handleDialogClose = React.useCallback(() => {
     /*
     // XXX This is probably not necessary, browsers do this out of the box already
@@ -85,8 +117,8 @@ export const useControlledDialog = (args: UseControlledDialogArgs): ControlledDi
     }
     */
     
-    onActiveStateChange(false); // Sync with the consumer
-  }, [onActiveStateChange]);
+    controller.deactivate(); // Sync with the controller
+  }, [controller]);
   
   // Handle dialog `click` event
   const handleDialogClick = React.useCallback((event: React.MouseEvent<HTMLDialogElement>) => {
@@ -108,9 +140,9 @@ export const useControlledDialog = (args: UseControlledDialogArgs): ControlledDi
     }
     
     if (allowUserClose && shouldCloseOnBackdropClick && isClickOnBackdrop) {
-      dialog.close();
+      controller.deactivate();
     }
-  }, [allowUserClose, shouldCloseOnBackdropClick]);
+  }, [controller, allowUserClose, shouldCloseOnBackdropClick]);
   
   // Handle dialog `keydown` event
   const handleDialogKeyDown = React.useCallback((event: React.KeyboardEvent<HTMLDialogElement>) => {
@@ -123,8 +155,10 @@ export const useControlledDialog = (args: UseControlledDialogArgs): ControlledDi
     close: requestDialogClose,
     dialogProps: {
       ref: dialogRef,
-      open: undefined, // Leave the `open` attribute to the browser to manage
+      open: undefined, // Do not set `open`, leave it to the browser to manage automatically
       
+      onBeforeToggle: handleDialogBeforeToggle,
+      onCancel: handleDialogCancel,
       onClose: handleDialogClose,
       // Note: we don't need keyboard accessibility for this `onClick`, the backdrop is not (and should not be) an
       // interactive element. This is a visual only convenience, screen readers should use the other close mechanisms.

From 4fe0d9fb1e13bbc041bcf8ad72abda752174253d Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 17:39:46 +0100
Subject: [PATCH 21/33] Implement useModalRefWithSubject().

---
 .../DialogModal/DialogModal.stories.tsx       | 47 +++++++++++++++--
 .../overlays/DialogModal/DialogModal.tsx      | 50 +++++++++++++++----
 .../overlays/ModalProvider/ModalProvider.tsx  |  2 +-
 src/typography/BodyText/BodyText.mixins.scss  |  2 +-
 4 files changed, 84 insertions(+), 17 deletions(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 1c4a16d9..f45888c6 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -24,7 +24,7 @@ export default {
   argTypes: {},
   args: {
     title: 'Modal dialog',
-    trigger: ({ active, activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
+    trigger: ({ activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
     children: <LoremIpsum paragraphs={15}/>,
   },
   render: (args) => <><LoremIpsum paragraphs={2}/> <DialogModal {...args}/> <LoremIpsum paragraphs={2}/></>,
@@ -33,6 +33,19 @@ export default {
 
 export const DialogModalStandard: Story = {};
 
+export const DialogModalNoncloseable: Story = {
+  args: {
+    activeDefault: true,
+    allowUserClose: false,
+    children: ({ close }) => (
+      <article className="bk-body-text">
+        <p>It should not be possible to close this dialog, except through the following button:</p>
+        <p><Button variant="primary" label="Force close" onPress={close}/></p>
+      </article>
+    ),
+  },
+};
+
 export const DialogModalSmall: Story = {
   args: {
     size: 'small',
@@ -59,7 +72,7 @@ export const DialogModalSlideOver: Story = {
   },
 };
 
-const DialogModalAutoOpen = (props: React.ComponentProps<typeof DialogModal>) => {
+const DialogModalControlledWithRef = (props: React.ComponentProps<typeof DialogModal>) => {
   const ref = DialogModal.useModalRef(null);
   
   // biome-ignore lint/correctness/useExhaustiveDependencies: want to only trigger this once
@@ -79,14 +92,40 @@ export const DialogModalWithRef: Story = {
   render: (args) => (
     <>
       A modal will automatically open after 2 seconds.
-      <DialogModalAutoOpen {...args}/>
+      <DialogModalControlledWithRef {...args}/>
     </>
   ),
 };
 
+const DialogModalControlledWithSubject = (props: React.ComponentProps<typeof DialogModal>) => {
+  type Subject = { name: string };
+  const modal = DialogModal.useModalRefWithSubject<null | Subject>(null);
+  
+  return (
+    <article className="bk-body-text">
+      {modal.subject &&
+        <DialogModal {...props} modalRef={modal.modalRef} title={modal.subject.name}>
+          Details about {modal.subject.name} here.
+        </DialogModal>
+      }
+      
+      <p>A single details modal will be used, filled in with the subject based on which name was pressed.</p>
+      
+      <p><Button variant="primary" label="Open: Alice" onPress={() => { modal.activateWith({ name: 'Alice' }); }}/></p>
+      <p><Button variant="primary" label="Open: Bob" onPress={() => { modal.activateWith({ name: 'Bob' }); }}/></p>
+    </article>
+  );
+};
+export const DialogModalWithSubject: Story = {
+  args: {
+    trigger: undefined,
+  },
+  render: (args) => <DialogModalControlledWithSubject {...args}/>,
+};
+
 export const ConfirmationDialog: Story = {
   args: {
-    trigger: ({ active, activate }) => <Button variant="primary" label="Delete" onPress={activate}/>,
+    trigger: ({ activate }) => <Button variant="primary" label="Delete" onPress={activate}/>,
     display: 'center',
     size: 'small',
     title: 'Confirmation',
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 5a8ae634..5e699d3e 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -2,8 +2,10 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+import * as React from 'react';
+import { flushSync } from 'react-dom';
 import { mergeRefs } from '../../../util/reactUtil.ts';
-import { classNames as cx, type ComponentProps } from '../../../util/componentUtil.ts';
+import { classNames as cx } from '../../../util/componentUtil.ts';
 
 import { Dialog } from '../../containers/Dialog/Dialog.tsx';
 import { ModalProvider, type ModalProviderProps } from '../ModalProvider/ModalProvider.tsx';
@@ -11,16 +13,35 @@ import { ModalProvider, type ModalProviderProps } from '../ModalProvider/ModalPr
 import cl from './DialogModal.module.scss';
 
 
-type Test = React.ComponentProps<typeof Dialog>['ref'];
-
 export { cl as DialogModalClassNames };
 
-export type DialogModalProps = ComponentProps<typeof Dialog> & {
-  modalRef?: undefined | React.Ref<React.ComponentRef<typeof ModalProvider>>,
+export const useModalRefWithSubject = <S,>(subjectInitial: S | (() => S), activeInitial = false) => {
+  const modalRef = ModalProvider.useRef(null);
+  const [subject, setSubject] = React.useState(subjectInitial);
+  
+  return {
+    modalRef,
+    subject,
+    activateWith: (subject: S | (() => S)) => {
+      // Use flushSync() to force the modal to render, in case the modal rendering is conditional
+      // on the subject being set.
+      flushSync(() => { setSubject(subject); });
+      
+      modalRef.current?.activate();
+    },
+  };
+};
+
+export type DialogModalProps = Omit<React.ComponentProps<typeof Dialog>, 'children'> & {
+  /** Content of the modal. If a function, will be passed a dialog controller. */
+  children?: React.ReactNode | ModalProviderProps['dialog'],
   
   /** Whether this component should be unstyled. */
   unstyled?: undefined | boolean,
   
+  /** Whether the modal should be active by default. Default: false. */
+  activeDefault?: undefined | boolean,
+  
   /** How to display the modal in the viewport. Default: 'center'. */
   display?: undefined | 'center' | 'full-screen' | 'slide-over',
   
@@ -39,6 +60,9 @@ export type DialogModalProps = ComponentProps<typeof Dialog> & {
   /** Whether to allow users to close the dialog manually. */
   allowUserClose?: undefined | boolean,
   
+  /** A reference to the modal, for imperative control. */
+  modalRef?: undefined | React.Ref<React.ComponentRef<typeof ModalProvider>>,
+  
   /** Any additional props to pass to the modal provider. */
   providerProps?: undefined | Omit<ModalProviderProps, 'children'>,
 };
@@ -49,27 +73,30 @@ export const DialogModal = Object.assign(
   (props: DialogModalProps) => {
     const {
       children,
-      modalRef,
       unstyled = false,
+      activeDefault = false,
       display = 'center',
       slideOverPosition = 'right',
       size = 'medium',
       trigger = () => null,
       allowUserClose = true,
+      modalRef,
       providerProps,
       ...propsRest
     } = props;
     
     return (
       <ModalProvider
+        activeDefault={activeDefault}
         allowUserClose={allowUserClose}
-        dialog={({ close, dialogProps }) =>
+        dialog={dialogController =>
           <Dialog
             flat={['full-screen', 'slide-over'].includes(display)}
-            {...dialogProps}
+            {...dialogController.dialogProps}
             showCloseIcon={allowUserClose}
             autoFocusClose={allowUserClose}
-            onRequestClose={allowUserClose ? close : undefined}
+            showCancelAction={allowUserClose}
+            onRequestClose={allowUserClose ? dialogController.close : undefined}
             {...propsRest}
             className={cx(
               'bk',
@@ -82,11 +109,11 @@ export const DialogModal = Object.assign(
               { [cl['bk-dialog-modal--small']]: size === 'small' },
               { [cl['bk-dialog-modal--medium']]: size === 'medium' },
               { [cl['bk-dialog-modal--large']]: size === 'large' },
-              dialogProps.className,
+              dialogController.dialogProps.className,
               propsRest.className,
             )}
           >
-            {children}
+            {typeof children === 'function' ? children(dialogController) : children}
           </Dialog>
         }
         {...providerProps}
@@ -98,6 +125,7 @@ export const DialogModal = Object.assign(
   },
   {
     useModalRef: ModalProvider.useRef,
+    useModalRefWithSubject,
     Action: Dialog.Action,
     ActionIcon: Dialog.ActionIcon,
     CancelAction: Dialog.CancelAction,
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index 404552cf..ab5e8013 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -48,7 +48,7 @@ export type ModalProviderProps = {
   /** The dialog to be shown in the modal overlay. */
   dialog: (props: ModalDialogProps) => React.ReactNode,
   
-  /** Whether the modal should be active by default. */
+  /** Whether the modal should be active by default. Default: false. */
   activeDefault?: undefined | boolean,
   
   /** Whether to allow users to close the modal manually. */
diff --git a/src/typography/BodyText/BodyText.mixins.scss b/src/typography/BodyText/BodyText.mixins.scss
index 946e3a05..ddd48f2e 100644
--- a/src/typography/BodyText/BodyText.mixins.scss
+++ b/src/typography/BodyText/BodyText.mixins.scss
@@ -221,7 +221,7 @@
     }
   }
   
-  > :first-child {
+  > :nth-child(1 of :not([hidden], dialog)) {
     margin-block-start: 0;
   }
 }

From a724071fbd174df0a85256270eba3291a3454ba0 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 19:41:06 +0100
Subject: [PATCH 22/33] Implement DialogModal.useConfirmationModal()

---
 src/components/containers/Dialog/Dialog.tsx   | 10 ++-
 .../DialogModal/DialogModal.stories.tsx       | 44 ++++++++---
 .../overlays/DialogModal/DialogModal.tsx      | 74 ++++++++++++++-----
 3 files changed, 97 insertions(+), 31 deletions(-)

diff --git a/src/components/containers/Dialog/Dialog.tsx b/src/components/containers/Dialog/Dialog.tsx
index b33c2912..ed410973 100644
--- a/src/components/containers/Dialog/Dialog.tsx
+++ b/src/components/containers/Dialog/Dialog.tsx
@@ -141,10 +141,12 @@ export const Dialog = Object.assign(
           {children}
         </section>
         
-        <footer className={cx(cl['bk-dialog__actions'])}>
-          {showCancelAction && <CancelAction/>}
-          {actions}
-        </footer>
+        {(showCancelAction || actions) &&
+          <footer className={cx(cl['bk-dialog__actions'])}>
+            {showCancelAction && <CancelAction/>}
+            {actions}
+          </footer>
+        }
       </dialog>
     );
   },
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index f45888c6..63d57504 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -99,12 +99,12 @@ export const DialogModalWithRef: Story = {
 
 const DialogModalControlledWithSubject = (props: React.ComponentProps<typeof DialogModal>) => {
   type Subject = { name: string };
-  const modal = DialogModal.useModalRefWithSubject<null | Subject>(null);
+  const modal = DialogModal.useModalWithSubject<null | Subject>(null);
   
   return (
     <article className="bk-body-text">
       {modal.subject &&
-        <DialogModal {...props} modalRef={modal.modalRef} title={modal.subject.name}>
+        <DialogModal {...modal.props} {...props} title={modal.subject.name}>
           Details about {modal.subject.name} here.
         </DialogModal>
       }
@@ -123,13 +123,39 @@ export const DialogModalWithSubject: Story = {
   render: (args) => <DialogModalControlledWithSubject {...args}/>,
 };
 
-export const ConfirmationDialog: Story = {
+const DialogModalControlledConfirmation = (props: React.ComponentProps<typeof DialogModal>) => {
+  type Subject = { name: string };
+  const deleteConfirmer = DialogModal.useConfirmationModal<null | Subject>(null, {
+    onConfirm() { globalThis.alert('Confirmed'); },
+    onCancel() { globalThis.alert('Canceled'); },
+  });
+  
+  return (
+    <article className="bk-body-text">
+      {deleteConfirmer.subject &&
+        <DialogModal {...deleteConfirmer.props} {...props} title={deleteConfirmer.subject.name}>
+          Are you sure you want to delete "{deleteConfirmer.subject.name}"?
+        </DialogModal>
+      }
+      
+      <p>A single details modal will be used, filled in with the subject based on which name was pressed.</p>
+      
+      <p>
+        <Button variant="primary" label="Delete Item 1"
+          onPress={() => { deleteConfirmer.activateWith({ name: 'Item 1' }); }}
+        />
+      </p>
+      <p>
+        <Button variant="primary" label="Delete Item 2"
+          onPress={() => { deleteConfirmer.activateWith({ name: 'Item 2' }); }}
+        />
+      </p>
+    </article>
+  );
+};
+export const DialogModalConfirmation: Story = {
   args: {
-    trigger: ({ activate }) => <Button variant="primary" label="Delete" onPress={activate}/>,
-    display: 'center',
-    size: 'small',
-    title: 'Confirmation',
-    children: <>Are you sure you want to delete this item?</>,
-    actions: <DialogModal.SubmitAction label="Delete" onPress={() => { window.alert('Confirmed'); }}/>,
+    trigger: undefined,
   },
+  render: (args) => <DialogModalControlledConfirmation {...args}/>,
 };
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 5e699d3e..d1b8cd8c 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -15,23 +15,6 @@ import cl from './DialogModal.module.scss';
 
 export { cl as DialogModalClassNames };
 
-export const useModalRefWithSubject = <S,>(subjectInitial: S | (() => S), activeInitial = false) => {
-  const modalRef = ModalProvider.useRef(null);
-  const [subject, setSubject] = React.useState(subjectInitial);
-  
-  return {
-    modalRef,
-    subject,
-    activateWith: (subject: S | (() => S)) => {
-      // Use flushSync() to force the modal to render, in case the modal rendering is conditional
-      // on the subject being set.
-      flushSync(() => { setSubject(subject); });
-      
-      modalRef.current?.activate();
-    },
-  };
-};
-
 export type DialogModalProps = Omit<React.ComponentProps<typeof Dialog>, 'children'> & {
   /** Content of the modal. If a function, will be passed a dialog controller. */
   children?: React.ReactNode | ModalProviderProps['dialog'],
@@ -66,6 +49,60 @@ export type DialogModalProps = Omit<React.ComponentProps<typeof Dialog>, 'childr
   /** Any additional props to pass to the modal provider. */
   providerProps?: undefined | Omit<ModalProviderProps, 'children'>,
 };
+
+export type ModalWithSubject<S> = {
+  props: Partial<DialogModalProps>,
+  subject: S,
+  activateWith: (subject: S | (() => S)) => void,
+};
+/**
+ * Utility hook to get a reference to a `DialogModal` for imperative usage. To open, you can call `activate()`, or
+ * `activateWith()` if you want to include some subject data to be shown in the modal.
+ */
+export const useModalWithSubject = <S,>(subjectInitial: S | (() => S)): ModalWithSubject<S> => {
+  const modalRef = ModalProvider.useRef(null);
+  const [subject, setSubject] = React.useState(subjectInitial);
+  
+  return {
+    props: { modalRef },
+    subject,
+    activateWith: (subject: S | (() => S)) => {
+      // Use flushSync() to force the modal to render, in case the modal rendering is conditional
+      // on the subject being set.
+      flushSync(() => { setSubject(subject); });
+      
+      modalRef.current?.activate();
+    },
+  };
+};
+
+/**
+ * Similar to `useModalWithSubject`, but will be preconfigured for usage as a confirmation modal.
+ */
+export const useConfirmationModal = <S,>(
+  subjectInitial: S | (() => S),
+  config: { onConfirm: () => void, onCancel?: undefined | (() => void) },
+) => {
+  const modal = useModalWithSubject(subjectInitial);
+  return {
+    ...modal,
+    props: {
+      ...modal.props,
+      display: 'center' as const,
+      size: 'small' as const,
+      allowUserClose: false, // Force the user to explicitly select an action
+      title: 'Confirm',
+      children: 'Are you sure you want to perform this action?',
+      actions: (
+        <>
+          <Dialog.CancelAction label="Cancel" onPress={config.onCancel}/>
+          <Dialog.SubmitAction label="Confirm" onPress={config.onConfirm}/>
+        </>
+      ),
+    },
+  };
+};
+
 /**
  * A dialog component displayed as a modal when activating the given trigger.
  */
@@ -125,7 +162,8 @@ export const DialogModal = Object.assign(
   },
   {
     useModalRef: ModalProvider.useRef,
-    useModalRefWithSubject,
+    useModalWithSubject,
+    useConfirmationModal,
     Action: Dialog.Action,
     ActionIcon: Dialog.ActionIcon,
     CancelAction: Dialog.CancelAction,

From e5d82c56f7ab93e4baeb48052a62859be2ac0781 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 19:44:18 +0100
Subject: [PATCH 23/33] Fix build errors.

---
 .../forms/controls/DatePicker/DatePicker.module.scss          | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/components/forms/controls/DatePicker/DatePicker.module.scss b/src/components/forms/controls/DatePicker/DatePicker.module.scss
index 0ecf05d7..fc4afbfd 100644
--- a/src/components/forms/controls/DatePicker/DatePicker.module.scss
+++ b/src/components/forms/controls/DatePicker/DatePicker.module.scss
@@ -13,7 +13,7 @@
     display: flex;
     flex-direction: row;
     align-items: center;
-    margin-right: -$caret-width;
+    margin-right: calc(-1 * $caret-width);
   }
 
   .bk-date-picker--input {
@@ -25,7 +25,7 @@
     width: $caret-width;
     height: $caret-width;
     position: relative;
-    left: -$caret-width;
+    left: calc(-1 * $caret-width);
     top: bk.rem-from-px(-1);
   }
 

From 03710a11e38fbf8a47469bfb80a109b50613117d Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 19:51:54 +0100
Subject: [PATCH 24/33] Disable no-global-function-names stylelint rule until
 round() issue is fixed.

---
 stylelint.config.mjs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/stylelint.config.mjs b/stylelint.config.mjs
index b4b97eb3..3944e2d6 100644
--- a/stylelint.config.mjs
+++ b/stylelint.config.mjs
@@ -79,7 +79,8 @@ export default {
     ],
     
     // Expressions
-    //...
+    // Workaround for `round()`, re-enable once https://github.com/stylelint-scss/stylelint-scss/pull/1097 lands
+    'scss/no-global-function-names': null,
     
     // CSS extensions (e.g. CSS modules, or future CSS)
     //'property-no-unknown': [true, { ignoreProperties: [] }],

From 8d6291782598ba76fc8ed0c3ce311c406e679cb7 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 19:54:15 +0100
Subject: [PATCH 25/33] Add missing license header.

---
 src/util/hooks/useDebounce.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/util/hooks/useDebounce.ts b/src/util/hooks/useDebounce.ts
index 5223e582..396ee351 100644
--- a/src/util/hooks/useDebounce.ts
+++ b/src/util/hooks/useDebounce.ts
@@ -1,3 +1,6 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import * as React from 'react';
 

From e200789358b88ce5a70a818d8962e8d689301299 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sat, 4 Jan 2025 23:53:48 +0100
Subject: [PATCH 26/33] Implement SpinnerModal + allow ModalProvider to be
 controlled.

---
 package.json.js                               |  1 +
 plopfile.ts                                   | 13 ++--
 .../DialogModal/DialogModal.stories.tsx       |  5 +-
 .../overlays/DialogModal/DialogModal.tsx      |  8 ++-
 .../overlays/ModalProvider/ModalProvider.tsx  | 35 +++++++----
 .../SpinnerModal/SpinnerModal.module.scss     | 11 ++++
 .../SpinnerModal/SpinnerModal.stories.tsx     | 50 +++++++++++++++
 .../overlays/SpinnerModal/SpinnerModal.tsx    | 62 +++++++++++++++++++
 src/components/util/Dialog/useModalDialog.ts  | 15 ++++-
 src/styling/global/reset.scss                 |  2 +-
 src/util/reactUtil.ts                         | 14 ++++-
 11 files changed, 188 insertions(+), 28 deletions(-)
 create mode 100644 src/components/overlays/SpinnerModal/SpinnerModal.module.scss
 create mode 100644 src/components/overlays/SpinnerModal/SpinnerModal.stories.tsx
 create mode 100644 src/components/overlays/SpinnerModal/SpinnerModal.tsx

diff --git a/package.json.js b/package.json.js
index 3ff6f249..b3ae31c9 100644
--- a/package.json.js
+++ b/package.json.js
@@ -168,6 +168,7 @@ const packageConfig = {
     'react': '^19.0.0',
     'react-dom': '^19.0.0',
     'react-error-boundary': '^4.1.2',
+    //'@uidotdev/usehooks': '^2.4.1',
     
     '@floating-ui/react': '^0.26.28',
     'react-toastify': '^10.0.6',
diff --git a/plopfile.ts b/plopfile.ts
index 3c5d12ee..05d824b5 100644
--- a/plopfile.ts
+++ b/plopfile.ts
@@ -78,12 +78,13 @@ const componentTemplate = {
       return (
         <{{{element-type}}}
           {...propsRest}
-          className={cx({
-            bk: true,
-            [cl['bk-{{{kebabCase component-name}}}']]: !unstyled,
-            [cl['bk-{{{kebabCase component-name}}}--x']]: variant === 'x',
-            [cl['bk-{{{kebabCase component-name}}}--y']]: variant === 'y',
-          }, propsRest.className)}
+          className={cx(
+            'bk',
+            { [cl['bk-{{{kebabCase component-name}}}']]: !unstyled },
+            { [cl['bk-{{{kebabCase component-name}}}--x']]: variant === 'x' },
+            { [cl['bk-{{{kebabCase component-name}}}--y']]: variant === 'y' },
+            propsRest.className,
+          )}
         />
       );
     };
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 63d57504..661300ce 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -23,7 +23,7 @@ export default {
   },
   argTypes: {},
   args: {
-    title: 'Modal dialog',
+    title: 'Modal Dialog',
     trigger: ({ activate }) => <Button variant="primary" label="Open modal" onPress={activate}/>,
     children: <LoremIpsum paragraphs={15}/>,
   },
@@ -126,6 +126,7 @@ export const DialogModalWithSubject: Story = {
 const DialogModalControlledConfirmation = (props: React.ComponentProps<typeof DialogModal>) => {
   type Subject = { name: string };
   const deleteConfirmer = DialogModal.useConfirmationModal<null | Subject>(null, {
+    actionLabel: 'Delete',
     onConfirm() { globalThis.alert('Confirmed'); },
     onCancel() { globalThis.alert('Canceled'); },
   });
@@ -133,7 +134,7 @@ const DialogModalControlledConfirmation = (props: React.ComponentProps<typeof Di
   return (
     <article className="bk-body-text">
       {deleteConfirmer.subject &&
-        <DialogModal {...deleteConfirmer.props} {...props} title={deleteConfirmer.subject.name}>
+        <DialogModal {...deleteConfirmer.props} {...props} title="Confirm Delete">
           Are you sure you want to delete "{deleteConfirmer.subject.name}"?
         </DialogModal>
       }
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index d1b8cd8c..598470cc 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -81,7 +81,11 @@ export const useModalWithSubject = <S,>(subjectInitial: S | (() => S)): ModalWit
  */
 export const useConfirmationModal = <S,>(
   subjectInitial: S | (() => S),
-  config: { onConfirm: () => void, onCancel?: undefined | (() => void) },
+  config: {
+    actionLabel?: undefined | string,
+    onConfirm: () => void,
+    onCancel?: undefined | (() => void)
+  },
 ) => {
   const modal = useModalWithSubject(subjectInitial);
   return {
@@ -96,7 +100,7 @@ export const useConfirmationModal = <S,>(
       actions: (
         <>
           <Dialog.CancelAction label="Cancel" onPress={config.onCancel}/>
-          <Dialog.SubmitAction label="Confirm" onPress={config.onConfirm}/>
+          <Dialog.SubmitAction label={config.actionLabel || 'Confirm'} onPress={config.onConfirm}/>
         </>
       ),
     },
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index ab5e8013..a2db9599 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -15,20 +15,20 @@ export { cl as ModalProviderClassNames };
 
 // Use an active state, but with a delay in unmounting to allow exit transitions time to animate
 export const useActiveWithUnmountDelay = (
-  activeDefault: boolean | (() => boolean),
+  active: boolean,
+  setActive: React.Dispatch<React.SetStateAction<boolean>>,
   unmountDelay = 3000, /*ms*/
-): [boolean, boolean, React.Dispatch<React.SetStateAction<boolean>>] => {
-  const [active, setActive] = React.useState(activeDefault);
+): [boolean, React.Dispatch<React.SetStateAction<boolean>>] => {
   const [shouldMount, setShouldMount] = useDebounce(active, unmountDelay);
   
   const setActiveWithUnmountDelay = React.useCallback((active: React.SetStateAction<boolean>) => {
     setActive(active);
     if (active) { setShouldMount(true); } // Skip the delay when activating (should only be for deactivation)
-  }, [setShouldMount]);
+  }, [setActive, setShouldMount]);
   
   React.useDebugValue(`Active: ${active} / Mounted: ${shouldMount}`);
   
-  return [active, shouldMount, setActiveWithUnmountDelay];
+  return [shouldMount, setActiveWithUnmountDelay];
 };
 
 export type ModalRef = {
@@ -43,12 +43,18 @@ export type ModalProviderProps = {
   ref?: undefined | React.Ref<ModalRef>,
   
   /** The trigger that activates the modal overlay. */
-  children: (triggerProps: { active: boolean, activate: () => void }) => React.ReactNode,
+  children?: undefined | ((triggerProps: { active: boolean, activate: () => void }) => React.ReactNode),
   
   /** The dialog to be shown in the modal overlay. */
   dialog: (props: ModalDialogProps) => React.ReactNode,
   
-  /** Whether the modal should be active by default. Default: false. */
+  /** Whether the modal is active. Use this if you want the modal to be a controlled component. */
+  active?: undefined | boolean,
+  
+  /** If the modal is a controlled component, this callback will be called when the active state should change. */
+  onActiveChange?: undefined | React.Dispatch<React.SetStateAction<boolean>>,
+  
+  /** If uncontrolled, specifies whether the modal should be active by default. Default: false. */
   activeDefault?: undefined | boolean,
   
   /** Whether to allow users to close the modal manually. */
@@ -71,13 +77,16 @@ export const ModalProvider = Object.assign(
       unmountDelay = 3000, // ms
     } = props;
     
-    const [active, shouldMount, setActive] = useActiveWithUnmountDelay(activeDefault, unmountDelay);
+    const [activeUncontrolled, setActiveUncontrolled] = React.useState(activeDefault);
+    const active = typeof props.active !== 'undefined' ? props.active : activeUncontrolled;
+    const setActive = typeof props.onActiveChange !== 'undefined' ? props.onActiveChange : setActiveUncontrolled;
+    const [shouldMount, setActiveWithDelay] = useActiveWithUnmountDelay(active, setActive, unmountDelay);
     
     const modalRef = React.useMemo<ModalRef>(() => ({
-      active,
-      activate: () => { setActive(true); },
-      deactivate: () => { setActive(false); },
-    }), [active, setActive]);
+      active: active,
+      activate: () => { setActiveWithDelay(true); },
+      deactivate: () => { setActiveWithDelay(false); },
+    }), [active, setActiveWithDelay]);
     
     React.useImperativeHandle(ref, () => modalRef, [modalRef]);
     
@@ -89,7 +98,7 @@ export const ModalProvider = Object.assign(
     return (
       <>
         {shouldMount && dialog(dialogProps)}
-        {children(modalRef)}
+        {typeof children === 'function' ? children(modalRef) : children}
       </>
     );
   },
diff --git a/src/components/overlays/SpinnerModal/SpinnerModal.module.scss b/src/components/overlays/SpinnerModal/SpinnerModal.module.scss
new file mode 100644
index 00000000..926b3c82
--- /dev/null
+++ b/src/components/overlays/SpinnerModal/SpinnerModal.module.scss
@@ -0,0 +1,11 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+@use '../../../styling/defs.scss' as bk;
+
+@layer baklava.components {
+  .bk-spinner-modal {
+    @include bk.component-base(bk-spinner-modal);
+  }
+}
diff --git a/src/components/overlays/SpinnerModal/SpinnerModal.stories.tsx b/src/components/overlays/SpinnerModal/SpinnerModal.stories.tsx
new file mode 100644
index 00000000..f9027212
--- /dev/null
+++ b/src/components/overlays/SpinnerModal/SpinnerModal.stories.tsx
@@ -0,0 +1,50 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { LoremIpsum } from '../../../util/storybook/LoremIpsum.tsx';
+
+import { Button } from '../../actions/Button/Button.tsx';
+
+import { SpinnerModal } from './SpinnerModal.tsx';
+
+
+type SpinnerModalArgs = React.ComponentProps<typeof SpinnerModal>;
+type Story = StoryObj<SpinnerModalArgs>;
+
+export default {
+  component: SpinnerModal,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+  },
+  render: (args) => <><LoremIpsum paragraphs={5}/><SpinnerModal {...args}/></>,
+} satisfies Meta<SpinnerModalArgs>;
+
+
+export const SpinnerModalStandard: Story = {};
+
+const SpinnerModalControlledWithTrigger = (props: SpinnerModalArgs) => {
+  const [isLoading, setIsLoading] = React.useState(false);
+  
+  React.useEffect(() => {
+    if (isLoading) {
+      globalThis.setTimeout(() => { setIsLoading(false); }, 3000);
+    }
+  }, [isLoading]);
+  
+  return (
+    <>
+      {isLoading && <SpinnerModal delay={0} {...props}/>}
+      <LoremIpsum paragraphs={2}/>
+      <Button variant="primary" label="Trigger spinner for 3 seconds" onPress={() => { setIsLoading(true); }}/>
+      <LoremIpsum paragraphs={2}/>
+    </>
+  );
+};
+export const SpinnerModalWithTrigger: Story = {
+  render: (args) => <SpinnerModalControlledWithTrigger {...args}/>,
+};
diff --git a/src/components/overlays/SpinnerModal/SpinnerModal.tsx b/src/components/overlays/SpinnerModal/SpinnerModal.tsx
new file mode 100644
index 00000000..c5887a36
--- /dev/null
+++ b/src/components/overlays/SpinnerModal/SpinnerModal.tsx
@@ -0,0 +1,62 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+import { mergeRefs, useEffectOnce } from '../../../util/reactUtil.ts';
+import { classNames as cx, type ComponentProps } from '../../../util/componentUtil.ts';
+
+import { Spinner } from '../../graphics/Spinner/Spinner.tsx';
+import { type ModalProviderProps, ModalProvider } from '../ModalProvider/ModalProvider.tsx';
+
+import cl from './SpinnerModal.module.scss';
+
+
+export { cl as SpinnerModalClassNames };
+
+export type SpinnerModalProps = React.PropsWithChildren<ComponentProps<typeof Spinner> & {
+  /** A reference to the modal, for imperative control. */
+  modalRef?: undefined | React.Ref<React.ComponentRef<typeof ModalProvider>>,
+  
+  /** Any additional props to pass to the modal provider. */
+  providerProps?: undefined | Omit<ModalProviderProps, 'children'>,
+  
+  /** Delay until the spinner is visible. Useful to prevent flashing for short actions. Default: 1 second. */
+  delay?: undefined | number,
+}>;
+/**
+ * A loading spinner displayed as modal.
+ */
+export const SpinnerModal = (props: SpinnerModalProps) => {
+  const { modalRef, providerProps, delay = 1000, ...propsRest } = props;
+  
+  const [visible, setVisible] = React.useState(delay === 0);
+  
+  useEffectOnce(() => {
+    if (delay === 0) { return; }
+    globalThis.setTimeout(() => { setVisible(true); }, delay);
+  });
+  
+  return (
+    <ModalProvider
+      active={visible}
+      onActiveChange={setVisible}
+      allowUserClose={false}
+      unmountDelay={0} // No exit animation, once done we want the spinner away as fast as possible
+      dialog={({ dialogProps }) =>
+        <dialog {...dialogProps} inert>
+          <Spinner
+            size="large"
+            {...propsRest}
+            className={cx(
+              cl['bk-spinner-modal'],
+              propsRest.className,
+            )}
+          />
+        </dialog>
+      }
+      {...providerProps}
+      ref={mergeRefs(modalRef, providerProps?.ref)}
+    />
+  );
+};
diff --git a/src/components/util/Dialog/useModalDialog.ts b/src/components/util/Dialog/useModalDialog.ts
index 54a93213..d6ab9020 100644
--- a/src/components/util/Dialog/useModalDialog.ts
+++ b/src/components/util/Dialog/useModalDialog.ts
@@ -58,7 +58,7 @@ export const useModalDialog = (
   }, []);
   
   // Sync active state with <dialog> DOM state
-  React.useEffect(() => {
+  const sync = () => {
     const dialog = dialogRef.current;
     if (!dialog) { return; } // Nothing to sync with
     
@@ -83,7 +83,9 @@ export const useModalDialog = (
         controller.activate();
       }
     }
-  }, [controller]);
+  };
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `controller` is used in `sync`
+  React.useEffect(sync, [controller]);
   
   // The `beforetoggle` event can be used to detect when a modal opens. Note: browser support is poor currently, but
   // it's okay since we generally control the activation, not the user. In non-supporting browsers, if someone were to
@@ -151,10 +153,17 @@ export const useModalDialog = (
     }
   }, [allowUserClose]);
   
+  // Sync when the ref changes. This helps prevent time issues where `active` is set to `true`, but the dialog is not
+  // yet mounted (and thus the ref is `null`). In that case our sync useEffect will be too early.
+  const dialogRefCallback: React.RefCallback<HTMLDialogElement> = (ref) => {
+    dialogRef.current = ref;
+    sync();
+  };
+  
   return {
     close: requestDialogClose,
     dialogProps: {
-      ref: dialogRef,
+      ref: dialogRefCallback,
       open: undefined, // Do not set `open`, leave it to the browser to manage automatically
       
       onBeforeToggle: handleDialogBeforeToggle,
diff --git a/src/styling/global/reset.scss b/src/styling/global/reset.scss
index 129e5c55..d355573f 100644
--- a/src/styling/global/reset.scss
+++ b/src/styling/global/reset.scss
@@ -103,6 +103,6 @@
   dialog::backdrop {
     position: fixed;
     inset: 0;
-    background: rgba(0 0 0 / 10%);
+    background: rgba(0 0 0 / 20%);
   }
 }
diff --git a/src/util/reactUtil.ts b/src/util/reactUtil.ts
index 5fbeff1f..173c543f 100644
--- a/src/util/reactUtil.ts
+++ b/src/util/reactUtil.ts
@@ -4,7 +4,7 @@
 
 /* Source: https://github.com/wojtekmaj/merge-refs/tree/main */
 
-import type * as React from 'react';
+import * as React from 'react';
 
 /**
  * A function that merges React refs into one.
@@ -46,3 +46,15 @@ export const mergeRefs = <T>(
 export const idToCssIdent = (id: string) => {
   return `--${id.replaceAll(':', '')}`;
 };
+
+export const useEffectOnce = (fn: () => void) => {
+  const isCalledRef = React.useRef(false);
+  
+  // biome-ignore lint/correctness/useExhaustiveDependencies: Should run only once
+    React.useEffect(() => {
+    if (!isCalledRef.current) {
+      isCalledRef.current = true;
+      fn();
+    }
+  }, []);
+}

From ccca5a8d3c0c7d7b04fc2a69afee6962b03f4c11 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sun, 5 Jan 2025 00:11:51 +0100
Subject: [PATCH 27/33] Allow slide-over modals to have a customizable width.

---
 .../DialogModal/DialogModal.module.scss       | 20 ++++++++++++++-----
 .../DialogModal/DialogModal.stories.tsx       | 12 ++++++++++-
 .../overlays/ModalProvider/ModalProvider.tsx  |  1 -
 3 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index 3bda69a5..b71ff0ca 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -56,7 +56,7 @@
   }
 }
 
-@mixin dialog-slide-over($entry-dur: 200ms, $exit-dur: 180ms, $origin: right) {
+@mixin dialog-slide-over($entry-dur: 200ms, $exit-dur: 180ms, $size: 0.8, $origin: right) {
   $dir: if($origin==right, 1, -1);
   
   transition-property: overlay, display, translate;
@@ -65,18 +65,23 @@
   
   // Open state styling
   translate: 0;
+  @if $origin == left {
+    margin-inline-end: calc((1 - $size) * 100vi);
+  } @else if $origin == right {
+    margin-inline-start: calc((1 - $size) * 100vi);
+  }
   
   // Entry transition styling
   @media (prefers-reduced-motion: no-preference) { transition-duration: $entry-dur; }
   @starting-style {
-    translate: ($dir * 80vi) 0;
+    translate: calc($dir * $size * 100vi) 0;
   }
   
   // Exit transition styling
   &:not([open]) {
     @media (prefers-reduced-motion: no-preference) { transition-duration: $exit-dur; }
     transition-timing-function: ease-in;
-    translate: ($dir * 80vi) 0;
+    translate: calc($dir * $size * 100vi) 0;
   }
 }
 
@@ -154,21 +159,26 @@
       width: auto;
       height: auto;
       
+      --bk-modal-slide-over-size: 0.8;
+      &.bk-dialog-modal--small { --bk-modal-slide-over-size: 0.3; }
+      &.bk-dialog-modal--medium { --bk-modal-slide-over-size: 0.5; }
+      &.bk-dialog-modal--large { --bk-modal-slide-over-size: 0.8; }
+      
       --bk-dialog-modal-entry-dur: 300ms;
       --bk-dialog-modal-exit-dur: 250ms;
       &.bk-dialog-modal--slide-over--left {
-        margin-inline-end: 20vi;
         @include dialog-slide-over(
           $entry-dur: var(--bk-dialog-modal-entry-dur),
           $exit-dur: var(--bk-dialog-modal-exit-dur),
+          $size: var(--bk-modal-slide-over-size),
           $origin: left,
         );
       }
       &.bk-dialog-modal--slide-over--right {
-        margin-inline-start: 20vi;
         @include dialog-slide-over(
           $entry-dur: var(--bk-dialog-modal-entry-dur),
           $exit-dur: var(--bk-dialog-modal-exit-dur),
+          $size: var(--bk-modal-slide-over-size),
           $origin: right,
         );
       }
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 661300ce..b13660a2 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -65,9 +65,19 @@ export const DialogModalFullScreen: Story = {
   },
 };
 
-export const DialogModalSlideOver: Story = {
+export const DialogModalSlideOverRight: Story = {
   args: {
     display: 'slide-over',
+    size: 'large',
+    slideOverPosition: 'right',
+    title: 'Slide over modal dialog',
+  },
+};
+export const DialogModalSlideOverLeft: Story = {
+  args: {
+    display: 'slide-over',
+    size: 'medium',
+    slideOverPosition: 'left',
     title: 'Slide over modal dialog',
   },
 };
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index a2db9599..6e752227 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -12,7 +12,6 @@ import cl from './ModalProvider.module.scss';
 
 export { cl as ModalProviderClassNames };
 
-
 // Use an active state, but with a delay in unmounting to allow exit transitions time to animate
 export const useActiveWithUnmountDelay = (
   active: boolean,

From 22d6564b169ad9484d1452ff16bc4429d5bbf4b4 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sun, 5 Jan 2025 00:51:44 +0100
Subject: [PATCH 28/33] Add story for nested dialogs + fix close bubbling
 issue.

---
 .../overlays/DialogModal/DialogModal.stories.tsx | 16 ++++++++++++++++
 src/components/util/Dialog/useModalDialog.ts     |  6 +++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index b13660a2..5d3e2c10 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -33,6 +33,22 @@ export default {
 
 export const DialogModalStandard: Story = {};
 
+export const DialogModalNested: Story = {
+  args: {
+    title: 'Modal with a submodal',
+    className: 'outer',
+    children: (
+      <DialogModal
+        className="inner"
+        title="Submodal"
+        trigger={({ activate }) => <Button variant="primary" label="Open submodal" onPress={activate}/>}
+      >
+        This is a submodal. Closing this modal should keep the outer modal still open.
+      </DialogModal>
+    ),
+  },
+};
+
 export const DialogModalNoncloseable: Story = {
   args: {
     activeDefault: true,
diff --git a/src/components/util/Dialog/useModalDialog.ts b/src/components/util/Dialog/useModalDialog.ts
index d6ab9020..1ec32282 100644
--- a/src/components/util/Dialog/useModalDialog.ts
+++ b/src/components/util/Dialog/useModalDialog.ts
@@ -109,7 +109,11 @@ export const useModalDialog = (
   
   // Handle dialog `close` event. This event is called when the dialog has already been closed (cannot be canceled).
   // https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close_event
-  const handleDialogClose = React.useCallback(() => {
+  const handleDialogClose = React.useCallback((event: React.SyntheticEvent<HTMLDialogElement>) => {
+    // Stop this event from closing parent dialog elements
+    // XXX `close` events shouldn't bubble, but at least in Chrome v131 it seems like it does?
+    event.stopPropagation();
+    
     /*
     // XXX This is probably not necessary, browsers do this out of the box already
     // Restore focus to last active element before the user opened the modal

From 42d610bcdcbf6cabe80722500e78abbbbd9f42eb Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sun, 5 Jan 2025 01:15:12 +0100
Subject: [PATCH 29/33] Replace Modal component with DialogModal.

---
 .storybook/preview.tsx                        |   7 +-
 app/lib.ts                                    |   4 +-
 .../DialogModal/DialogModal.module.scss       |  40 +++-
 .../DialogModal/DialogModal.stories.tsx       |  20 +-
 .../overlays/DialogModal/DialogModal.tsx      |   3 +-
 .../overlays/Modal/Modal.module.scss          | 187 ----------------
 .../overlays/Modal/Modal.stories.tsx          | 144 -------------
 src/components/overlays/Modal/Modal.tsx       | 201 ------------------
 .../overlays/ModalProvider/ModalProvider.tsx  |   8 +-
 src/layouts/AppLayout/AppLayout.stories.tsx   |  30 +--
 10 files changed, 67 insertions(+), 577 deletions(-)
 delete mode 100644 src/components/overlays/Modal/Modal.module.scss
 delete mode 100644 src/components/overlays/Modal/Modal.stories.tsx
 delete mode 100644 src/components/overlays/Modal/Modal.tsx

diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index f6b2c5a2..c6362b09 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -63,10 +63,13 @@ const preview = {
             ],
             'overlays',
             [
+              'ModalProvider',
+              'SpinnerModal',
+              'DialogModal',
               'Tooltip',
               'TooltipProvider',
-              'Dropdown',
-              'Modal',
+              'DropdownMenu',
+              'Toast',
             ],
             'lists',
             [
diff --git a/app/lib.ts b/app/lib.ts
index a9dee7ed..4a981e2e 100644
--- a/app/lib.ts
+++ b/app/lib.ts
@@ -62,9 +62,11 @@ export { Stepper } from '../src/components/navigations/Stepper/Stepper.tsx';
 export { Tab, Tabs } from '../src/components/navigations/Tabs/Tabs.tsx';
 
 // Overlays
+export { ModalProvider } from '../src/components/overlays/ModalProvider/ModalProvider.tsx';
+export { SpinnerModal } from '../src/components/overlays/SpinnerModal/SpinnerModal.tsx';
+export { DialogModal } from '../src/components/overlays/DialogModal/DialogModal.tsx';
 export { DropdownMenu } from '../src/components/overlays/DropdownMenu/DropdownMenu.tsx';
 export { DropdownMenuProvider } from '../src/components/overlays/DropdownMenu/DropdownMenuProvider.tsx';
-export { Modal } from '../src/components/overlays/Modal/Modal.tsx';
 export { type ToastContent, ToastProvider, ToastMessage } from '../src/components/overlays/Toast/Toast.tsx';
 export { Tooltip } from '../src/components/overlays/Tooltip/Tooltip.tsx';
 export { TooltipProvider } from '../src/components/overlays/Tooltip/TooltipProvider.tsx';
diff --git a/src/components/overlays/DialogModal/DialogModal.module.scss b/src/components/overlays/DialogModal/DialogModal.module.scss
index b71ff0ca..1712fe61 100644
--- a/src/components/overlays/DialogModal/DialogModal.module.scss
+++ b/src/components/overlays/DialogModal/DialogModal.module.scss
@@ -31,6 +31,29 @@
   }
 }
 
+@mixin dialog-backdrop-opaque($entry-dur: 200ms, $exit-dur: 180ms) {
+  &::backdrop {
+    transition-property: overlay, display, background-color;
+    transition-timing-function: linear;
+    transition-behavior: allow-discrete;
+    
+    // Open state styling
+    background-color: bk.$theme-page-default;
+    
+    // Entry transition styling
+    @media (prefers-reduced-motion: no-preference) { transition-duration: $entry-dur; }
+    @starting-style {
+      background-color: transparent;
+    }
+  }
+  // Exit transition styling
+  // Note: cannot nest the following inside `::backdrop`, since `:not()` needs to apply to the dialog not `::backdrop`
+  &:not([open])::backdrop {
+    @media (prefers-reduced-motion: no-preference) { transition-duration: $exit-dur; }
+    background-color: transparent;
+  }
+}
+
 @mixin dialog-fade-in($entry-dur: 200ms, $exit-dur: 180ms, $scale: 1) {
   transition-property: overlay, display, opacity, scale;
   transition-timing-function: ease-out;
@@ -100,10 +123,12 @@
     max-width: 100vi;
     max-height: 100vb;
     
-    @include dialog-backdrop(
-      $entry-dur: var(--bk-dialog-modal-entry-dur),
-      $exit-dur: var(--bk-dialog-modal-exit-dur),
-    );
+    &:not(.bk-dialog-modal--full-screen) {
+      @include dialog-backdrop(
+        $entry-dur: var(--bk-dialog-modal-entry-dur),
+        $exit-dur: var(--bk-dialog-modal-exit-dur),
+      );
+    }
     
     
     //
@@ -140,7 +165,7 @@
     
     &.bk-dialog-modal--full-screen {
       // FIXME: test this on mobile for potential overflow/shifting. May need to use `dvb`/`dvi` instead?
-      inset: 0;
+      inset: 1rem;
       margin: 0;
       width: auto;
       height: auto;
@@ -151,6 +176,11 @@
         $entry-dur: var(--bk-dialog-modal-entry-dur),
         $exit-dur: var(--bk-dialog-modal-exit-dur),
       );
+      
+      @include dialog-backdrop-opaque(
+        $entry-dur: var(--bk-dialog-modal-entry-dur),
+        $exit-dur: var(--bk-dialog-modal-exit-dur),
+      );
     }
     
     &.bk-dialog-modal--slide-over {
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 5d3e2c10..5be4f7e3 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -33,6 +33,14 @@ export default {
 
 export const DialogModalStandard: Story = {};
 
+export const DialogModalSmall: Story = {
+  args: { size: 'small' },
+};
+
+export const DialogModalLarge: Story = {
+  args: { size: 'large' },
+};
+
 export const DialogModalNested: Story = {
   args: {
     title: 'Modal with a submodal',
@@ -62,18 +70,6 @@ export const DialogModalNoncloseable: Story = {
   },
 };
 
-export const DialogModalSmall: Story = {
-  args: {
-    size: 'small',
-  },
-};
-
-export const DialogModalLarge: Story = {
-  args: {
-    size: 'large',
-  },
-};
-
 export const DialogModalFullScreen: Story = {
   args: {
     display: 'full-screen',
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 598470cc..444bf719 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -130,9 +130,10 @@ export const DialogModal = Object.assign(
       <ModalProvider
         activeDefault={activeDefault}
         allowUserClose={allowUserClose}
+        shouldCloseOnBackdropClick={display !== 'full-screen'}
         dialog={dialogController =>
           <Dialog
-            flat={['full-screen', 'slide-over'].includes(display)}
+            flat={[/*'full-screen', */'slide-over'].includes(display)}
             {...dialogController.dialogProps}
             showCloseIcon={allowUserClose}
             autoFocusClose={allowUserClose}
diff --git a/src/components/overlays/Modal/Modal.module.scss b/src/components/overlays/Modal/Modal.module.scss
deleted file mode 100644
index 0391fc37..00000000
--- a/src/components/overlays/Modal/Modal.module.scss
+++ /dev/null
@@ -1,187 +0,0 @@
-/* Copyright (c) Fortanix, Inc.
-|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
-|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-@use '../../../styling/defs.scss' as bk;
-@use '../../containers/Panel/Panel.module.scss' as Panel;
-
-@layer baklava.components {
-  .bk-modal {
-    @include bk.component-base(bk-modal);
-    @include Panel.panel; // Reuse styling from `Panel`
-    
-    /* --bk-modal-background-color: color-mix(in srgb, var(--bk-panel-background-color) 80%, transparent); */
-    --bk-modal-background-color:  var(--bk-panel-background-color);
-    
-    margin: auto;
-    padding: 0;
-    height: fit-content;
-    min-height: bk.$spacing-16;
-    max-width: calc(100% - bk.$spacing-6);
-    max-height: calc(100% - bk.$spacing-6);
-    
-    box-shadow: 0 8px 10px 1px rgba(0 0 0 / 14%), 0 3px 14px 2px rgba(0 0 0 / 12%), 0 5px 5px -3px rgba(0 0 0 / 3%);
-    background-color: var(--bk-modal-background-color);
-    border-radius: bk.$sizing-2;
-    
-    display: none; /* flex */
-    flex-direction: column;
-    
-    &.bk-modal-small {
-      // 484px
-      width: calc(484 * bk.$size-1);
-    }
-    &.bk-modal-medium {
-      // 684px
-      width: calc(684 * bk.$size-1);
-    }
-    &.bk-modal-large {
-      // 784px
-      width: calc(784 * bk.$size-1);
-    }
-    &.bk-modal-x-large {
-      // 906px
-      width: calc(906 * bk.$size-1);
-    }
-    &.bk-modal-fullscreen {
-      width: calc(100% - bk.$spacing-3);
-      height: calc(100% - bk.$spacing-3);
-    }
-    .bk-modal__header {
-      position: sticky;
-      top: 0;
-      padding: 0;
-      
-      background: var(--bk-modal-background-color);
-      
-      display: flex;
-      flex-direction: row;
-      align-items: baseline;
-      margin-bottom: bk.$spacing-7;
-      
-      h1 {
-        font-size: 16px; // do not match bk variable sizes
-        font-weight: bk.$font-weight-semibold;
-      }
-      
-      :nth-child(1 of :global(.action)) {
-        margin-left: auto;
-      }
-    }
-    .bk-modal__close {
-      position: absolute;
-      right: bk.$spacing-8;
-      top: calc(bk.$spacing-8 - 8px);
-      z-index: 1;
-      font-size: 1.6em;
-    }
-    .bk-modal__container {
-      padding: bk.$spacing-8;
-      padding-bottom: bk.$spacing-9;
-      flex-direction: column;
-      overflow: hidden;
-      display: flex;
-      flex: 1;
-    }
-    .bk-modal__content {
-      flex: 1; /* Make sure we cover all available space */
-      // stylelint-disable-next-line declaration-property-value-disallowed-list
-      overflow: auto; // FIXME
-    }
-
-    transition:
-      opacity 1ms ease-out,
-      scale 1ms ease-out,
-      overlay 1ms ease-out allow-discrete,
-      display 1ms ease-out allow-discrete;
-    opacity: 0;
-    scale: 0.98 0.98;
-    transition-duration: 200ms; /* Exit transition duration */
-    
-    /* Variant: slide out */
-    --modal-slide-out-inset: var(--bk-sizing-3);
-    &:is(.bk-modal--slide-out-left, .bk-modal--slide-out-right) {
-      position: fixed;
-      inset: 0;
-      margin: 0;
-      width: 60vw;
-      height: auto;
-      max-height: 100%;
-      
-      &.bk-modal--slide-out-left {
-        right: auto;
-        transform-origin: center left;
-        border-top-left-radius: 0;
-        border-bottom-left-radius: 0;
-      }
-      &.bk-modal--slide-out-right {
-        left: auto;
-        transform-origin: center right;
-        border-top-right-radius: 0;
-        border-bottom-right-radius: 0;
-      }
-      
-      opacity: 1;
-      transform: scaleX(0);
-      &:modal {
-        transform: scaleX(1);
-        
-        @starting-style {
-          opacity: 1;
-          transform: scaleX(0);
-        }
-      }
-      
-      .bk-modal__content {
-        // stylelint-disable-next-line declaration-property-value-disallowed-list
-        overflow: auto; // FIXME
-      }
-    }
-    
-    /* https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#animating_dialogs */
-    
-    &:modal {
-      display: flex;
-      opacity: 1;
-      scale: 1 1;
-      transition-duration: 120ms; /* Enter transition duration */
-      transition-timing-function: ease-in;
-      
-      @starting-style {
-        opacity: 0;
-        scale: 1.05 1.05;
-      }
-    }
-  }
-  
-  /* Note: `::backdrop` cannot be nested/scoped (at least in Chrome v120) */
-  .bk-modal::backdrop {
-    --transition-time: 200ms;
-    background-color: rgb(0 0 0 / 0%);
-    transition:
-      display var(--transition-time) allow-discrete,
-      overlay var(--transition-time) allow-discrete,
-      background-color var(--transition-time);
-  }
-  .bk-modal:modal::backdrop,
-  .bk-modal-spinner::backdrop {
-    background-color: rgb(0 0 0 / 20%);
-    backdrop-filter: blur(5px); /* Should be in px, not rem (blur effect should be constant) */
-  }
-  @starting-style {
-    .bk-modal:modal::backdrop {
-      background-color: rgb(0 0 0 / 0%);
-    }
-  }
-  
-  .bk-modal-spinner {
-    outline: none !important; // prevent blue border on Esc pressing
-    
-    .bk-modal__content {
-      display: flex;
-      justify-content: center;
-      align-items: center;
-      overflow: hidden;
-    }
-  }
-}
diff --git a/src/components/overlays/Modal/Modal.stories.tsx b/src/components/overlays/Modal/Modal.stories.tsx
deleted file mode 100644
index 1bc4af36..00000000
--- a/src/components/overlays/Modal/Modal.stories.tsx
+++ /dev/null
@@ -1,144 +0,0 @@
-/* Copyright (c) Fortanix, Inc.
-|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
-|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-import * as React from 'react';
-
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { ModalClassNames as cl } from './Modal.tsx';
-import { OverflowTester } from '../../../util/storybook/OverflowTester.tsx';
-import { Modal } from './Modal.tsx';
-import { Button } from '../../actions/Button/Button.tsx';
-import { Spinner } from '../../graphics/Spinner/Spinner.tsx';
-
-
-type ButtonArgs = React.ComponentProps<typeof Modal>;
-type Story = StoryObj<ButtonArgs>;
-
-export default {
-  component: Modal,
-  parameters: {
-    layout: 'centered',
-  },
-  tags: ['autodocs'],
-  argTypes: {
-  },
-} satisfies Meta<ButtonArgs>;
-
-
-type ModalWithTriggerProps = Omit<React.ComponentProps<typeof Modal>, 'active' | 'onClose'> & {
-  triggerLabel?: string,
-};
-const ModalWithTrigger = ({ triggerLabel = 'Open modal', ...modalProps }: ModalWithTriggerProps) => {
-  const [active, setActive] = React.useState(false);
-  const onClose = React.useCallback(() => { setActive(false); }, []);
-  return (
-    <>
-      <Button variant="primary" onPress={() => { setActive(true); }}>{triggerLabel}</Button>
-      <Modal {...modalProps} active={active} onClose={onClose}/>
-    </>
-  );
-};
-
-const reusableModalChildren: React.JSX.Element = (
-  <>
-    <Modal.Header>
-      <h1>Modal title</h1>
-    </Modal.Header>
-    <Modal.Content>
-      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do iusmod tempor incididunt ut labore et dolore magna aliqua.</p>
-      
-      <ModalWithTrigger triggerLabel="Open Submodal">
-        <Modal.Header>
-          <h1>Submodal title</h1>
-        </Modal.Header>
-        <Modal.Content>
-          <p>This is a submodal</p>
-          <OverflowTester/>
-        </Modal.Content>
-      </ModalWithTrigger>
-      
-      <OverflowTester/>
-    </Modal.Content>
-    <Modal.Footer>This is a modal footer with eventual action buttons</Modal.Footer>
-  </>
-);
-
-export const ModalSizeSmall: Story = {
-  render: () => (
-    <ModalWithTrigger size="small">
-      {reusableModalChildren}
-    </ModalWithTrigger>
-  ),
-};
-
-export const ModalSizeMedium: Story = {
-  render: () => (
-    <ModalWithTrigger size="medium">
-      {reusableModalChildren}
-    </ModalWithTrigger>
-  ),
-};
-
-export const ModalSizeLarge: Story = {
-  render: () => (
-    <ModalWithTrigger size="large">
-      {reusableModalChildren}
-    </ModalWithTrigger>
-  ),
-};
-
-export const ModalSizeXLarge: Story = {
-  render: () => (
-    <ModalWithTrigger size="x-large">
-      {reusableModalChildren}
-    </ModalWithTrigger>
-  ),
-};
-
-export const ModalSizeFullScreen: Story = {
-  render: () => (
-    <ModalWithTrigger size="fullscreen">
-      {reusableModalChildren}
-    </ModalWithTrigger>
-  ),
-};
-
-export const ModalUncloseable: Story = {
-  render: () => (
-    <ModalWithTrigger closeable={false}>
-      {reusableModalChildren}
-    </ModalWithTrigger>
-  ),
-};
-
-type ModalWithSpinnerTriggerProps = Omit<React.ComponentProps<typeof Modal>, 'active' | 'onClose'> & {
-  triggerLabel?: string,
-};
-const ModalWithSpinnerTrigger = ({ triggerLabel = 'Open modal with spinner (it will close in 5 seconds)', ...modalProps }: ModalWithSpinnerTriggerProps) => {
-  const [active, setActive] = React.useState(false);
-  const onPress = () => {
-    setActive(true);
-    setTimeout(() => {
-      setActive(false);
-    }, 5000);
-  }
-  const onClose = React.useCallback(() => { setActive(false); }, []);
-  return (
-    <>
-      <Button variant="primary" onPress={onPress}>{triggerLabel}</Button>
-      <Modal {...modalProps} active={active} onClose={onClose} closeable={false} className={cl['bk-modal-spinner']} size="fullscreen"/>
-    </>
-  );
-};
-
-export const ModalWithSpinner: Story = {
-  render: () => (
-    <ModalWithSpinnerTrigger unstyled={true}>
-      <Modal.Content>
-        <Spinner size="large" />
-      </Modal.Content>
-    </ModalWithSpinnerTrigger>
-  ),
-};
diff --git a/src/components/overlays/Modal/Modal.tsx b/src/components/overlays/Modal/Modal.tsx
deleted file mode 100644
index b36988de..00000000
--- a/src/components/overlays/Modal/Modal.tsx
+++ /dev/null
@@ -1,201 +0,0 @@
-/* Copyright (c) Fortanix, Inc.
-|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
-|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-import { type ClassNameArgument, classNames as cx } from '../../../util/componentUtil.ts';
-import * as React from 'react';
-
-import { Icon } from '../../graphics/Icon/Icon.tsx';
-
-import cl from './Modal.module.scss';
-
-export { cl as ModalClassNames };
-
-
-type ModalHeaderProps = React.PropsWithChildren<{
-  unstyled?: boolean;
-  className?: ClassNameArgument;
-}>;
-
-/* Modal Header component */
-const ModalHeader = ({ children, unstyled, className }: ModalHeaderProps) => (
-  <header
-    className={cx(
-      {
-        bk: true,
-        [cl['bk-modal__header'] as string]: !unstyled,
-      },
-      className,
-    )}
-  >
-    {children}
-  </header>
-);
-
-type ModalContentProps = React.PropsWithChildren<{
-  unstyled?: boolean;
-  className?: ClassNameArgument;
-}>;
-
-/* Modal Content component */
-const ModalContent = ({ children, unstyled, className }: ModalContentProps) => (
-  <section
-    className={cx(
-      {
-        bk: true,
-        'body-text': true,
-        [cl['bk-modal__content'] as string]: !unstyled,
-      },
-      className,
-    )}
-  >
-    {children}
-  </section>
-);
-
-type ModalFooterProps = React.PropsWithChildren<{
-  unstyled?: boolean;
-  className?: ClassNameArgument;
-}>;
-
-/* Modal Footer component */
-const ModalFooter = ({ children, unstyled, className }: ModalFooterProps) => (
-  <footer
-    className={cx(
-      {
-        bk: true,
-        [cl['bk-modal__footer'] as string]: !unstyled,
-      },
-      className,
-    )}
-  >
-    {children}
-  </footer>
-);
-
-type ModalProps = React.PropsWithChildren<{
-  unstyled?: boolean;
-  size?: 'small' | 'medium' | 'large' | 'x-large' | 'fullscreen';
-  active: boolean;
-  className?: ClassNameArgument;
-  onClose: () => void;
-  closeable?: boolean;
-}>;
-
-/**
- * Modal component.
- */
-const Modal = ({
-  children,
-  unstyled,
-  className,
-  size = 'medium',
-  closeable = true,
-  active,
-  onClose,
-}: ModalProps) => {
-  const dialogRef = React.useRef<HTMLDialogElement>(null);
-
-  // Sync the `active` flag with the DOM dialog
-  React.useEffect(() => {
-    const dialog = dialogRef.current;
-    if (dialog === null) {
-      return;
-    }
-
-    if (active && !dialog.open) {
-      dialog.showModal();
-    } else if (!active && dialog.open) {
-      dialog.close();
-    }
-  }, [active]);
-
-  // Sync the dialog close event with the `active` flag
-  const handleCloseEvent = React.useCallback(
-    (event: Event): void => {
-      const dialog = dialogRef.current;
-      if (dialog === null) {
-        return;
-      }
-      
-      if (active && event.target === dialog) {
-        onClose();
-      }
-    },
-    [active, onClose],
-  );
-  React.useEffect(() => {
-    const dialog = dialogRef.current;
-    if (dialog === null) {
-      return;
-    }
-    
-    dialog.addEventListener('close', handleCloseEvent);
-    return () => {
-      dialog.removeEventListener('close', handleCloseEvent);
-    };
-  }, [handleCloseEvent]);
-
-  const close = React.useCallback(() => {
-    onClose();
-  }, [onClose]);
-
-  const handleDialogClick = React.useCallback(
-    (event: React.MouseEvent) => {
-      const dialog = dialogRef.current;
-      if (dialog !== null && event.target === dialog && closeable) {
-        // Note: clicking the backdrop just results in an event where the target is the `<dialog>` element. In order to
-        // distinguish between the backdrop and the modal content, we assume that the `<dialog>` is fully covered by
-        // another element. In our case, `bk-modal__content` must cover the whole `<dialog>` otherwise this will not work.
-        close();
-      }
-    },
-    [close, closeable],
-  );
-
-  // "onKeyDown" instead of "onCancel" as the latter is only fired after the cancel already initiated
-  const handleDialogKeyDown = (event: React.KeyboardEvent) => {
-    if (event.key === 'Escape' && !closeable) {
-      event.preventDefault();
-    }
-  };
-
-  return (
-    <dialog
-      ref={dialogRef}
-      className={cx(
-        {
-          bk: true,
-          [cl['bk-modal-small'] as string]: size === 'small',
-          [cl['bk-modal-medium'] as string]: size === 'medium',
-          [cl['bk-modal-large'] as string]: size === 'large',
-          [cl['bk-modal-x-large'] as string]: size === 'x-large',
-          [cl['bk-modal-fullscreen'] as string]: size === 'fullscreen',
-          [cl['bk-modal'] as string]: !unstyled,
-        },
-        className,
-      )}
-      onClick={handleDialogClick}
-      onKeyDown={handleDialogKeyDown}
-    >
-      {closeable && (
-        <button
-          type="button"
-          className={cx(cl['bk-modal__close'])}
-          onClick={close}
-        >
-          <Icon icon="cross" />
-        </button>
-      )}
-      <div className={cx(cl['bk-modal__container'])}>
-        {children}
-      </div>
-    </dialog>
-  );
-};
-
-Modal.Content = ModalContent;
-Modal.Header = ModalHeader;
-Modal.Footer = ModalFooter;
-
-export { Modal };
diff --git a/src/components/overlays/ModalProvider/ModalProvider.tsx b/src/components/overlays/ModalProvider/ModalProvider.tsx
index 6e752227..ad51b3d7 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.tsx
@@ -59,6 +59,9 @@ export type ModalProviderProps = {
   /** Whether to allow users to close the modal manually. */
   allowUserClose?: undefined | boolean,
   
+  /** Whether clicking on the backdrop should close the modal. Default: true */
+  shouldCloseOnBackdropClick?: undefined | boolean,
+  
   /** How long to keep the dialog in the DOM for exit animation purposes. Default: 3 seconds. */
   unmountDelay?: undefined | number,
 };
@@ -72,7 +75,8 @@ export const ModalProvider = Object.assign(
       children,
       dialog,
       activeDefault = false,
-      allowUserClose = false,
+      allowUserClose = true,
+      shouldCloseOnBackdropClick = true,
       unmountDelay = 3000, // ms
     } = props;
     
@@ -91,7 +95,7 @@ export const ModalProvider = Object.assign(
     
     const dialogProps = useModalDialog(modalRef, {
       allowUserClose,
-      shouldCloseOnBackdropClick: allowUserClose,
+      shouldCloseOnBackdropClick,
     });
     
     return (
diff --git a/src/layouts/AppLayout/AppLayout.stories.tsx b/src/layouts/AppLayout/AppLayout.stories.tsx
index b9627832..ea51b05a 100644
--- a/src/layouts/AppLayout/AppLayout.stories.tsx
+++ b/src/layouts/AppLayout/AppLayout.stories.tsx
@@ -2,11 +2,9 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-import cx, { type Argument as ClassNameArgument } from 'classnames';
 import * as React from 'react';
 
 import type { Meta, StoryObj } from '@storybook/react';
-import { userEvent, within } from '@storybook/test';
 
 import { OverflowTester } from '../../util/storybook/OverflowTester.tsx';
 import { Header } from './Header/Header.tsx';
@@ -17,13 +15,13 @@ import { Nav } from './Nav/Nav.tsx';
 import { Button } from '../../components/actions/Button/Button.tsx';
 import { Link } from '../../components/actions/Link/Link.tsx';
 import { Panel } from '../../components/containers/Panel/Panel.tsx';
-import { Modal } from '../../components/overlays/Modal/Modal.tsx';
+import { DialogModal } from '../../components/overlays/DialogModal/DialogModal.tsx';
 import { UserMenu } from './Header/UserMenu.tsx';
 
-import { AppLayout } from './AppLayout.tsx';
 import { SolutionSelector } from './Header/SolutionSelector.tsx';
 import { AccountSelector } from './Header/AccountSelector.tsx';
 import { Breadcrumbs } from './Breadcrumbs/Breadcrumbs.tsx';
+import { AppLayout } from './AppLayout.tsx';
 
 
 type AppLayoutArgs = React.ComponentProps<typeof AppLayout>;
@@ -41,21 +39,6 @@ export default {
 } satisfies Meta<AppLayoutArgs>;
 
 
-type ModalWithTriggerProps = Omit<React.ComponentProps<typeof Modal>, 'active' | 'onClose'> & {
-  triggerLabel?: string,
-  content?: React.ComponentProps<typeof Modal>['children'],
-};
-const ModalWithTrigger = ({ triggerLabel = 'Open modal', content, ...modalProps }: ModalWithTriggerProps) => {
-  const [active, setActive] = React.useState(false);
-  const onClose = React.useCallback(() => { setActive(false); }, [setActive]);
-  return (
-    <>
-      <Button variant="primary" onPress={() => { setActive(true); }}>{triggerLabel}</Button>
-      <Modal children={content} {...modalProps} active={active} onClose={onClose}/>
-    </>
-  );
-};
-
 export const Standard: Story = {
   args: {
     children: (
@@ -97,9 +80,12 @@ export const Standard: Story = {
           <Panel>
             <Panel.Heading>Panel</Panel.Heading>
             
-            <ModalWithTrigger>
-              <ModalWithTrigger/>
-            </ModalWithTrigger>
+            <DialogModal
+              title="Modal"
+              trigger={({ activate }) => <Button variant="primary" label="Open modal" onPress={() => { activate(); }}/>}
+            >
+              Test
+            </DialogModal>
           </Panel>
           <OverflowTester/>
         </main>

From 3828066c425d5018913be6371d43b29d3a171926 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sun, 5 Jan 2025 22:22:56 +0100
Subject: [PATCH 30/33] Work on DialogModal.

---
 .../containers/Dialog/Dialog.module.scss      |  11 +-
 src/components/containers/Dialog/Dialog.tsx   | 124 +++++++++++-------
 .../DialogModal/DialogModal.stories.tsx       |   2 +-
 .../overlays/DialogModal/DialogModal.tsx      |   8 +-
 .../ModalProvider/ModalProvider.stories.tsx   |   3 +-
 .../overlays/SpinnerModal/SpinnerModal.tsx    |   2 +-
 src/components/text/Tag/Tag.module.scss       |  31 +++--
 src/components/text/Tag/Tag.tsx               |   2 +-
 src/layouts/util/Scroller.module.scss         |   2 +
 src/layouts/util/Scroller.tsx                 |  10 +-
 src/styling/defs.scss                         |   4 +
 src/styling/global/accessibility.scss         |  22 +++-
 src/styling/global/reset.scss                 |  16 ++-
 13 files changed, 158 insertions(+), 79 deletions(-)

diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index 17a0ef4f..0aa38579 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -38,10 +38,11 @@
     
     .bk-dialog__header {
       position: sticky;
-      top: 0;
+      top: -1px; // -1px to prevent bleed through due to pixel rounding
       z-index: 1;
       
       padding-block: var(--bk-dialog-padding-block) calc(bk.$spacing-7 / 2);
+      padding-block-start: calc(var(--bk-dialog-padding-block) + 1px); // 1px to compensate for `top: -1px`
       padding-inline: var(--bk-dialog-padding-inline);
       background: var(--bk-dialog-background-color);
       
@@ -62,6 +63,7 @@
     }
     
     .bk-dialog__content {
+      scroll-margin-top: 100lh; // Workaround for an issue where the content scroll behind the header on focus
       flex: 1;
       
       margin-block: calc(bk.$spacing-7 / 2) calc(bk.$spacing-7 / 2);
@@ -91,5 +93,12 @@
     
     // State: focus
     @include bk.focus-outset;
+    // .bk-dialog__content {
+    //   @include bk.focus-hidden;
+    // }
+    // @include bk.focus-hidden;
+    // &:has(.bk-dialog__content:focus-visible), .pseudo-focus-visible {
+    //   @include bk.focus-outset($selector: '&');
+    // }
   }
 }
diff --git a/src/components/containers/Dialog/Dialog.tsx b/src/components/containers/Dialog/Dialog.tsx
index ed410973..2f5ceac0 100644
--- a/src/components/containers/Dialog/Dialog.tsx
+++ b/src/components/containers/Dialog/Dialog.tsx
@@ -17,6 +17,18 @@ import cl from './Dialog.module.scss';
 
 export { cl as DialogClassNames };
 
+
+export type DialogContext = {
+  close: () => void,
+};
+export const DialogContext = React.createContext<null | DialogContext>(null);
+export const useDialogContext = () => {
+  const context = React.use(DialogContext);
+  if (context === null) { throw new Error(`Cannot read DialogContext: missing provider.`); }
+  return context;
+};
+
+
 type ActionProps = ComponentProps<typeof Button> & {
   /** Optional tooltip text. */
   tooltip?: undefined | ComponentProps<typeof TooltipProvider>['tooltip'],
@@ -52,8 +64,16 @@ const ActionIcon = ({ tooltip, ...buttonProps }: ActionIconProps) => {
   );
 };
 
-const CancelAction = (props: ActionProps) => <Action variant="secondary" label="Cancel" {...props}/>;
-const SubmitAction = (props: ActionProps) => <Action variant="primary" label="Submit" {...props}/>;
+const CancelAction = (props: ActionProps) => {
+  const context = useDialogContext();
+  const handlePress = () => { props.onPress?.(); context.close(); };
+  return <Action variant="secondary" label="Cancel" {...props} onPress={handlePress}/>;
+};
+const SubmitAction = (props: ActionProps) => {
+  const context = useDialogContext();
+  const handlePress = () => { props.onPress?.(); context.close(); };
+  return <Action variant="primary" label="Submit" {...props} onPress={handlePress}/>;
+};
 
 export type DialogProps = Omit<ComponentProps<'dialog'>, 'title'> & {
   /** Whether this component should be unstyled. Default: false. */
@@ -98,56 +118,72 @@ export const Dialog = Object.assign(
       ...propsRest
     } = props;
     
+    const dialogId = React.useId();
     const dialogRef = React.useRef<HTMLDialogElement>(null);
-    const scrollerProps = useScroller();
+    const scrollerProps = useScroller(); // FIXME: add `{ hasFocusableChild: true }`?
     
     if ((showCloseIcon || showCancelAction) && typeof onRequestClose !== 'function') {
       console.error(`Missing prop in <Dialog/>: 'onRequestClose' function`);
     }
     
+    const dialogContext = React.useMemo<DialogContext>(() => ({
+      close: onRequestClose ?? (() => { console.warn('Missing `onRequestClose` callback.'); })
+    }), [onRequestClose]);
+    
     return (
-      <dialog
-        open
-        {...scrollerProps}
-        {...propsRest}
-        ref={mergeRefs(dialogRef, propsRest.ref)}
-        className={cx(
-          'bk',
-          { [cl['bk-dialog']]: !unstyled },
-          { [cl['bk-dialog--flat']]: flat },
-          scrollerProps.className,
-          propsRest.className,
-        )}
-      >
-        <header className={cx(cl['bk-dialog__header'])}>
-          <H5 className={cx(cl['bk-dialog__header__title'])}>{title}</H5>
+      <DialogContext value={dialogContext}>
+        <dialog
+          open
+          //role="dialog" // Default role. Change this to `role="alertdialog"` for things like confirmation modals.
+          aria-labelledby={`${dialogId}-title`}
+          aria-describedby={`${dialogId}-content`}
+          {...scrollerProps}
+          {...propsRest}
+          ref={mergeRefs(dialogRef, propsRest.ref)}
+          className={cx(
+            'bk',
+            { [cl['bk-dialog']]: !unstyled },
+            { [cl['bk-dialog--flat']]: flat },
+            scrollerProps.className,
+            propsRest.className,
+          )}
+        >
+          <header className={cx(cl['bk-dialog__header'])}>
+            <H5 id={`${dialogId}-title`} className={cx(cl['bk-dialog__header__title'])}>{title}</H5>
+            
+            <div className={cx(cl['bk-dialog__header__actions'])}>
+              {showCloseIcon &&
+                <ActionIcon
+                  autoFocus={autoFocusClose}
+                  label="Close dialog"
+                  tooltip={null}
+                  className={cx(cl['bk-dialog__header-action-close'])}
+                  onPress={onRequestClose}
+                >
+                  <Icon icon="cross"/>
+                </ActionIcon>
+              }
+            </div>
+          </header>
+          
+          <section
+            id={`${dialogId}-content`} // Used with `aria-describedby`
+            role="document" // https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/document_role
+            // FIXME: make this focusable instead of the <dialog> as per guidelines on MDN?
+            //tabIndex={0}
+            className={cx(cl['bk-dialog__content'], 'bk-body-text')}
+          >
+            {children}
+          </section>
           
-          <div className={cx(cl['bk-dialog__header__actions'])}>
-            {showCloseIcon &&
-              <ActionIcon
-                autoFocus={autoFocusClose}
-                label="Close dialog"
-                tooltip={null}
-                className={cx(cl['bk-dialog__header-action-close'])}
-                onPress={onRequestClose}
-              >
-                <Icon icon="cross"/>
-              </ActionIcon>
-            }
-          </div>
-        </header>
-        
-        <section className={cx(cl['bk-dialog__content'], 'bk-body-text')}>
-          {children}
-        </section>
-        
-        {(showCancelAction || actions) &&
-          <footer className={cx(cl['bk-dialog__actions'])}>
-            {showCancelAction && <CancelAction/>}
-            {actions}
-          </footer>
-        }
-      </dialog>
+          {(showCancelAction || actions) &&
+            <footer className={cx(cl['bk-dialog__actions'])}>
+              {showCancelAction && <CancelAction/>}
+              {actions}
+            </footer>
+          }
+        </dialog>
+      </DialogContext>
     );
   },
   {
diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 5be4f7e3..495f8629 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -57,7 +57,7 @@ export const DialogModalNested: Story = {
   },
 };
 
-export const DialogModalNoncloseable: Story = {
+export const DialogModalUncloseable: Story = {
   args: {
     activeDefault: true,
     allowUserClose: false,
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 444bf719..63c207a2 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -92,6 +92,9 @@ export const useConfirmationModal = <S,>(
     ...modal,
     props: {
       ...modal.props,
+      // A confirmation modal must use the `role="alertdialog"` rather than the default `role="dialog"`.
+      // See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role
+      role: 'alertdialog',
       display: 'center' as const,
       size: 'small' as const,
       allowUserClose: false, // Force the user to explicitly select an action
@@ -133,12 +136,13 @@ export const DialogModal = Object.assign(
         shouldCloseOnBackdropClick={display !== 'full-screen'}
         dialog={dialogController =>
           <Dialog
-            flat={[/*'full-screen', */'slide-over'].includes(display)}
+            aria-modal="true"
+            flat={['slide-over'].includes(display)}
             {...dialogController.dialogProps}
             showCloseIcon={allowUserClose}
             autoFocusClose={allowUserClose}
             showCancelAction={allowUserClose}
-            onRequestClose={allowUserClose ? dialogController.close : undefined}
+            onRequestClose={dialogController.close}
             {...propsRest}
             className={cx(
               'bk',
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index c6a8c05e..2918290b 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -61,6 +61,7 @@ export const ModalProviderWithRef: Story = {
   render: args => <ModalProviderAutoOpen {...args}/>,
   args: {
     children: () => <>Modal will open automatically after 2 seconds.</>,
-    dialog: ({ dialogProps }) => <dialog {...dialogProps}>This modal was opened through a ref.</dialog>,
+    dialog: ({ dialogProps }) =>
+      <dialog aria-modal="true" {...dialogProps}>This modal was opened through a ref.</dialog>,
   }
 };
diff --git a/src/components/overlays/SpinnerModal/SpinnerModal.tsx b/src/components/overlays/SpinnerModal/SpinnerModal.tsx
index c5887a36..693531bd 100644
--- a/src/components/overlays/SpinnerModal/SpinnerModal.tsx
+++ b/src/components/overlays/SpinnerModal/SpinnerModal.tsx
@@ -44,7 +44,7 @@ export const SpinnerModal = (props: SpinnerModalProps) => {
       allowUserClose={false}
       unmountDelay={0} // No exit animation, once done we want the spinner away as fast as possible
       dialog={({ dialogProps }) =>
-        <dialog {...dialogProps} inert>
+        <dialog {...dialogProps} inert aria-modal="true">
           <Spinner
             size="large"
             {...propsRest}
diff --git a/src/components/text/Tag/Tag.module.scss b/src/components/text/Tag/Tag.module.scss
index 427cf31a..9d82d302 100644
--- a/src/components/text/Tag/Tag.module.scss
+++ b/src/components/text/Tag/Tag.module.scss
@@ -7,25 +7,30 @@
 @layer baklava.components {
   .bk-tag {
     @include bk.component-base(bk-tag);
-
-    background: bk.$theme-tag-background-default;
+    
+    flex-shrink: 0;
+    
+    padding: bk.$size-2 bk.$spacing-2;
     border-radius: bk.$size-2;
+    background: bk.$theme-tag-background-default;
     color: bk.$theme-tag-text-default;
+    
     display: flex;
     align-items: center;
+    column-gap: bk.$spacing-2;
     font-size: bk.$font-size-xs;
-    padding: bk.$size-2 bk.$spacing-2 bk.$size-3;
-    flex-shrink: 0;
-
-    &.bk-tag--with-close-button {
-      padding-right: 0;
-    }
-
-    .bk-tag__icon {
-      cursor: pointer;
-      font-size: 1.2em;
+    
+    --bk-tag--with-close-button { --keep: ; }
+    
+    .bk-tag__action {
+      font-size: 0.9em;
       color: bk.$theme-tag-icon-default;
-      padding: bk.$size-2 bk.$spacing-2 bk.$size-2 bk.$spacing-2;
+      
+      display: flex;
+      
+      .bk-tag__icon {
+        display: block;
+      }
     }
   }
 }
diff --git a/src/components/text/Tag/Tag.tsx b/src/components/text/Tag/Tag.tsx
index b0d1c28e..4b1c77b3 100644
--- a/src/components/text/Tag/Tag.tsx
+++ b/src/components/text/Tag/Tag.tsx
@@ -47,7 +47,7 @@ export const Tag = (props: TagProps) => {
     >
       {content}
       {onRemove && (
-        <Button unstyled onPress={onRemove} aria-label="Remove tag">
+        <Button unstyled onPress={onRemove} aria-label="Remove tag" className={cl['bk-tag__action']}>
           <Icon icon="cross" className={cl['bk-tag__icon']}/>
         </Button>
       )}
diff --git a/src/layouts/util/Scroller.module.scss b/src/layouts/util/Scroller.module.scss
index c24f2d12..016141ea 100644
--- a/src/layouts/util/Scroller.module.scss
+++ b/src/layouts/util/Scroller.module.scss
@@ -4,6 +4,8 @@
 
 @layer baklava.overrides {
   .bk-util-scroller {
+    overscroll-behavior: none;
+    
     // stylelint-disable-next-line declaration-property-value-disallowed-list
     &.bk-util-scroller--vertical { overflow-y: auto; }
     
diff --git a/src/layouts/util/Scroller.tsx b/src/layouts/util/Scroller.tsx
index 815056b1..f15e911c 100644
--- a/src/layouts/util/Scroller.tsx
+++ b/src/layouts/util/Scroller.tsx
@@ -8,7 +8,14 @@ import cl from './Scroller.module.scss';
 
 
 type UseScrollerArgs = {
+  /**
+   * Set this to true if you know for sure there is a focusable child inside the scroller that can be used
+   * for keyboard scrolling purposes. If true, this scroller will not be made focusable. Default: false.
+   */
+  hasFocusableChild?: undefined | boolean,
+  /** Whether to include scroller styling automatically. Default: true. */
   includeStyling?: undefined | boolean,
+  /** Which direction(s) can be scrolled in. Default: vertical. */
   scrollDirection?: undefined | 'vertical' | 'horizontal' | 'both',
 };
 
@@ -25,6 +32,7 @@ type ScrollerProps = {
  */
 export const useScroller = (args: UseScrollerArgs = {}): ScrollerProps => {
   const {
+    hasFocusableChild = false,
     includeStyling = true,
     scrollDirection = 'vertical',
   } = args;
@@ -37,7 +45,7 @@ export const useScroller = (args: UseScrollerArgs = {}): ScrollerProps => {
   );
   
   return {
-    tabIndex: 0,
+    tabIndex: hasFocusableChild ? undefined : 0,
     className: includeStyling ? className : undefined,
   };
 };
diff --git a/src/styling/defs.scss b/src/styling/defs.scss
index dcd73e64..a75a07e2 100644
--- a/src/styling/defs.scss
+++ b/src/styling/defs.scss
@@ -45,6 +45,10 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+  
+  // Add a little bit of padding to prevent parts of characters getting cut off in some browsers. For example,
+  // try the letter "J" and view it in Safari, the bottom extender of the "J" overflows the text box and gets cut off.
+  padding-inline: 0.3ch;
 }
 
 @mixin flex-center() {
diff --git a/src/styling/global/accessibility.scss b/src/styling/global/accessibility.scss
index abe36733..38076e1f 100644
--- a/src/styling/global/accessibility.scss
+++ b/src/styling/global/accessibility.scss
@@ -2,17 +2,25 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+@mixin focus-hidden($override-layer: true) {
+  --bk-focus-color-anim: transparent; // Start transparent for animation purposes
+  
+  &, &.pseudo-focus-visible {
+    box-shadow: none if($override-layer, !important, null);
+    outline: none if($override-layer, !important, null);
+  }
+}
+
 // Configure an element with a focus outline outset from the element.
-@mixin focus-outset($override-layer: true) {
+@mixin focus-outset($selector: '&:focus-visible, &.pseudo-focus-visible', $override-layer: true) {
   --bk-focus-color-anim: transparent; // Start transparent for animation purposes
   
   box-shadow: none if($override-layer, !important, null); // Remove focus-inset, if any
-  
   outline: var(--bk-focus-outline-width) solid var(--bk-focus-color-anim) if($override-layer, !important, null);
   
-  // Add `.pseudo-focus-visible` for visual testing purposes
-  &:focus-visible, &.pseudo-focus-visible {
-    --bk-focus-color-anim: var(--bk-focus-outline-color);
+  // Should add `.pseudo-focus-visible` here for visual testing purposes
+  #{$selector} {
+    --bk-focus-color-anim: var(--bk-focus-outline-color) #{if($override-layer, !important, null)};
   }
   
   @media (prefers-reduced-motion: no-preference) {
@@ -22,7 +30,7 @@
 
 // Configure an element with a focus outline inset into the element. This can be useful for elements
 // that have overflow hidden and thus can't have an exterior outline.
-@mixin focus-inset($override-layer: true) {
+@mixin focus-inset($selector: '&:focus-visible, &.pseudo-focus-visible', $override-layer: true) {
   --bk-focus-color-anim: transparent; // Start transparent for animation purposes
   
   outline: none if($override-layer, !important, null); // Remove focus-outset, if any
@@ -35,7 +43,7 @@
     inset calc(-1 * $w) calc(-1 * $w) var(--bk-focus-color-anim) if($override-layer, !important, null);
   
   // Add `.pseudo-focus-visible` for visual testing purposes
-  &:focus-visible, &.pseudo-focus-visible {
+  #{$selector} {
     --bk-focus-color-anim: var(--bk-focus-outline-color);
   }
   
diff --git a/src/styling/global/reset.scss b/src/styling/global/reset.scss
index d355573f..288c474a 100644
--- a/src/styling/global/reset.scss
+++ b/src/styling/global/reset.scss
@@ -85,13 +85,14 @@
   whether it's going to be used as a modal or not, if we also want exit transitions.
   
   This reset assumes you do *not* apply an exit transition. If you do want an exit transition, you must also apply
-  the `position: fixed` (etc.) styling on the base `dialog`.
+  the `position: fixed` (etc.) styling on the base `dialog`. Or you can use `aria-model="true"` and opt in to base
+  styling that way.
   
   - https://github.com/w3c/csswg-drafts/issues/9912 - "User-agent styles for top layer transitions"
   - https://github.com/whatwg/html/pull/9387#issuecomment-1599722425
   - https://issues.chromium.org/issues/40270744 - `:-internal-dialog-in-top-layer`
   */
-  dialog:modal {
+  dialog[aria-modal='true'], dialog:modal {
     position: fixed;
     inset: 0;
     
@@ -99,10 +100,11 @@
     //place-self: center; // In the future can use this instead of `margin: auto`
     width: fit-content;
     height: fit-content;
-  }
-  dialog::backdrop {
-    position: fixed;
-    inset: 0;
-    background: rgba(0 0 0 / 20%);
+    
+    &::backdrop {
+      position: fixed;
+      inset: 0;
+      background: rgba(0 0 0 / 20%);
+    }
   }
 }

From b3e1007d6d3be4e3478687d0db1fa0a156dbcd41 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sun, 5 Jan 2025 22:57:52 +0100
Subject: [PATCH 31/33] Refactor useConfirmationModal().

---
 .../DialogModal/DialogModal.stories.tsx       | 17 ++++---
 .../overlays/DialogModal/DialogModal.tsx      | 45 +++++++++++++++----
 src/util/types.ts                             |  6 +++
 3 files changed, 53 insertions(+), 15 deletions(-)

diff --git a/src/components/overlays/DialogModal/DialogModal.stories.tsx b/src/components/overlays/DialogModal/DialogModal.stories.tsx
index 495f8629..5fcb5b1e 100644
--- a/src/components/overlays/DialogModal/DialogModal.stories.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.stories.tsx
@@ -121,7 +121,7 @@ export const DialogModalWithRef: Story = {
 
 const DialogModalControlledWithSubject = (props: React.ComponentProps<typeof DialogModal>) => {
   type Subject = { name: string };
-  const modal = DialogModal.useModalWithSubject<null | Subject>(null);
+  const modal = DialogModal.useModalWithSubject<Subject>();
   
   return (
     <article className="bk-body-text">
@@ -147,10 +147,11 @@ export const DialogModalWithSubject: Story = {
 
 const DialogModalControlledConfirmation = (props: React.ComponentProps<typeof DialogModal>) => {
   type Subject = { name: string };
-  const deleteConfirmer = DialogModal.useConfirmationModal<null | Subject>(null, {
+  const [deleted, setDeleted] = React.useState(new Set());
+  const deleteConfirmer = DialogModal.useConfirmationModal<Subject>({
     actionLabel: 'Delete',
-    onConfirm() { globalThis.alert('Confirmed'); },
-    onCancel() { globalThis.alert('Canceled'); },
+    onConfirm(subject) { setDeleted(deleted => new Set([...deleted, subject.name])); },
+    onCancel(subject) { console.log(`Canceled deleting ${subject.name}`); },
   });
   
   return (
@@ -164,12 +165,16 @@ const DialogModalControlledConfirmation = (props: React.ComponentProps<typeof Di
       <p>A single details modal will be used, filled in with the subject based on which name was pressed.</p>
       
       <p>
-        <Button variant="primary" label="Delete Item 1"
+        <Button variant="primary"
+          label={deleted.has('Item 1') ? 'Deleted' : `Delete Item 1`}
+          disabled={deleted.has('Item 1')}
           onPress={() => { deleteConfirmer.activateWith({ name: 'Item 1' }); }}
         />
       </p>
       <p>
-        <Button variant="primary" label="Delete Item 2"
+        <Button variant="primary"
+          label={deleted.has('Item 2') ? 'Deleted' : `Delete Item 2`}
+          disabled={deleted.has('Item 2')}
           onPress={() => { deleteConfirmer.activateWith({ name: 'Item 2' }); }}
         />
       </p>
diff --git a/src/components/overlays/DialogModal/DialogModal.tsx b/src/components/overlays/DialogModal/DialogModal.tsx
index 63c207a2..1f3c6353 100644
--- a/src/components/overlays/DialogModal/DialogModal.tsx
+++ b/src/components/overlays/DialogModal/DialogModal.tsx
@@ -2,6 +2,8 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+import type { NonUndefined } from '../../../util/types.ts';
+
 import * as React from 'react';
 import { flushSync } from 'react-dom';
 import { mergeRefs } from '../../../util/reactUtil.ts';
@@ -52,16 +54,22 @@ export type DialogModalProps = Omit<React.ComponentProps<typeof Dialog>, 'childr
 
 export type ModalWithSubject<S> = {
   props: Partial<DialogModalProps>,
-  subject: S,
+  subject: undefined | S,
   activateWith: (subject: S | (() => S)) => void,
 };
 /**
  * Utility hook to get a reference to a `DialogModal` for imperative usage. To open, you can call `activate()`, or
  * `activateWith()` if you want to include some subject data to be shown in the modal.
  */
-export const useModalWithSubject = <S,>(subjectInitial: S | (() => S)): ModalWithSubject<S> => {
+export const useModalWithSubject = <S,>(
+  config?: undefined | {
+    subjectInitial?: undefined | S | (() => undefined | S),
+  },
+): ModalWithSubject<S> => {
+  const { subjectInitial } = config ?? {};
+  
   const modalRef = ModalProvider.useRef(null);
-  const [subject, setSubject] = React.useState(subjectInitial);
+  const [subject, setSubject] = React.useState<undefined | S>(subjectInitial);
   
   return {
     props: { modalRef },
@@ -80,14 +88,15 @@ export const useModalWithSubject = <S,>(subjectInitial: S | (() => S)): ModalWit
  * Similar to `useModalWithSubject`, but will be preconfigured for usage as a confirmation modal.
  */
 export const useConfirmationModal = <S,>(
-  subjectInitial: S | (() => S),
   config: {
+    subjectInitial?: undefined | S | (() => undefined | S),
     actionLabel?: undefined | string,
-    onConfirm: () => void,
-    onCancel?: undefined | (() => void)
+    onConfirm: (subject: NonUndefined<S>) => void,
+    onCancel?: undefined | ((subject: NonUndefined<S>) => void)
   },
 ) => {
-  const modal = useModalWithSubject(subjectInitial);
+  const { subjectInitial, actionLabel, onConfirm, onCancel } = config;
+  const modal = useModalWithSubject({ subjectInitial });
   return {
     ...modal,
     props: {
@@ -102,8 +111,26 @@ export const useConfirmationModal = <S,>(
       children: 'Are you sure you want to perform this action?',
       actions: (
         <>
-          <Dialog.CancelAction label="Cancel" onPress={config.onCancel}/>
-          <Dialog.SubmitAction label={config.actionLabel || 'Confirm'} onPress={config.onConfirm}/>
+          <Dialog.CancelAction label="Cancel"
+            onPress={() => {
+              const subject = modal.subject;
+              if (typeof subject === 'undefined') {
+                console.error(`Unexpected: missing subject in confirmation`);
+                return;
+              }
+              onCancel?.(subject);
+            }}
+          />
+          <Dialog.SubmitAction label={actionLabel || 'Confirm'}
+            onPress={() => {
+              const subject = modal.subject;
+              if (typeof subject === 'undefined') {
+                console.error(`Unexpected: missing subject in confirmation`);
+                return;
+              }
+              onConfirm(subject);
+            }}
+          />
         </>
       ),
     },
diff --git a/src/util/types.ts b/src/util/types.ts
index a2349d12..4b7dc0b7 100644
--- a/src/util/types.ts
+++ b/src/util/types.ts
@@ -2,6 +2,12 @@
 |* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
 |* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+// TypeScript has `NonNullable` built in, but not `NonUndefined`.
+// Note: when TS refines non-undefined, it produces `T & ({} | null)`. Do not define this type as
+// `T extends undefined ? never : T`, because you cannot `T & ({} | null)` cannot be assigned to such a conditional.
+// https://www.typescriptlang.org/play/?#code/LAKAxg9gdgzgLgAgGZQQXgQHgCoBoB8AFAIYBOA5gFwLYCU6+CA3qAmwgJZIKFwCeABwCmEbmXLo0GAOQBXKABMhSDlCELp9FiHa6EpIXFmkoAblbsAvhbbjzIS-aA
+export type NonUndefined<T> = T & ({} | null);
+
 // https://stackoverflow.com/questions/39419170/how-do-i-check-that-a-switch-block-is-exhaustive-in-typescript
 export const assertUnreachable = (x: never): never => {
   throw new Error(`Unexpected case`);

From 29d744636618c64d5310167b25f069bfe33b1ec4 Mon Sep 17 00:00:00 2001
From: mkrause <maikel.krause@fortanix.com>
Date: Sun, 5 Jan 2025 23:00:57 +0100
Subject: [PATCH 32/33] Fix type error.

---
 src/layouts/util/Scroller.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/layouts/util/Scroller.tsx b/src/layouts/util/Scroller.tsx
index f15e911c..391e70b0 100644
--- a/src/layouts/util/Scroller.tsx
+++ b/src/layouts/util/Scroller.tsx
@@ -20,7 +20,7 @@ type UseScrollerArgs = {
 };
 
 type ScrollerProps = {
-  tabIndex: number,
+  tabIndex?: undefined | number,
   // Note: don't use `ClassNameArgument`, because that forces all consumers to apply `cx()`
   className?: undefined | string,
 };

From 6c66420368c0a030be251783058352b1e664ee00 Mon Sep 17 00:00:00 2001
From: mkrause <maikelkrause@gmail.com>
Date: Mon, 6 Jan 2025 23:50:15 +0100
Subject: [PATCH 33/33] Fix review comments.

---
 src/components/containers/Dialog/Dialog.module.scss        | 7 -------
 src/components/containers/Dialog/Dialog.stories.tsx        | 2 --
 .../overlays/ModalProvider/ModalProvider.stories.tsx       | 2 +-
 3 files changed, 1 insertion(+), 10 deletions(-)

diff --git a/src/components/containers/Dialog/Dialog.module.scss b/src/components/containers/Dialog/Dialog.module.scss
index 0aa38579..d49a5610 100644
--- a/src/components/containers/Dialog/Dialog.module.scss
+++ b/src/components/containers/Dialog/Dialog.module.scss
@@ -93,12 +93,5 @@
     
     // State: focus
     @include bk.focus-outset;
-    // .bk-dialog__content {
-    //   @include bk.focus-hidden;
-    // }
-    // @include bk.focus-hidden;
-    // &:has(.bk-dialog__content:focus-visible), .pseudo-focus-visible {
-    //   @include bk.focus-outset($selector: '&');
-    // }
   }
 }
diff --git a/src/components/containers/Dialog/Dialog.stories.tsx b/src/components/containers/Dialog/Dialog.stories.tsx
index a5af8adc..a066aa92 100644
--- a/src/components/containers/Dialog/Dialog.stories.tsx
+++ b/src/components/containers/Dialog/Dialog.stories.tsx
@@ -8,8 +8,6 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { LayoutDecorator } from '../../../util/storybook/LayoutDecorator.tsx';
 import { loremIpsum, LoremIpsum } from '../../../util/storybook/LoremIpsum.tsx';
 
-import { Button } from '../../actions/Button/Button.tsx';
-
 import { Dialog } from './Dialog.tsx';
 
 
diff --git a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
index 2918290b..3a42ed2f 100644
--- a/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
+++ b/src/components/overlays/ModalProvider/ModalProvider.stories.tsx
@@ -49,7 +49,7 @@ const ModalProviderAutoOpen = (props: React.ComponentProps<typeof ModalProvider>
   const ref = ModalProvider.useRef(null);
   
   // biome-ignore lint/correctness/useExhaustiveDependencies: want to only trigger this once
-    React.useEffect(() => {
+  React.useEffect(() => {
     globalThis.setTimeout(() => {
       ref.current?.activate();
     }, 2000);