@sveltia/ui 0.78.4 → 0.79.0

package/dist/services/navigation.d.ts

@@ -0,0 +1,19 @@
+export function getArrowKeys(orientation: string, rtl: boolean): {
+    prevKey: string;
+    nextKey: string;
+};
+export function getLinearTargetIndex({ key, index, count, prevKey, nextKey }: {
+    key: string;
+    index: number;
+    count: number;
+    prevKey: string;
+    nextKey: string;
+}): number;
+export function getGridTargetIndex({ key, index, count, columnCount, prevKey, nextKey }: {
+    key: string;
+    index: number;
+    count: number;
+    columnCount: number;
+    prevKey: string;
+    nextKey: string;
+}): number;

package/dist/services/navigation.js

@@ -0,0 +1,84 @@
+/**
+ * Arrow key navigation shared by the composite widgets. These functions only map a key and the
+ * current position to a new position; finding the members and moving focus is up to the caller.
+ */
+
+/**
+ * Get the arrow keys that move to the previous and next member along the given orientation. In a
+ * right-to-left layout, the inline arrows are mirrored: ArrowLeft moves forward, ArrowRight back.
+ * @param {string} orientation `horizontal` or `vertical`.
+ * @param {boolean} rtl Whether the layout runs right to left.
+ * @returns {{ prevKey: string, nextKey: string }} Keys.
+ */
+export const getArrowKeys = (orientation, rtl) => {
+  if (orientation === 'horizontal') {
+    return rtl
+      ? { prevKey: 'ArrowRight', nextKey: 'ArrowLeft' }
+      : { prevKey: 'ArrowLeft', nextKey: 'ArrowRight' };
+  }
+
+  return { prevKey: 'ArrowUp', nextKey: 'ArrowDown' };
+};
+
+/**
+ * Get the index to move to in a list when an arrow key is pressed. The movement wraps around at
+ * either end, and with nothing current yet, the previous key starts from the last member and the
+ * next key from the first one.
+ * @param {object} args Arguments.
+ * @param {string} args.key Pressed key.
+ * @param {number} args.index Index of the current member, or `-1` if there’s none.
+ * @param {number} args.count Number of members.
+ * @param {string} args.prevKey Key that moves to the previous member.
+ * @param {string} args.nextKey Key that moves to the next member.
+ * @returns {number} Index of the member to move to, or `-1` if the key doesn’t move.
+ */
+export const getLinearTargetIndex = ({ key, index, count, prevKey, nextKey }) => {
+  if (key === prevKey) {
+    return index > 0 ? index - 1 : count - 1;
+  }
+
+  if (key === nextKey) {
+    return index < count - 1 ? index + 1 : 0;
+  }
+
+  return -1;
+};
+
+/**
+ * Get the index to move to in a grid layout when an arrow key is pressed. The vertical arrows move
+ * by a visual row and the inline arrows by a single member, and none of them wraps around. With
+ * nothing current yet, the arrows start from either end, as in a list.
+ * @param {object} args Arguments.
+ * @param {string} args.key Pressed key.
+ * @param {number} args.index Index of the current member, or `-1` if there’s none.
+ * @param {number} args.count Number of members.
+ * @param {number} args.columnCount Number of members per visual row.
+ * @param {string} args.prevKey Inline key that moves to the previous member.
+ * @param {string} args.nextKey Inline key that moves to the next member.
+ * @returns {number} Index of the member to move to, or `-1` if the key doesn’t move.
+ */
+export const getGridTargetIndex = ({ key, index, count, columnCount, prevKey, nextKey }) => {
+  const lastIndex = count - 1;
+  const backward = key === 'ArrowUp' || key === prevKey;
+  const forward = key === 'ArrowDown' || key === nextKey;
+
+  if (index === -1) {
+    if (forward) {
+      return 0;
+    }
+
+    return backward ? lastIndex : -1;
+  }
+
+  if (backward && index > 0) {
+    // Up by a row, stopping at the first member
+    return key === 'ArrowUp' ? Math.max(index - columnCount, 0) : index - 1;
+  }
+
+  if (forward && index < lastIndex) {
+    // Down by a row; a partial last row still gets reached
+    return key === 'ArrowDown' ? Math.min(index + columnCount, lastIndex) : index + 1;
+  }
+
+  return -1;
+};

package/dist/services/popup-position.d.ts

@@ -0,0 +1,90 @@
+export function mirrorPosition(position: PopupPosition): PopupPosition;
+export function clipRect(anchorRect: {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+}, viewport: ViewportSize): ClippedRect;
+export function flip({ position, from, to, size, room, otherRoom }: {
+    position: PopupPosition;
+    from: string;
+    to: string;
+    size: number;
+    room: number;
+    otherRoom: number;
+}): {
+    position: PopupPosition;
+    cap: number | undefined;
+};
+export function calculatePopupStyle({ position: preferredPosition, anchorRect, viewport, contentWidth, contentHeight, }: {
+    position: PopupPosition;
+    anchorRect: {
+        top: number;
+        left: number;
+        right: number;
+        bottom: number;
+    };
+    viewport: ViewportSize;
+    contentWidth: number;
+    contentHeight: number;
+}): PopupStyle;
+export function isShallowEqual(a: Record<string, any>, b: Record<string, any>): boolean;
+export type PopupStyle = {
+    /**
+     * The `inset` CSS property.
+     */
+    inset: string | undefined;
+    /**
+     * The `z-index` CSS property.
+     */
+    zIndex: number | undefined;
+    /**
+     * The `min-width` CSS property.
+     */
+    minWidth: string | undefined;
+    /**
+     * The `max-width` CSS property.
+     */
+    maxWidth: string | undefined;
+    /**
+     * The `max-height` CSS property.
+     */
+    height: string | undefined;
+};
+export type ViewportSize = {
+    /**
+     * Viewport width.
+     */
+    width: number;
+    /**
+     * Viewport height.
+     */
+    height: number;
+};
+export type ClippedRect = {
+    /**
+     * Top edge.
+     */
+    top: number;
+    /**
+     * Left edge.
+     */
+    left: number;
+    /**
+     * Right edge.
+     */
+    right: number;
+    /**
+     * Bottom edge.
+     */
+    bottom: number;
+    /**
+     * Width.
+     */
+    width: number;
+    /**
+     * Height.
+     */
+    height: number;
+};
+import type { PopupPosition } from '../typedefs.js';

package/dist/services/popup-position.js

@@ -0,0 +1,275 @@
+/**
+ * Pure helpers that work out where a popup goes and how large it can be, given the anchor’s rect
+ * and the viewport size. They don’t touch the DOM, so they can be tested on their own.
+ */
+
+/**
+ * @import { PopupPosition } from '../typedefs.js';
+ */
+
+/**
+ * @typedef {object} PopupStyle
+ * @property {string | undefined} inset The `inset` CSS property.
+ * @property {number | undefined} zIndex The `z-index` CSS property.
+ * @property {string | undefined} minWidth The `min-width` CSS property.
+ * @property {string | undefined} maxWidth The `max-width` CSS property.
+ * @property {string | undefined} height The `max-height` CSS property.
+ */
+
+/**
+ * @typedef {object} ViewportSize
+ * @property {number} width Viewport width.
+ * @property {number} height Viewport height.
+ */
+
+/**
+ * @typedef {object} ClippedRect
+ * @property {number} top Top edge.
+ * @property {number} left Left edge.
+ * @property {number} right Right edge.
+ * @property {number} bottom Bottom edge.
+ * @property {number} width Width.
+ * @property {number} height Height.
+ */
+
+/**
+ * Mirror a popup position for an RTL document, so `-left` becomes `-right`, `left-` becomes
+ * `right-` and vice versa. The positions are written for LTR documents.
+ * @internal
+ * @param {PopupPosition} position Original position.
+ * @returns {PopupPosition} Mirrored position.
+ * @todo Rename `PopupPosition` enums to be direction-agnostic.
+ */
+export const mirrorPosition = (position) => {
+  let mirrored = position;
+
+  if (mirrored.endsWith('-left')) {
+    mirrored = /** @type {PopupPosition} */ (mirrored.replace('-left', '-right'));
+  } else if (mirrored.endsWith('-right')) {
+    mirrored = /** @type {PopupPosition} */ (mirrored.replace('-right', '-left'));
+  }
+
+  if (mirrored.startsWith('left-')) {
+    mirrored = /** @type {PopupPosition} */ (mirrored.replace('left-', 'right-'));
+  } else if (mirrored.startsWith('right-')) {
+    mirrored = /** @type {PopupPosition} */ (mirrored.replace('right-', 'left-'));
+  }
+
+  return mirrored;
+};
+
+/**
+ * Clip the anchor’s rect to the viewport, mirroring what `IntersectionObserver` used to report as
+ * `intersectionRect`.
+ * @internal
+ * @param {{ top: number, left: number, right: number, bottom: number }} anchorRect Anchor’s
+ * bounding rect.
+ * @param {ViewportSize} viewport Viewport size.
+ * @returns {ClippedRect} Clipped rect.
+ */
+export const clipRect = (anchorRect, viewport) => {
+  const top = Math.max(anchorRect.top, 0);
+  const left = Math.max(anchorRect.left, 0);
+  const right = Math.min(anchorRect.right, viewport.width);
+  const bottom = Math.min(anchorRect.bottom, viewport.height);
+
+  return {
+    top,
+    left,
+    right,
+    bottom,
+    width: Math.max(0, right - left),
+    height: Math.max(0, bottom - top),
+  };
+};
+
+/**
+ * Move a popup to the opposite side of its anchor when the content doesn’t fit on the current side
+ * and the opposite side has more room. When the content doesn’t fit, the popup is also capped by
+ * the room on the side it ends up on, so it scrolls instead of running past the viewport.
+ * @internal
+ * @param {object} args Arguments.
+ * @param {PopupPosition} args.position Current position.
+ * @param {string} args.from Part of the position denoting the current side, e.g. `bottom-`.
+ * @param {string} args.to Part of the position denoting the opposite side, e.g. `top-`.
+ * @param {number} args.size Content size along the axis.
+ * @param {number} args.room Room on the current side.
+ * @param {number} args.otherRoom Room on the opposite side.
+ * @returns {{ position: PopupPosition, cap: number | undefined }} New position, and the size limit
+ * if the content doesn’t fit, `undefined` otherwise.
+ */
+export const flip = ({ position, from, to, size, room, otherRoom }) => {
+  if (size <= room) {
+    return { position, cap: undefined };
+  }
+
+  if (otherRoom > room) {
+    return { position: /** @type {PopupPosition} */ (position.replace(from, to)), cap: otherRoom };
+  }
+
+  return { position, cap: room };
+};
+
+/**
+ * Calculate the popup’s inset and size from the anchor’s rect, the viewport size and the content’s
+ * natural size. The position may be altered if the space is limited.
+ * @internal
+ * @param {object} args Arguments.
+ * @param {PopupPosition} args.position Preferred position, already mirrored for RTL if needed.
+ * @param {{ top: number, left: number, right: number, bottom: number }} args.anchorRect Anchor’s
+ * bounding rect.
+ * @param {ViewportSize} args.viewport Viewport size.
+ * @param {number} args.contentWidth Content’s natural width.
+ * @param {number} args.contentHeight Content’s natural height.
+ * @returns {PopupStyle} Popup style.
+ */
+export const calculatePopupStyle = ({
+  position: preferredPosition,
+  anchorRect,
+  viewport,
+  contentWidth,
+  contentHeight,
+}) => {
+  const rect = clipRect(anchorRect, viewport);
+  const topMargin = rect.top - 8;
+  const bottomMargin = viewport.height - rect.bottom - 8;
+  // A popup that opens beside its anchor is aligned with one of the anchor’s edges and extends
+  // across it, so its room is measured from that edge, not from the opposite one a dropdown
+  // hangs off
+  const leftMargin = rect.left - 8;
+  const rightMargin = viewport.width - rect.right - 8;
+  const downwardMargin = viewport.height - rect.top - 8;
+  const upwardMargin = rect.bottom - 8;
+  let position = preferredPosition;
+  /** @type {number | undefined} */
+  let height;
+
+  /**
+   * Apply {@link flip} vertically, keeping any height limit already set if the content fits.
+   * @param {string} from Current side.
+   * @param {string} to Opposite side.
+   * @param {number} room Room on the current side.
+   * @param {number} otherRoom Room on the opposite side.
+   */
+  const flipVertically = (from, to, room, otherRoom) => {
+    const result = flip({ position, from, to, size: contentHeight, room, otherRoom });
+
+    position = result.position;
+    height = result.cap ?? height;
+  };
+
+  // Alter the position if the space is limited
+  if (position.startsWith('bottom-')) {
+    flipVertically('bottom-', 'top-', bottomMargin, topMargin);
+  } else if (position.startsWith('top-')) {
+    flipVertically('top-', 'bottom-', topMargin, bottomMargin);
+  }
+
+  // Only a popup that opens beside its anchor carries a `-top`/`-bottom` suffix, and it grows
+  // away from the edge it’s aligned with: down from the anchor’s top, or up from its bottom. It
+  // gets the same treatment as the dropdown above — align with the other edge when the content
+  // doesn’t fit and that edge has more room, and cap it either way, so a long submenu scrolls
+  // instead of running past the viewport
+  if (position.endsWith('-top')) {
+    flipVertically('-top', '-bottom', downwardMargin, upwardMargin);
+  } else if (position.endsWith('-bottom')) {
+    flipVertically('-bottom', '-top', upwardMargin, downwardMargin);
+  }
+
+  // If the popup overflows the viewport, change the position
+  if (position.endsWith('-left')) {
+    if (rect.left + contentWidth > viewport.width - 8) {
+      position = /** @type {PopupPosition} */ (position.replace('-left', '-right'));
+    }
+  }
+
+  if (position.endsWith('-right')) {
+    if (rect.right - contentWidth < 8) {
+      position = /** @type {PopupPosition} */ (position.replace('-right', '-left'));
+    }
+  }
+
+  // The two checks above align a dropdown that opens below or above its anchor, so neither
+  // covers a popup that opens beside one — a submenu — running off the edge it opens towards.
+  // That gets the same treatment as the vertical flip above: switch to the other side, but only
+  // when it has more room, so a submenu with nowhere to go stays where the caller put it. The
+  // width isn’t capped here; that’s done with `maxWidth` below.
+  if (position.startsWith('right-')) {
+    ({ position } = flip({
+      position,
+      from: 'right-',
+      to: 'left-',
+      size: contentWidth,
+      room: rightMargin,
+      otherRoom: leftMargin,
+    }));
+  } else if (position.startsWith('left-')) {
+    ({ position } = flip({
+      position,
+      from: 'left-',
+      to: 'right-',
+      size: contentWidth,
+      room: leftMargin,
+      otherRoom: rightMargin,
+    }));
+  }
+
+  const top = position.startsWith('bottom-')
+    ? `${Math.round(rect.bottom)}px`
+    : position.endsWith('-top')
+      ? `${Math.round(rect.top)}px`
+      : 'auto';
+
+  const right = position.startsWith('left-')
+    ? `${Math.round(viewport.width - rect.left)}px`
+    : position.endsWith('-right')
+      ? `${Math.round(viewport.width - rect.right)}px`
+      : 'auto';
+
+  const bottom = position.startsWith('top-')
+    ? `${Math.round(viewport.height - rect.top)}px`
+    : position.endsWith('-bottom')
+      ? `${Math.round(viewport.height - rect.bottom)}px`
+      : 'auto';
+
+  const left = position.startsWith('right-')
+    ? `${Math.round(rect.right)}px`
+    : position.endsWith('-left')
+      ? `${Math.round(rect.left)}px`
+      : 'auto';
+
+  return {
+    inset: [top, right, bottom, left].join(' '),
+    zIndex: 1000,
+    minWidth: `${Math.round(rect.width)}px`,
+    // A popup opening beside the anchor is capped by the room on that side, not by the width the
+    // anchor’s own edges leave, which is what the two dropdown cases below measure
+    maxWidth: position.startsWith('right-')
+      ? `${Math.round(rightMargin)}px`
+      : position.startsWith('left-')
+        ? `${Math.round(leftMargin)}px`
+        : position.endsWith('-left')
+          ? `${Math.round(viewport.width - rect.left - 8)}px`
+          : `${Math.round(rect.right - 8)}px`,
+    // `undefined` removes the `max-height` the popup is given, letting it take its natural size
+    // again. `auto` would look equivalent but isn’t a valid `max-height`, so the browser would
+    // drop it and leave whatever limit was applied last in place.
+    height: height ? `${Math.round(height)}px` : undefined,
+  };
+};
+
+/**
+ * Check if two objects have the same keys with strictly equal values.
+ * @internal
+ * @param {Record<string, any>} a One object.
+ * @param {Record<string, any>} b Another object.
+ * @returns {boolean} Whether the objects are shallowly equal.
+ */
+export const isShallowEqual = (a, b) => {
+  const keys = Object.keys(a);
+
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) => Object.hasOwn(b, key) && a[key] === b[key])
+  );
+};

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

@@ -1,6 +1,8 @@
-export function activatePopup(...args: any[]): Popup;
+export function activatePopup(anchorElement: HTMLElement, popupElement: HTMLDialogElement | undefined, position: PopupPosition, positionBaseElement?: HTMLElement | undefined): Popup;
+import type { PopupPosition } from '../typedefs.js';
 /**
- * @import { PopupPosition } from '../typedefs';
+ * @import { PopupPosition } from '../typedefs.js';
+ * @import { PopupStyle } from './popup-position.js';
  */
 /**
  * Implement the popup handler.
@@ -10,14 +12,14 @@ declare class Popup {
      * 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 {HTMLElement} anchorElement Element that triggers the popup, typically a `<button>`.
      * @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: HTMLButtonElement, popupElement: HTMLDialogElement | undefined, position: PopupPosition, positionBaseElement?: HTMLElement);
+    constructor(anchorElement: HTMLElement, popupElement: HTMLDialogElement | undefined, position: PopupPosition, positionBaseElement?: HTMLElement);
     /**
      * Open or close the popup, running side effects synchronously.
      * @param {boolean} value `true` to open, `false` to close.
@@ -28,13 +30,7 @@ declare class Popup {
      * @returns {boolean} `true` if the popup is open.
      */
     get open(): boolean;
-    style: {
-        inset: string | undefined;
-        zIndex: number | undefined;
-        minWidth: string | undefined;
-        maxWidth: string | undefined;
-        height: string | undefined;
-    };
+    style: PopupStyle;
     /**
      * 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
@@ -49,13 +45,17 @@ declare class Popup {
      * @type {HTMLElement | undefined}
      */
     contentElement: HTMLElement | undefined;
-    anchorElement: HTMLButtonElement;
+    /**
+     * ID of the animation frame requested to recalculate the position after a resize.
+     * @type {number}
+     */
+    _rafId: number;
+    anchorElement: HTMLElement;
     position: PopupPosition;
     positionBaseElement: HTMLElement;
     id: string;
     intersectionObserver: IntersectionObserver;
     resizeObserver: ResizeObserver;
-    _rafId: number;
     viewportResizeObserver: ResizeObserver;
     /**
      * Attach the `<dialog>` element used for the popup. This is called every time the element is
@@ -67,9 +67,8 @@ declare class Popup {
      */
     attachPopupElement(popupElement: HTMLDialogElement, contentElement?: HTMLElement): void;
     /**
-     * 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.
+     * Detach the `<dialog>` element, typically because it’s being unmounted. The anchor’s
+     * `aria-controls` attribute is removed as well, since the content is leaving the DOM tree.
      */
     detachPopupElement(): void;
     /**
@@ -103,5 +102,5 @@ declare class Popup {
     destroy(): void;
     #private;
 }
-import type { PopupPosition } from '../typedefs';
+import type { PopupStyle } from './popup-position.js';
 export {};