@sveltia/ui 0.55.1 → 0.57.0

package/dist/services/popup.svelte.js

@@ -31,8 +31,18 @@ class Popup {
     } else if (this.anchorElement.getAttribute('aria-expanded') === 'true') {
       // Wait for the popup to close before focusing the anchor, otherwise the focus will be lost
       window.requestAnimationFrame(() => {
-        this.anchorElement.focus();
-        this.anchorElement.removeAttribute('aria-controls');
+        const { activeElement } = document;
+
+        // Only take focus back if it’s still inside the popup, or nowhere because the popup took it
+        // down with itself. If it has already moved on — the user tabbed out of the menu, say —
+        // pulling it back would undo what they just did.
+        if (
+          !activeElement ||
+          activeElement === document.body ||
+          this.popupElement?.contains(activeElement)
+        ) {
+          this.anchorElement.focus();
+        }
       });
     }
 
@@ -59,7 +69,18 @@ class Popup {
         return;
       }
 
-      const content = /** @type {HTMLElement} */ (this.popupElement.querySelector('.content'));
+      // Use the tracked content element rather than searching the popup element, which for a nested
+      // popup is the shared parent `<dialog>` and would yield the parent’s content
+      const content = /** @type {HTMLElement | null} */ (
+        this.contentElement ?? this.popupElement?.querySelector('.content') ?? null
+      );
+
+      // The content is not in the DOM tree yet; `checkPosition()` will be called again once the
+      // popup element is attached
+      if (!content) {
+        return;
+      }
+
       const { scrollHeight: contentHeight, scrollWidth: contentWidth } = content;
       const topMargin = intersectionRect.top - 8;
       const bottomMargin = rootBounds.height - intersectionRect.bottom - 8;
@@ -155,22 +176,44 @@ class Popup {
   });
 
   /**
-   * Initialize a new `Popup` instance.
+   * A reference to the `<dialog>` element used for the popup, which also serves as the backdrop.
+   * This is `undefined` while the element is not in the DOM tree, which is the case for a closed
+   * popup that doesn’t keep its content.
+   * @type {HTMLDialogElement | undefined}
+   */
+  popupElement = undefined;
+
+  /**
+   * A reference to the element holding the popup content. Unlike {@link popupElement}, which a
+   * nested popup shares with its parent, this element belongs to this popup alone, so it’s the one
+   * that carries the {@link id} and that the anchor’s `aria-controls` points at.
+   * @type {HTMLElement | undefined}
+   */
+  contentElement = undefined;
+
+  /**
+   * Function that removes the event listeners added to the current {@link popupElement}.
+   * @type {(() => void) | undefined}
+   */
+  #removeEventListeners = undefined;
+
+  /**
+   * Initialize a new `Popup` instance. Note that the `popupElement` is optional, because the
+   * element is typically mounted only while the popup is open. Use {@link attachPopupElement} to
+   * provide it later.
    * @param {HTMLButtonElement} anchorElement `<button>` element that triggers the popup.
-   * @param {HTMLDialogElement} popupElement `<dialog>` element to be used for the popup.
+   * @param {HTMLDialogElement | undefined} popupElement `<dialog>` element to be used for the
+   * popup, if it’s already in the DOM tree.
    * @param {PopupPosition} position Where to show the popup content.
    * @param {HTMLElement} [positionBaseElement] The base element of the `position`. If omitted, this
    * will be the `anchorElement`.
    */
   constructor(anchorElement, popupElement, position, positionBaseElement) {
     this.anchorElement = anchorElement;
-    this.popupElement = popupElement; // = backdrop
     this.position = position;
     this.positionBaseElement = positionBaseElement ?? anchorElement;
     this.id = generateElementId('popup');
 
-    this.anchorElement.setAttribute('aria-controls', this.id);
-    this.popupElement.setAttribute('id', this.id);
     this.anchorElement.setAttribute('aria-expanded', 'false');
 
     on(anchorElement, 'click', () => {
@@ -203,8 +246,45 @@ class Popup {
     });
     this.intersectionObserver.observe(this.anchorElement);
 
+    // Update the popup width when the base element is resized
+    this.resizeObserver = new ResizeObserver(() => {
+      cancelAnimationFrame(this._rafId);
+      this._rafId = requestAnimationFrame(() => this.checkPosition());
+    });
+    this.resizeObserver.observe(this.positionBaseElement);
+
+    if (popupElement) {
+      this.attachPopupElement(popupElement);
+    }
+  }
+
+  /**
+   * Attach the `<dialog>` element used for the popup. This is called every time the element is
+   * mounted, which happens on each open.
+   * @param {HTMLDialogElement} popupElement `<dialog>` element to be used for the popup. A nested
+   * popup shares this with its parent, so it must not be labelled as belonging to this popup.
+   * @param {HTMLElement} [contentElement] Element holding this popup’s content. When omitted, the
+   * `popupElement` is assumed to hold the content on its own.
+   */
+  attachPopupElement(popupElement, contentElement) {
+    if (this.popupElement === popupElement && this.contentElement === contentElement) {
+      return;
+    }
+
+    this.detachPopupElement();
+    this.popupElement = popupElement;
+    this.contentElement = contentElement;
+
+    // Identify the popup by the element that actually holds its content. Labelling the `<dialog>`
+    // would be wrong for a nested popup, which shares its parent’s: it would overwrite the parent’s
+    // own `id` and leave the anchor pointing at the parent instead of the submenu.
+    const identifiedElement = contentElement ?? popupElement;
+
+    identifiedElement.id = this.id;
+    this.anchorElement.setAttribute('aria-controls', this.id);
+
     // Close the popup when the backdrop, a menu item or an option is clicked
-    on(this.popupElement, 'click', (event) => {
+    const removeClickListener = on(popupElement, 'click', (event) => {
       event.stopPropagation();
 
       // eslint-disable-next-line prefer-destructuring
@@ -218,7 +298,7 @@ class Popup {
       }
     });
 
-    on(this.popupElement, 'keydown', (event) => {
+    const removeKeyDownListener = on(popupElement, 'keydown', (event) => {
       const { key, ctrlKey, metaKey, shiftKey, altKey } = event;
       const hasModifier = shiftKey || altKey || ctrlKey || metaKey;
 
@@ -229,12 +309,32 @@ class Popup {
       }
     });
 
-    // Update the popup width when the base element is resized
-    this.resizeObserver = new ResizeObserver(() => {
-      cancelAnimationFrame(this._rafId);
-      this._rafId = requestAnimationFrame(() => this.checkPosition());
-    });
-    this.resizeObserver.observe(this.positionBaseElement);
+    /**
+     * Remove the listeners added above.
+     */
+    this.#removeEventListeners = () => {
+      removeClickListener();
+      removeKeyDownListener();
+    };
+  }
+
+  /**
+   * Detach the `<dialog>` element, typically because it’s being unmounted. The `aria-controls`
+   * attribute on the anchor is left to the {@link open} setter, which removes it once the closing
+   * animation is complete.
+   */
+  detachPopupElement() {
+    this.#removeEventListeners?.();
+    this.#removeEventListeners = undefined;
+
+    // The content is leaving the DOM tree, so the anchor must stop referencing it. Only clear a
+    // reference this popup owns; the consumer may have pointed the anchor somewhere else.
+    if (this.anchorElement.getAttribute('aria-controls') === this.id) {
+      this.anchorElement.removeAttribute('aria-controls');
+    }
+
+    this.popupElement = undefined;
+    this.contentElement = undefined;
   }
 
   /**
@@ -254,9 +354,14 @@ class Popup {
   }
 
   /**
-   * Check the position of the anchor element.
+   * Check the position of the anchor element. This is a no-op while the popup element is not in the
+   * DOM tree; the caller is expected to call this again once the element is attached.
    */
   checkPosition() {
+    if (!this.popupElement) {
+      return;
+    }
+
     this.observer.unobserve(this.positionBaseElement);
     this.observer.observe(this.positionBaseElement);
   }
@@ -265,16 +370,24 @@ class Popup {
    * Hide the popup immediately (when the anchor is being hidden).
    */
   async hideImmediately() {
-    this.popupElement.hidden = true;
+    if (this.popupElement) {
+      this.popupElement.hidden = true;
+    }
+
     this.open = false;
     await sleep(50);
-    this.popupElement.hidden = false;
+
+    // The element may have been unmounted in the meantime
+    if (this.popupElement) {
+      this.popupElement.hidden = false;
+    }
   }
 
   /**
    * Dispose of the popup, disconnecting observers and canceling pending work.
    */
   destroy() {
+    this.detachPopupElement();
     this.intersectionObserver?.disconnect();
     this.resizeObserver?.disconnect();
     this.observer?.disconnect();

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

@@ -1,2 +1,51 @@
+/**
+ * Reactive registry of the `<Option>`s declared within a `<Combobox>`.
+ *
+ * The options only render their DOM while the dropdown is expanded, so a collapsed combobox can’t
+ * look them up with `querySelector`. Each `<Option>` instead registers a live view of its own props
+ * here, which lets the combobox resolve the current label and the initially selected value without
+ * keeping the option elements in the DOM tree.
+ *
+ * The order of the registered options is not significant. Svelte still renders the options itself,
+ * in declaration order, so nothing here has to reproduce that order.
+ */
+export class OptionRegistry {
+    /**
+     * Whether the dropdown is expanded, meaning the options should render their DOM.
+     * @type {boolean}
+     */
+    expanded: boolean;
+    /**
+     * Number of registered options.
+     * @returns {number} Count.
+     */
+    get count(): number;
+    /**
+     * The option that is currently marked as selected, if any.
+     * @returns {OptionEntry | undefined} Matching option.
+     */
+    get selectedEntry(): OptionEntry | undefined;
+    /**
+     * Register an option.
+     * @param {OptionEntry} entry Live view of the option’s props.
+     * @returns {() => void} Function to unregister the option.
+     */
+    register(entry: OptionEntry): () => void;
+    /**
+     * Find the option with the given value.
+     * @param {any} value Value to look for.
+     * @returns {OptionEntry | undefined} Matching option.
+     */
+    find(value: any): OptionEntry | undefined;
+    /**
+     * Mark the option with the given value as the only selected one.
+     * @param {any} value Value to select.
+     */
+    selectOnly(value: any): void;
+    #private;
+}
+export function createOptionRegistry(): OptionRegistry;
+export function getOptionRegistry(): OptionRegistry | undefined;
 export function getSelectedItemDetail(target: HTMLElement): SelectedItemDetail;
+import type { OptionEntry } from '../typedefs';
 import type { SelectedItemDetail } from '../typedefs';

package/dist/services/select.svelte.js

@@ -1,6 +1,104 @@
+import { getContext, setContext } from 'svelte';
+
+/**
+ * @import { OptionEntry, SelectedItemDetail } from '../typedefs';
+ */
+
+/**
+ * Context key for {@link OptionRegistry}.
+ */
+const CONTEXT_KEY = Symbol('sui-option-registry');
+
+/**
+ * Reactive registry of the `<Option>`s declared within a `<Combobox>`.
+ *
+ * The options only render their DOM while the dropdown is expanded, so a collapsed combobox can’t
+ * look them up with `querySelector`. Each `<Option>` instead registers a live view of its own props
+ * here, which lets the combobox resolve the current label and the initially selected value without
+ * keeping the option elements in the DOM tree.
+ *
+ * The order of the registered options is not significant. Svelte still renders the options itself,
+ * in declaration order, so nothing here has to reproduce that order.
+ */
+export class OptionRegistry {
+  /**
+   * Whether the dropdown is expanded, meaning the options should render their DOM.
+   * @type {boolean}
+   */
+  expanded = $state(false);
+
+  /**
+   * Registered options. This is a raw state so that the entries, which expose their properties as
+   * getters onto the `<Option>`’s props, are not wrapped in a reactive proxy.
+   * @type {OptionEntry[]}
+   */
+  #entries = $state.raw([]);
+
+  /**
+   * Number of registered options.
+   * @returns {number} Count.
+   */
+  get count() {
+    return this.#entries.length;
+  }
+
+  /**
+   * The option that is currently marked as selected, if any.
+   * @returns {OptionEntry | undefined} Matching option.
+   */
+  get selectedEntry() {
+    return this.#entries.find((entry) => entry.selected);
+  }
+
+  /**
+   * Register an option.
+   * @param {OptionEntry} entry Live view of the option’s props.
+   * @returns {() => void} Function to unregister the option.
+   */
+  register(entry) {
+    this.#entries = [...this.#entries, entry];
+
+    return () => {
+      this.#entries = this.#entries.filter((item) => item !== entry);
+    };
+  }
+
+  /**
+   * Find the option with the given value.
+   * @param {any} value Value to look for.
+   * @returns {OptionEntry | undefined} Matching option.
+   */
+  find(value) {
+    return this.#entries.find((entry) => entry.value === value);
+  }
+
+  /**
+   * Mark the option with the given value as the only selected one.
+   * @param {any} value Value to select.
+   */
+  selectOnly(value) {
+    this.#entries.forEach((entry) => {
+      const selected = entry.value === value;
+
+      if (entry.selected !== selected) {
+        entry.selected = selected;
+      }
+    });
+  }
+}
+
+/**
+ * Create an option registry and provide it to the descendant `<Option>`s.
+ * @returns {OptionRegistry} New registry.
+ */
+export const createOptionRegistry = () => setContext(CONTEXT_KEY, new OptionRegistry());
+
 /**
- * @import { SelectedItemDetail } from '../typedefs';
+ * Get the option registry provided by an ancestor `<Combobox>`.
+ * @returns {OptionRegistry | undefined} Registry, or `undefined` when the `<Option>` is used
+ * standalone within a `<Listbox>`.
  */
+export const getOptionRegistry = () => getContext(CONTEXT_KEY);
 
 /**
  * Get the detail of the selected element.

package/dist/typedefs.d.ts

@@ -148,8 +148,9 @@ export type ModalProps = {
      */
     escapeDismiss?: boolean | undefined;
     /**
-     * Whether to keep the content in the DOM tree when the modal is
-     * not displayed.
+     * Whether to keep the `<dialog>` element and its content in the
+     * DOM tree while the modal is not displayed. By default, these are mounted only while the modal is
+     * open, and unmounted once the closing transition is complete.
      */
     keepContent?: boolean | undefined;
     /**
@@ -351,6 +352,36 @@ export type MenuItemProps = {
      */
     onSelect?: ((event: CustomEvent) => void) | undefined;
 };
+/**
+ * A live view of an `<Option>`’s props, registered with the ancestor `<Combobox>` so that it can
+ * resolve labels and the initial value while the options are not rendered.
+ */
+export type OptionEntry = {
+    /**
+     * The option’s value.
+     */
+    value: any;
+    /**
+     * The option’s text label.
+     */
+    label: string;
+    /**
+     * The option’s name.
+     */
+    name?: string | undefined;
+    /**
+     * Data type of the `value`.
+     */
+    type: string;
+    /**
+     * Whether the option is selected. Writable.
+     */
+    selected: boolean;
+    /**
+     * Whether the option is disabled.
+     */
+    disabled: boolean;
+};
 export type ComboboxProps = {
     /**
      * The `class` attribute on the wrapper element.
@@ -683,6 +714,11 @@ export type TextEditorComponent = {
      * Material Symbols icon name.
      */
     icon?: string | undefined;
+    /**
+     * Trigger UI of the component. Default: `menuitem`. A
+     * menu item is placed under the Insert menu, while a button is placed directly on the toolbar.
+     */
+    trigger?: "button" | "menuitem" | undefined;
     /**
      * Lexical node class implementation.
      */

package/dist/typedefs.js

@@ -54,8 +54,9 @@
  * @property {boolean} [lightDismiss] Whether to close the modal when the backdrop (outside of the
  * modal) is clicked.
  * @property {boolean} [escapeDismiss] Whether to close the modal when the Escape key is pressed.
- * @property {boolean} [keepContent] Whether to keep the content in the DOM tree when the modal is
- * not displayed.
+ * @property {boolean} [keepContent] Whether to keep the `<dialog>` element and its content in the
+ * DOM tree while the modal is not displayed. By default, these are mounted only while the modal is
+ * open, and unmounted once the closing transition is complete.
  * @property {HTMLDialogElement} [dialog] A reference to the `<dialog>` element.
  * @property {Snippet} [children] Primary slot content.
  * @property {Snippet} [extraContent] Extra slot content.
@@ -122,6 +123,18 @@
  * @property {(event: CustomEvent) => void} [onSelect] Custom `Select` event handler.
  */
 
+/**
+ * A live view of an `<Option>`’s props, registered with the ancestor `<Combobox>` so that it can
+ * resolve labels and the initial value while the options are not rendered.
+ * @typedef {object} OptionEntry
+ * @property {any} value The option’s value.
+ * @property {string} label The option’s text label.
+ * @property {string} [name] The option’s name.
+ * @property {string} type Data type of the `value`.
+ * @property {boolean} selected Whether the option is selected. Writable.
+ * @property {boolean} disabled Whether the option is disabled.
+ */
+
 /**
  * @typedef {object} ComboboxProps
  * @property {string} [class] The `class` attribute on the wrapper element.
@@ -284,6 +297,8 @@
  * @property {string} id Component ID.
  * @property {string} label Component label.
  * @property {string} [icon] Material Symbols icon name.
+ * @property {'menuitem' | 'button'} [trigger] Trigger UI of the component. Default: `menuitem`. A
+ * menu item is placed under the Insert menu, while a button is placed directly on the toolbar.
  * @property {LexicalNode} node Lexical node class implementation.
  * @property {(props?: Record<string, any>) => LexicalNode} createNode Function to create a new node
  * instance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltia/ui",
-  "version": "0.55.1",
+  "version": "0.57.0",
   "description": "A collection of Svelte components and utilities for building user interfaces.",
   "repository": {
     "type": "git",
@@ -56,20 +56,20 @@
     "@sveltejs/adapter-auto": "^7.0.1",
     "@sveltejs/kit": "^2.70.2",
     "@sveltejs/package": "^2.5.8",
-    "@sveltejs/vite-plugin-svelte": "^7.2.0",
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@vitest/coverage-v8": "^4.1.10",
     "cspell": "^10.0.1",
     "eslint": "^9.39.5",
     "eslint-config-airbnb-extended": "^3.2.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsdoc": "^63.3.3",
+    "eslint-plugin-jsdoc": "^64.0.1",
     "eslint-plugin-package-json": "^1.6.3",
     "eslint-plugin-svelte": "^3.22.0",
     "globals": "^17.9.0",
-    "happy-dom": "^20.11.1",
+    "happy-dom": "^20.11.2",
     "oxlint": "^1.77.0",
-    "postcss": "^8.5.25",
+    "postcss": "^8.5.26",
     "postcss-html": "^2.0.0",
     "prettier": "^3.9.6",
     "prettier-plugin-svelte": "^4.1.1",
@@ -78,10 +78,10 @@
     "stylelint-config-recommended-scss": "^17.0.1",
     "stylelint-scss": "^7.2.0",
     "svelte": "^5.56.8",
-    "svelte-check": "^4.7.4",
+    "svelte-check": "^4.7.5",
     "svelte-preprocess": "^6.0.5",
     "tslib": "^2.8.1",
-    "vite": "^8.2.0",
+    "vite": "^8.2.1",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {