@sveltia/ui 0.55.0 → 0.56.0

package/dist/components/util/modal.svelte

@@ -2,9 +2,25 @@
   @component
   A generic modal top-layer helper based on the HTML `<dialog>` element.
 -->
+<script module>
+  /**
+   * Context key used by a modal to keep the modal it’s rendered within mounted.
+   * @type {symbol}
+   */
+  const RETAINER_KEY = Symbol('sui-modal-retainer');
+</script>
+
 <script>
-  import { sleep } from '@sveltia/utils/misc';
-  import { mount, onMount, unmount } from 'svelte';
+  import {
+    getAllContexts,
+    getContext,
+    mount,
+    onMount,
+    setContext,
+    tick,
+    unmount,
+    untrack,
+  } from 'svelte';
   import Placeholder from './placeholder.svelte';
 
   /**
@@ -58,7 +74,67 @@
 
   let setOpenClass = $state(false);
   let setActiveClass = $state(false);
-  let showContent = $state(false);
+  /**
+   * Whether the modal is being displayed. This is enabled just before the opening transition
+   * starts, and disabled right after the closing transition is complete.
+   * @type {boolean}
+   */
+  let visible = $state(false);
+
+  /**
+   * The number of descendant modals that are currently being displayed. A popup’s content is
+   * unmounted as soon as the popup closes, which would also destroy any modal declared alongside
+   * it, such as a dialog opened from a menu item. Because the menu item inevitably goes away with
+   * the menu, the dialog has to outlive it, so the content is held until the dialog is done with.
+   * @type {number}
+   */
+  let retainCount = $state(0);
+
+  /**
+   * The retainer of the modal this modal is rendered within, if any. This has to be read before the
+   * `setContext()` call below, which would otherwise shadow it with this modal’s own retainer.
+   * @type {{ retain: () => void, release: () => void } | undefined}
+   */
+  const parentRetainer = getContext(RETAINER_KEY);
+
+  // This has to be set before `getAllContexts()` below, so the content, which is rendered in a
+  // separate component tree, can reach it. The counter is updated within `untrack()`, because
+  // incrementing it reads it first, which would otherwise make it a dependency of the calling
+  // descendant’s effect and send that effect into an endless retain/release loop.
+  setContext(RETAINER_KEY, {
+    /**
+     * Keep this modal mounted on behalf of a descendant modal.
+     */
+    retain: () => {
+      untrack(() => {
+        retainCount += 1;
+      });
+    },
+    /**
+     * Release a hold previously acquired with `retain`.
+     */
+    release: () => {
+      untrack(() => {
+        retainCount -= 1;
+      });
+    },
+  });
+
+  /**
+   * Whether the `<dialog>` element is in the DOM tree. Unless {@link keepContent} is enabled, the
+   * element is mounted on demand, and unmounted once the closing transition is complete.
+   * @type {boolean}
+   */
+  const mounted = $derived(keepContent || visible || retainCount > 0);
+
+  /**
+   * Whether the modal has been requested to open. Unlike the {@link open} prop, this is a plain
+   * variable updated synchronously at the very beginning of `openDialog`/`closeDialog`, so either
+   * of them can bail out early when the requested state is already in effect.
+   * @type {boolean}
+   */
+  let requestedOpen = false;
+
   /**
    * Monotonically increasing counter used to detect stale async operations. Incremented at the
    * start of each `openDialog`/`closeDialog` call; any suspended continuation that finds its
@@ -68,44 +144,78 @@
    */
   let generation = 0;
 
+  /**
+   * Get the longest time from a computed CSS time list, such as `transition-duration`.
+   * @param {string} value Comma-separated CSS time values in seconds, e.g. `0.4s, 0.15s`.
+   * @returns {number} Time in milliseconds.
+   */
+  const getLongestTime = (value) =>
+    Math.max(0, ...value.split(',').map((time) => Number.parseFloat(time) || 0)) * 1000;
+
   /**
    * Resolve once the transition is complete.
    * @returns {Promise<void>} Nothing.
    */
-  const waitForTransition = async () =>
-    new Promise((resolve) => {
-      /**
-       * Transition event listener.
-       * @param {TransitionEvent} event `transition` event.
-       */
-      const listener = (event) => {
+  const waitForTransition = async () => {
+    // Let the CSS class change be applied first, so the duration below is read from the new state
+    await tick();
+
+    if (!dialog) {
+      return;
+    }
+
+    const { transitionDuration, transitionDelay } = getComputedStyle(dialog);
+    // Fall back to a timer, so the modal is never stuck half-open (and, more importantly, never
+    // left mounted) in case `transitionend` is never fired, e.g. when the transition is removed by
+    // the consumer’s CSS or the element is not rendered at all
+    const timeout = getLongestTime(transitionDuration) + getLongestTime(transitionDelay) + 100;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    dialog.addEventListener(
+      'transitionend',
+      (event) => {
         if (event.target === dialog) {
-          dialog.removeEventListener('transitionend', listener);
-          resolve();
+          controller.abort();
         }
-      };
+      },
+      { signal },
+    );
 
-      dialog?.addEventListener('transitionend', listener);
+    const timer = window.setTimeout(() => controller.abort(), timeout);
+
+    await new Promise((resolve) => {
+      signal.addEventListener('abort', () => resolve(undefined));
     });
 
+    window.clearTimeout(timer);
+  };
+
   /**
    * Show the modal.
    */
   const openDialog = async () => {
-    if (!dialog || dialog?.open) {
+    if (requestedOpen) {
       return;
     }
 
+    requestedOpen = true;
     generation += 1;
 
     const gen = generation;
 
     onOpening?.(new CustomEvent('Opening'));
-    showContent = true;
+    visible = true;
+    // Wait for the `<dialog>` element to be added to the DOM tree
+    await tick();
+
+    if (gen !== generation || !dialog || dialog.open) return;
+
     dialog.showModal();
     onOpen?.(new CustomEvent('Open'));
-    await sleep(0);
-    if (gen !== generation) return;
+    // Force a style recalculation, so the browser has a state to transition from. This is required
+    // because the element may have just been added to the DOM tree.
+    dialog.getBoundingClientRect();
     setOpenClass = true;
     await waitForTransition();
     if (gen !== generation) return;
@@ -116,21 +226,26 @@
    * Hide the modal.
    */
   const closeDialog = async () => {
-    if (!dialog || !dialog.open) {
+    if (!requestedOpen) {
       return;
     }
 
+    requestedOpen = false;
     generation += 1;
 
     const gen = generation;
     const wasOpen = setOpenClass;
-    const { returnValue } = dialog;
+    const returnValue = dialog?.returnValue ?? '';
 
     onClosing?.(new CustomEvent('Closing'));
-    // Prevent a button behind the `<dialog>` from being clicked erroneously (Svelte bug)
-    document.body.inert = true;
-    dialog.close();
-    document.body.inert = false;
+
+    if (dialog?.open) {
+      // Prevent a button behind the `<dialog>` from being clicked erroneously (Svelte bug)
+      document.body.inert = true;
+      dialog.close();
+      document.body.inert = false;
+    }
+
     setActiveClass = false;
     setOpenClass = false;
 
@@ -143,7 +258,8 @@
 
     if (gen !== generation) return;
 
-    showContent = false;
+    // Unmount the `<dialog>` element unless `keepContent` is enabled
+    visible = false;
 
     if (returnValue === 'ok') {
       onOk?.(new CustomEvent('Ok'));
@@ -154,22 +270,26 @@
     }
 
     onClose?.(new CustomEvent('Close', { detail: { returnValue } }));
-    dialog.returnValue = '';
-  };
 
-  $effect(() => {
-    if (open) {
-      openDialog();
-    } else {
-      closeDialog();
+    if (dialog) {
+      dialog.returnValue = '';
     }
-  });
+  };
+
+  /**
+   * The context available to this component. The `<dialog>` element is rendered in a separate
+   * component tree created with `mount()`, which would otherwise start with an empty context, so
+   * this is forwarded to keep `getContext()` working for the modal content.
+   * @type {Map<any, any>}
+   */
+  const context = getAllContexts();
 
   onMount(() => {
     const placeholder = mount(Placeholder, {
       target: document.querySelector('.sui.app-shell') ?? document.body,
       // eslint-disable-next-line no-use-before-define
       props: { children: dialogSnippet },
+      context,
     });
 
     // onUnmount
@@ -178,43 +298,67 @@
       unmount(placeholder);
     };
   });
+
+  // This must be declared after `onMount()` above, because effects run in declaration order, and
+  // `openDialog()` expects the placeholder holding the `<dialog>` element to be already mounted
+  $effect(() => {
+    if (open) {
+      openDialog();
+    } else {
+      closeDialog();
+    }
+  });
+
+  // Hold the enclosing modal, if any, for as long as this one is on screen. `visible` is used
+  // rather than `mounted`, so a `keepContent` modal doesn’t pin its ancestor forever
+  $effect(() => {
+    if (!visible) {
+      return undefined;
+    }
+
+    parentRetainer?.retain();
+
+    return () => {
+      parentRetainer?.release();
+    };
+  });
 </script>
 
 {#snippet dialogSnippet()}
-  <dialog
-    bind:this={dialog}
-    {...restProps}
-    inert={!setOpenClass}
-    {role}
-    class="sui modal {className}"
-    class:backdrop={showBackdrop}
-    class:open={setOpenClass}
-    class:active={setActiveClass}
-    onclick={({ target }) => {
-      if (
-        dialog &&
-        lightDismiss &&
-        /** @type {HTMLElement | undefined} */ (target)?.matches('dialog')
-      ) {
-        dialog.returnValue = 'cancel';
-        open = false;
-      }
-    }}
-    oncancel={(event) => {
-      event.preventDefault();
-
-      // Escape key is pressed
-      if (dialog && escapeDismiss) {
-        dialog.returnValue = 'cancel';
-        open = false;
-      }
-    }}
-  >
-    {@render extraContent?.()}
-    {#if showContent || keepContent}
+  {#if mounted}
+    <dialog
+      bind:this={dialog}
+      {...restProps}
+      inert={!setOpenClass}
+      {role}
+      class="sui modal {className}"
+      class:backdrop={showBackdrop}
+      class:open={setOpenClass}
+      class:active={setActiveClass}
+      onclick={({ target }) => {
+        if (
+          dialog &&
+          lightDismiss &&
+          /** @type {HTMLElement | undefined} */ (target)?.matches('dialog')
+        ) {
+          dialog.returnValue = 'cancel';
+          open = false;
+        }
+      }}
+      oncancel={(event) => {
+        event.preventDefault();
+
+        // Escape key is pressed
+        if (dialog && escapeDismiss) {
+          dialog.returnValue = 'cancel';
+          open = false;
+        }
+      }}
+    >
+      {@render extraContent?.()}
       {@render children?.()}
-    {/if}
-  </dialog>
+    </dialog>
+  {/if}
 {/snippet}
 
 <style>dialog {

package/dist/components/util/popup.svelte

@@ -55,11 +55,8 @@
   } = $props();
 
   /**
-   * @type {boolean}
-   */
-  let initialized = $state(false);
-  /**
-   * A reference to the `<dialog>` element.
+   * A reference to the `<dialog>` element. This is only available while the popup is open, because
+   * the element is mounted on demand.
    * @type {HTMLDialogElement | undefined}
    */
   let dialogElement = $state();
@@ -78,21 +75,12 @@
   /**
    * @type {{ style: { inset: string | undefined, zIndex: number | undefined, minWidth: string |
    * undefined, maxWidth: string | undefined, height: string | undefined }, open: boolean,
-   * checkPosition: () => void, destroy: () => void } | undefined}
+   * attachPopupElement: (popupElement: HTMLDialogElement, contentElement?: HTMLElement) => void,
+   * detachPopupElement: () => void, checkPosition: () => void, destroy: () => void } | undefined}
    */
   let popupInstance = $state();
   let hoveredTimeout = 0;
 
-  /**
-   * Initialize the popup.
-   */
-  const init = () => {
-    popupInstance = activatePopup(anchor, dialogElement, position, positionBaseElement);
-
-    contentType = anchor?.getAttribute('aria-haspopup') ?? undefined;
-    initialized = true;
-  };
-
   $effect(() => {
     if (popupInstance) {
       open = popupInstance.open;
@@ -106,14 +94,35 @@
     }
   });
 
+  // The instance must be created as soon as the anchor is available, without waiting for the
+  // `<dialog>` element, because it’s the instance that listens to the anchor and opens the popup —
+  // and therefore causes the element to be mounted in the first place
   $effect(() => {
-    if (anchor && dialogElement && !initialized) {
-      init();
+    if (anchor && !popupInstance) {
+      popupInstance = activatePopup(anchor, undefined, position, positionBaseElement);
+      contentType = anchor.getAttribute('aria-haspopup') ?? undefined;
     }
   });
 
+  // Attach the `<dialog>` element to the instance whenever it’s mounted, and detach it when it’s
+  // unmounted, which happens on every close. The content element is passed alongside it, because
+  // a nested popup shares the `<dialog>` with its parent and only the content is its own.
+  $effect(() => {
+    if (popupInstance && dialogElement && content) {
+      popupInstance.attachPopupElement(dialogElement, content);
+
+      return () => {
+        popupInstance?.detachPopupElement();
+      };
+    }
+
+    return undefined;
+  });
+
+  // The position can only be calculated once the content is in the DOM tree, so it has to be
+  // (re)checked here rather than in the instance’s `open` setter, which runs before the mount
   $effect(() => {
-    if (parentDialogElement && open) {
+    if (open && dialogElement) {
       popupInstance?.checkPosition();
     }
   });
@@ -175,7 +184,6 @@
     bind:open
     showBackdrop={showBackdrop ?? touch}
     lightDismiss={true}
-    keepContent={true}
     onOpen={async (event) => {
       onOpen?.(event);
 

package/dist/locales/pl.yaml

@@ -0,0 +1,113 @@
+# Dialog action button labels
+ok: OK
+cancel: Anuluj
+close: Zamknij
+
+# Button to clear content, e.g. search input or calendar date
+clear: Wyczyść
+
+# Text editor dialog buttons for link/image insertion
+insert: Wstaw
+update: Zaktualizuj
+remove: Usuń
+
+# Combobox dropdown toggle button aria-labels
+collapse: Zwiń
+expand: Rozwiń
+
+# Infobar/toast dismiss button label
+dismiss: Odrzuć
+
+# Calendar component
+calendar:
+  # View switcher group aria-labels and navigation button aria-labels
+  year: Rok
+  previous_decade: Poprzednia dekada
+  next_decade: Następna dekada
+  month: Miesiąc
+  previous_month: Poprzedni miesiąc
+  next_month: Następny miesiąc
+  # “Today” button label in footer
+  today: Dzisiaj
+
+# Split button component
+split_button:
+  # Wrapper aria-label, e.g. “Save Options” when primary button is “Save”
+  x_options: 'Opcje {$name}'
+  # Dropdown toggle aria-label
+  more_options: Więcej opcji
+
+# Combobox component
+combobox:
+  # Placeholder when no option is selected
+  select_an_option: Wybierz opcję…
+  # Filter input aria-label
+  filter_options: Filtruj opcje
+  # Empty state message when filter has no matches
+  no_matching_options: Nie znaleziono pasujących opcji
+
+# Number input component
+number_input:
+  # Spin button aria-labels for incrementing/decrementing the number value
+  increase: Zwiększ
+  decrease: Zmniejsz
+
+# Password input component
+password_input:
+  # Visibility toggle button aria-labels
+  show_password: Pokaż hasło
+  hide_password: Ukryj hasło
+
+# Secret input component (API keys, tokens, etc.)
+secret_input:
+  # Visibility toggle button aria-labels
+  show_secret: Pokaż sekret
+  hide_secret: Ukryj sekret
+
+# Select tags component (multi-select)
+select_tags:
+  # Listbox aria-label
+  selected_options: Wybrane opcje
+  # Remove button aria-label, e.g. “Remove Option 1”
+  remove_x: 'Usuń {$name}'
+
+# Text editor component
+text_editor:
+  # Toolbar aria-labels
+  text_editor: Edytor tekstu
+  code_editor: Edytor kodu
+  # Block style menu button and menu aria-labels
+  text_style_options: Opcje stylu tekstu
+  show_text_style_options: Pokaż opcje stylu tekstu
+  # Block style menu items
+  paragraph: Akapit
+  heading_1: Nagłówek 1
+  heading_2: Nagłówek 2
+  heading_3: Nagłówek 3
+  heading_4: Nagłówek 4
+  heading_5: Nagłówek 5
+  heading_6: Nagłówek 6
+  bulleted_list: Lista punktowana
+  numbered_list: Lista numerowana
+  blockquote: Cytat blokowy
+  code_block: Blok kodu
+  # Inline style button aria-labels
+  bold: Pogrubienie
+  italic: Kursywa
+  strikethrough: Przekreślenie
+  code: Kod
+  link: Odnośnik
+  # Link dialog title
+  insert_link: Wstaw odnośnik
+  update_link: Zaktualizuj odnośnik
+  # Link dialog input field labels
+  text: Tekst
+  url: URL
+  # Markdown mode toggle button aria-label
+  edit_in_markdown: Edytuj w Markdown
+  # Error message when rich text conversion fails
+  converter_error: Nie można włączyć trybu tekstu sformatowanego. Zamiast tego użyj zwykłego edytora tekstu.
+  # Language selector aria-label
+  language: Język
+  # Plain text mode option in language selector
+  plain_text: Zwykły tekst

package/dist/services/group.svelte.d.ts

@@ -29,10 +29,33 @@ export class Group {
     childSelectedProp: string;
     focusChild: boolean;
     selectFirst: boolean;
+    /**
+     * Whether a member’s `aria-controls` target is a panel this group owns, as with a tab and its
+     * tabpanel. Only then may the group hide the target when the member isn’t selected. Elsewhere
+     * `aria-controls` means something quite different — on a menu item it points at the submenu the
+     * item opens, and on a toolbar button at the region it acts on — and hiding those would break
+     * the very widget the member controls.
+     * @type {boolean}
+     */
+    controlsPanel: boolean;
+    /**
+     * Which member holds the group’s single tab stop. `selected` suits widgets where one member is
+     * the natural entry point, such as the checked radio or the current tab. `first` suits menus,
+     * where any number of items can be checked at once, so the checked state says nothing about
+     * where the keyboard should land.
+     * @type {'selected' | 'first'}
+     */
+    rovingTabStop: "selected" | "first";
     /**
      * Activate the members.
      */
     activate(): void;
+    /**
+     * Put exactly one member in the tab sequence, as a composite widget should. Giving every checked
+     * member `tabindex="0"` would scatter tab stops through the widget — a menu with two checked
+     * items would take three tab presses to step over.
+     */
+    updateTabStop(): void;
     /**
      * CSS selector to retrieve the members.
      * @type {string}
@@ -48,6 +71,40 @@ export class Group {
      * @type {HTMLElement[]}
      */
     get activeMembers(): HTMLElement[];
+    /**
+     * The element that opens this menu, either a menu button or a menu item in the menu above.
+     * @type {HTMLElement | null}
+     */
+    get opener(): HTMLElement | null;
+    /**
+     * The menu item that opens this menu, when this menu is a submenu. A menu button is deliberately
+     * excluded, because closing a top-level menu is not what “back to the parent item” means.
+     * @type {HTMLElement | null}
+     */
+    get parentMenuItem(): HTMLElement | null;
+    /**
+     * Close this menu along with every menu above it.
+     * @returns {HTMLElement | null} The element that opens the outermost menu, so the caller can
+     * hand focus back to it.
+     */
+    closeMenuChain(): HTMLElement | null;
+    /**
+     * Leave the menu the way Tab should: close it along with every menu above it, then carry focus on
+     * to whatever follows the outermost opener. The browser can’t be left to do this itself, because
+     * a modal `<dialog>` confines Tab to its own contents.
+     * @param {boolean} backwards Whether to move to the previous tab stop instead, as Shift+Tab.
+     */
+    leaveMenu(backwards: boolean): Promise<void>;
+    /**
+     * Open the submenu of the given menu item if needed, and move focus onto its first item.
+     * @param {HTMLElement} item Menu item with `aria-haspopup="menu"`.
+     */
+    enterSubmenu(item: HTMLElement): Promise<void>;
+    /**
+     * Close this submenu and move focus back onto the menu item that opens it.
+     * @param {HTMLElement} item Menu item with `aria-haspopup="menu"`.
+     */
+    leaveSubmenu(item: HTMLElement): void;
     /**
      * Get the currently selected member.
      * @type {HTMLElement | undefined}