entasis 0.11.0 → 0.12.0

package/dist/components/Dialog/dialog.snap.js

@@ -0,0 +1,78 @@
+const LENGTH = /^\s*(\d*\.?\d+)\s*(px|rem|em|%|vh|dvh|svh|lvh)?\s*$/i;
+/** Release speed in px/ms from which a drag is a flick, the same rule as dismissing a drawer. */
+export const FLICK_SPEED = 0.4;
+/**
+ * The visible height of a snap point in px, `NaN` when it is not valid. A number is a fraction of
+ * the available height (above 0, at most 1); a string is a CSS length: `px`, `rem`, `em`, `%` (of
+ * the available height) or `vh`.
+ */
+export function snapPointHeight(point, context) {
+    if (typeof point === 'number') {
+        return point > 0 && point <= 1 ? point * context.available : Number.NaN;
+    }
+    const match = LENGTH.exec(point);
+    if (!match)
+        return Number.NaN;
+    const value = parseFloat(match[1]);
+    const unit = (match[2] ?? 'px').toLowerCase();
+    if (unit === 'px')
+        return value;
+    if (unit === 'rem' || unit === 'em')
+        return value * context.rem;
+    if (unit === '%')
+        return (value / 100) * context.available;
+    return (value / 100) * context.viewport;
+}
+/**
+ * The snap points as px heights, from the lowest to the highest. Invalid points are dropped, a
+ * point taller than the available room is clamped to it, and points that land on the same pixel
+ * keep the first one written.
+ */
+export function resolveSnapPoints(points, context) {
+    if (!points?.length || !(context.available > 0))
+        return [];
+    const resolved = [];
+    for (const point of points) {
+        const height = Math.min(snapPointHeight(point, context), context.available);
+        if (!Number.isFinite(height) || height <= 0)
+            continue;
+        if (resolved.some((other) => Math.abs(other.height - height) < 0.5))
+            continue;
+        resolved.push({ point, height });
+    }
+    return resolved.sort((a, b) => a.height - b.height);
+}
+/**
+ * Where a released drag rests. `height` is how much of the drawer shows when the pointer lifts and
+ * `velocity` its speed toward dismissal in px/ms (positive shrinks the drawer). A flick (at least
+ * `FLICK_SPEED`) carries the drawer to the next point in the direction it was thrown, past the
+ * lowest one to closed; a slower release rests at the nearest point, closed counting as a point
+ * with a height of 0. Without `allowClose`, closed is never the answer. Returns the index into
+ * `heights` (ascending), or `-1` to close. A tie keeps the drawer open and as large as possible.
+ */
+export function settleSnapIndex(heights, height, velocity, allowClose) {
+    if (Math.abs(velocity) >= FLICK_SPEED) {
+        if (velocity > 0) {
+            for (let index = heights.length - 1; index >= 0; index -= 1) {
+                if (heights[index] < height - 0.5)
+                    return index;
+            }
+            return allowClose ? -1 : 0;
+        }
+        for (let index = 0; index < heights.length; index += 1) {
+            if (heights[index] > height + 0.5)
+                return index;
+        }
+        return heights.length - 1;
+    }
+    let best = -1;
+    let bestDistance = allowClose ? Math.abs(height) : Number.POSITIVE_INFINITY;
+    for (let index = 0; index < heights.length; index += 1) {
+        const distance = Math.abs(height - heights[index]);
+        if (distance <= bestDistance) {
+            best = index;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}

package/dist/components/Dialog/dialog.state.svelte.d.ts

@@ -1,23 +1,64 @@
-import type { DialogProps } from './dialog.props.js';
+import type { DialogProps, DialogSnapPoint } from './dialog.props.js';
+import { type OpenChangeDetails, type OpenChangeHandler, type OpenChangeInit } from '../../utils/openChange.js';
+import { type PopupTriggerProps } from '../../utils/trigger.js';
 import { type DialogThemeProps } from './dialog.theme.js';
+import type { DialogApi } from './dialog.api.js';
 export { DIALOG_Z_BASE, DIALOG_Z_STEP } from '../Theme/theme.layers.js';
 type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-interface DialogOptions extends MakeRequired<Pick<DialogProps, 'id' | 'type' | 'size' | 'scroll' | 'transition' | 'closeOnEscape' | 'closeOnClickOutside' | 'closable' | 'swipeToDismiss' | 'swipeFrom' | 'responsive'>, 'closeOnEscape' | 'closeOnClickOutside' | 'closable'> {
+interface DialogOptions extends MakeRequired<Pick<DialogProps, 'id' | 'type' | 'size' | 'scroll' | 'transition' | 'closeOnEscape' | 'closeOnClickOutside' | 'closable' | 'swipeToDismiss' | 'swipeFrom' | 'responsive' | 'focusOnClose' | 'modal' | 'snapPoints' | 'defaultSnapPoint' | 'onSnapPointChange'>, 'id' | 'closeOnEscape' | 'closable' | 'modal'> {
     isOpen: boolean;
-    onOpenChange?: (open: boolean) => void;
+    /** The resting snap point; `undefined` until one is chosen (the default point applies). */
+    snapPoint?: DialogSnapPoint;
+    onOpenChange?: OpenChangeHandler;
+    onAfterOpen?: (payload: DialogApi) => void;
+    onAfterClose?: (payload: DialogApi) => void;
     /** The instance `theme.motion` slot; the `transition` prop still wins over it. */
     motion?: DialogThemeProps['motion'];
 }
+/** What `open`, `close`, `toggle` and `setOpen` accept: details, a partial, or the DOM event. */
+export type DialogOpenChangeInput = OpenChangeDetails | OpenChangeInit | Event;
 declare const DialogState_base: new (props: DialogOptions) => {} & DialogOptions;
-export declare class DialogState extends DialogState_base {
+export declare class DialogState extends DialogState_base implements DialogApi {
     #private;
     parent: DialogState | null;
     get children(): readonly DialogState[];
-    hasTransitioned: boolean;
     theme: import("../Theme/theme.state.svelte.js").ThemeState;
+    /** Whether the dialog is rendered: open, and mounted. */
+    isRendered: boolean;
+    lifecycle: import("../../utils/openLifecycle.svelte.js").OpenLifecycle;
+    /** Where the dialog is in its open/close lifecycle; see `DialogApi.status`. */
+    get status(): import("../../utils/stateAttributes.js").OpenTransitionStatus;
+    /** @deprecated Read `status === 'open'`; kept for one minor. */
+    get hasTransitioned(): boolean;
+    /**
+     * `data-open` / `data-closed` and `data-entering` / `data-exiting` for the root and the panel
+     * (see `dialogDataAttributes`). Closed, they render only while the exit transition plays.
+     */
+    stateAttributes: {
+        'data-entering': import("../../utils/stateAttributes.js").Presence;
+        'data-exiting': import("../../utils/stateAttributes.js").Presence;
+        'data-open': import("../../utils/stateAttributes.js").Presence;
+        'data-closed': import("../../utils/stateAttributes.js").Presence;
+    };
+    /** The details of the last change that was applied, kept until the next one. */
+    lastOpenChange: OpenChangeDetails | null;
     layer: import("../../utils/layers.svelte.js").LayerHandle;
-    /** How many open dialogs sit above this one. */
+    /**
+     * Trigger state in the library's semantic vocabulary: spread on the built-in Button, and
+     * written as ARIA attributes by `reference` / `trigger` on a snippet trigger.
+     */
+    triggerProps: PopupTriggerProps;
+    /**
+     * How many open modal dialogs sit above this one. A non-modal dialog leaves the page usable, so
+     * it does not push the ones beneath it back.
+     */
     stackDepth: number;
+    /** The dialog directly above this one, whose swipe this one follows. */
+    childAbove: DialogState | undefined;
+    /** Whether the dialog above is being dragged, so this one tracks it without easing. */
+    followsChild: boolean;
+    /** The stack depth as the dialog above is dismissed: it shrinks toward the next level as it is dragged away. */
+    effectiveDepth: number;
     /** Topmost dialog (popovers opened above it do not count). */
     isTop: boolean;
     zIndex: number;
@@ -26,6 +67,15 @@ export declare class DialogState extends DialogState_base {
     computedSize: import("../../types/theme.js").Sizes;
     computedType: import("./dialog.props.js").DialogType;
     computedScroll: "inner" | "outer";
+    /** Whether the resolved type is `alert`: an interruption that needs an explicit answer. */
+    isAlert: boolean;
+    /** `alertdialog` for an alert, so assistive technology announces it as one. */
+    role: 'dialog' | 'alertdialog';
+    /**
+     * `closeOnClickOutside` when set; otherwise an outside press dismisses a modal that is not an
+     * alert. A non-modal dialog stays open while the page is used.
+     */
+    computedCloseOnClickOutside: boolean;
     private resolveMotion;
     computedTransition: import("../../utils/motion/index.js").ResolvedMotion;
     isDrawer: boolean;
@@ -33,21 +83,83 @@ export declare class DialogState extends DialogState_base {
     swipeAxis: 'x' | 'y';
     swipeSign: number;
     dragging: boolean;
+    /**
+     * Where the panel sits along the dismiss axis, in px (0 = fully open). Follows the finger while
+     * dragging and otherwise rests at 0, or at the active snap point's offset.
+     */
     dragOffset: number;
     dragSize: number;
+    /** Drag progress toward dismissal, 0 while resting at the open position or any snap point. */
     dragProgress: number;
     contentTransform: string | undefined;
+    /** Whether the drawer rests at snap points: a bottom or top drawer with `snapPoints`. */
+    snapEnabled: boolean;
+    /** Room in px the drawer may use, measured from the positioner; 0 until it is laid out. */
+    availableSize: number;
+    /** The snap points as px heights, lowest first. */
+    snapHeights: import("./dialog.snap.js").ResolvedSnapPoint[];
+    /** The point the drawer rests at: `snapPoint`, else `defaultSnapPoint`, else the largest. */
+    activeSnap: import("./dialog.snap.js").ResolvedSnapPoint | undefined;
+    /** The value of `snapPoint` right now, as the consumer wrote it. */
+    currentSnapPoint: DialogSnapPoint | undefined;
+    /** Whether the drawer rests at its largest point, the only one where its body scrolls. */
+    atLargestSnap: boolean;
+    /** The panel's height in px: the largest snap point. */
+    snapPanelHeight: number | undefined;
+    /** The panel offset in px (signed along the dismiss axis) at the active point. */
+    restOffset: number;
+    /** Offset in px at the lowest point: dragging beyond it moves toward dismissal. */
+    snapFloor: number;
+    /** Whether the panel can be dragged: to dismiss it, or between snap points. */
+    gestureEnabled: boolean;
+    /** The panel scrolls only while it shows in full. */
+    bodyScrollLocked: boolean;
+    /**
+     * Moves the drawer to a snap point (one of `snapPoints`, or the nearest to it). `onSnapPointChange`
+     * runs first with the change details; cancelling keeps the current point. Returns `false` when
+     * the change did not happen.
+     */
+    setSnapPoint(point: DialogSnapPoint, input?: DialogOpenChangeInput): boolean;
+    /** Whether a text field inside the panel has focus, so the on-screen keyboard may be up. */
+    fieldFocused: boolean;
+    /** A bottom sheet gives room to the keyboard while one of its fields has focus. */
+    keyboardAvoiding: boolean;
     focusScope: {
         attachment: (target: HTMLElement) => () => void;
         restore: () => void;
     };
     addChild: (child: DialogState) => () => () => void;
     constructor(options: DialogOptions);
-    toggle: () => void;
-    open: () => void;
-    close: () => void;
-    private setOpen;
+    toggle: (input?: DialogOpenChangeInput) => void;
+    open: (input?: DialogOpenChangeInput) => void;
+    close: (input?: DialogOpenChangeInput) => void;
+    /**
+     * Requests an open-state change. `onOpenChange(nextOpen, details)` runs first; when it calls
+     * `details.cancel()` nothing changes. Returns `false` when the change was cancelled.
+     */
+    setOpen(nextOpen: boolean, input?: DialogOpenChangeInput): boolean;
+    /**
+     * Attachment for a custom trigger element (`{@attach dialog.reference}`): keeps its
+     * `aria-haspopup`, `aria-expanded` and `aria-controls` in sync and makes it the element focus
+     * returns to, leaving clicks and keys to the element.
+     */
+    reference: (node: HTMLElement) => () => void;
+    /**
+     * Makes any element the dialog's trigger (`{@attach dialog.trigger}`): `reference`, plus a
+     * click that opens the dialog, and on an element that is not already a control
+     * `role="button"`, `tabindex="0"` and Enter/Space activation. The element's own handler runs
+     * first: calling `event.preventDefault()` there, or opening the dialog itself, stops it.
+     */
+    trigger: (node: HTMLElement) => () => void;
     contentAttachment: (node: HTMLElement) => () => void;
     static readonly NO_SWIPE_TAGS: readonly string[];
+    /** Whether text inside `panel` is selected: a drag there is meant to extend the selection. */
+    static hasSelectionIn(panel: HTMLElement): boolean;
+    private keyboardAttachment;
     private swipeAttachment;
 }
+/**
+ * The state behind the `DialogApi` a Dialog hands its snippets and callbacks. For library code
+ * and tests that read a dialog's internals; consumers get the narrow API.
+ */
+export declare const dialogInternals: (dialog: DialogApi) => DialogState;