@zeyos/zx 2.3.0 → 3.0.0

package/dist/types/components/sheet/sheet.d.ts

@@ -0,0 +1,294 @@
+import { Dialog } from '../dialog/dialog.js';
+export type SheetSide = 'start' | 'end' | 'top' | 'bottom';
+export type SheetModality = true | 'trap-focus' | false;
+export type SheetBackdrop = 'dim' | 'blur' | 'none';
+export type SheetOptions = {
+    /**
+     * Edge the sheet is anchored to. Logical, so `start` and `end`
+     * follow the writing direction.
+     */
+    side?: SheetSide;
+    /**
+     * `true` traps focus, locks page scroll, and blocks pointer
+     * interaction behind a backdrop; `'trap-focus'` traps focus only; `false` leaves the page fully
+     * interactive. Only `true` renders a backdrop — that is what makes the other two non-modal.
+     */
+    modal?: SheetModality;
+    /**
+     * Backdrop treatment, applied only when `modal` is
+     * `true`. `'blur'` reads `--zx-overlay-blur`.
+     */
+    backdrop?: SheetBackdrop;
+    /**
+     * Size along the sheet's own axis — width for
+     * `start`/`end`, height for `top`/`bottom`. A number is pixels, a string is any CSS length. Null
+     * keeps the per-side default.
+     */
+    size?: string | number | null;
+    /**
+     * Whether the header shows its close control. Independent of
+     * `closable`, so a sheet can offer Escape without an ✕, or the reverse.
+     */
+    closeButton?: boolean;
+    /**
+     * Whether the inner edge may be dragged to resize the sheet.
+     */
+    resizable?: boolean;
+    /**
+     * Smallest the sheet may be dragged to, in pixels.
+     */
+    min?: number;
+    /**
+     * Largest it may be dragged to; null means the viewport.
+     */
+    max?: number | null;
+    /**
+     * Whether to show a grab handle on the inner edge.
+     * `'auto'` shows one for `top` and `bottom` sheets, which is what makes them read as drawers.
+     */
+    handle?: boolean | 'auto';
+    /**
+     * Detents the sheet settles on. A number at or
+     * below 1 is a fraction of the viewport along the sheet's axis, anything larger is pixels, and a
+     * string is any CSS length `resolveSize` understands (`'320px'`, `'90%'`).
+     */
+    snap?: Array<number | string> | null;
+    /**
+     * Header title.
+     */
+    title?: string;
+    /**
+     * Body content.
+     */
+    content?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Footer buttons.
+     */
+    buttons?: import('../dialog/dialog.js').DialogButton[];
+    /**
+     * Whether Escape may close the sheet.
+     */
+    closable?: boolean;
+    /**
+     * Whether a click outside closes the sheet — the backdrop
+     * when modal, a document-level pointer press when not.
+     */
+    lightDismiss?: boolean;
+    /**
+     * Whether to destroy the sheet after it closes.
+     */
+    destroyOnClose?: boolean;
+    /**
+     * Open event listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close event listener.
+     */
+    onclose?: (event: CustomEvent<{
+        result: unknown;
+    }>) => void;
+    /**
+     * Cancel event listener.
+     */
+    oncancel?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Resize listener.
+     */
+    onresize?: (event: CustomEvent<{
+        size: number;
+        ratio: number;
+    }>) => void;
+    /**
+     * Dock-state listener.
+     */
+    ondockchange?: (event: CustomEvent<{
+        docked: boolean;
+        dock: import('../dock/dock.js').Dock | null;
+    }>) => void;
+};
+/**
+ * @typedef {Object} SheetOptions
+ * @property {SheetSide} [side='end'] Edge the sheet is anchored to. Logical, so `start` and `end`
+ *   follow the writing direction.
+ * @property {SheetModality} [modal=true] `true` traps focus, locks page scroll, and blocks pointer
+ *   interaction behind a backdrop; `'trap-focus'` traps focus only; `false` leaves the page fully
+ *   interactive. Only `true` renders a backdrop — that is what makes the other two non-modal.
+ * @property {SheetBackdrop} [backdrop='dim'] Backdrop treatment, applied only when `modal` is
+ *   `true`. `'blur'` reads `--zx-overlay-blur`.
+ * @property {string|number|null} [size=null] Size along the sheet's own axis — width for
+ *   `start`/`end`, height for `top`/`bottom`. A number is pixels, a string is any CSS length. Null
+ *   keeps the per-side default.
+ * @property {boolean} [closeButton=true] Whether the header shows its close control. Independent of
+ *   `closable`, so a sheet can offer Escape without an ✕, or the reverse.
+ * @property {boolean} [resizable=false] Whether the inner edge may be dragged to resize the sheet.
+ * @property {number} [min=160] Smallest the sheet may be dragged to, in pixels.
+ * @property {number|null} [max=null] Largest it may be dragged to; null means the viewport.
+ * @property {boolean|'auto'} [handle='auto'] Whether to show a grab handle on the inner edge.
+ *   `'auto'` shows one for `top` and `bottom` sheets, which is what makes them read as drawers.
+ * @property {Array<number|string>|null} [snap=null] Detents the sheet settles on. A number at or
+ *   below 1 is a fraction of the viewport along the sheet's axis, anything larger is pixels, and a
+ *   string is any CSS length `resolveSize` understands (`'320px'`, `'90%'`).
+ * @property {string} [title=''] Header title.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
+ * @property {import('../dialog/dialog.js').DialogButton[]} [buttons=[]] Footer buttons.
+ * @property {boolean} [closable=true] Whether Escape may close the sheet.
+ * @property {boolean} [lightDismiss=true] Whether a click outside closes the sheet — the backdrop
+ *   when modal, a document-level pointer press when not.
+ * @property {boolean} [destroyOnClose=false] Whether to destroy the sheet after it closes.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
+ * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
+ * @property {(event: CustomEvent<{size: number, ratio: number}>) => void} [onresize] Resize listener.
+ * @property {(event: CustomEvent<{docked: boolean, dock: import('../dock/dock.js').Dock|null}>) => void} [ondockchange] Dock-state listener.
+ */
+/**
+ * Edge-anchored surface: a Dialog that attaches to one side of the viewport instead of floating in
+ * the middle. One primitive covers both side sheets and mobile drawers; only the edge differs.
+ *
+ * Extends `Dialog` rather than reimplementing it, so the header, footer buttons, switchable views,
+ * and focus restoration all come from the same structured-dialog foundation.
+ *
+ * Modality is a three-way choice rather than a boolean because the three real behaviours do not
+ * collapse into two: a modal sheet delegates focus containment, page inertness, and Escape to the
+ * browser via `showModal()`; the other two open with `show()` and re-implement only what they still
+ * want. That is also why `backdrop` applies only to `modal: true` — `::backdrop` does not render
+ * for a non-modal dialog, and painting a fake one would make a sheet look blocking while it is not.
+ * @fires Sheet#open
+ * @fires Sheet#close
+ * @fires Sheet#cancel
+ * @fires Sheet#resize
+ * @fires Sheet#dockchange
+ */
+export declare class Sheet extends Dialog {
+    #private;
+    _dock: any;
+    _handoff: boolean;
+    static cssName: string;
+    /** @type {Readonly<SheetOptions>} */
+    static defaults: Readonly<SheetOptions>;
+    /**
+     * Creates an edge-anchored sheet.
+     * @param {Element|string|null} [_target=null] Ignored; Sheet always owns its root.
+     * @param {SheetOptions} [options={}] Sheet options.
+     */
+    constructor(_target?: Element | string | null, options?: SheetOptions);
+    /**
+     * Moves to one of the configured detents.
+     * @param {number|string} target Detent index, or one of the `snap` values.
+     * @returns {this}
+     * @fires Sheet#resize
+     */
+    snapTo(target: number | string): this;
+    /**
+     * Returns the sheet's current size along its own axis, in pixels.
+     * @returns {number}
+     */
+    getSize(): number;
+    /**
+     * Resolves a translated string, falling back to English when no translator knows the key.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
+    /**
+     * Where the dialog lives: the owning dock while adopted, the document otherwise.
+     * @returns {Element}
+     */
+    mountTarget(): Element;
+    /**
+     * Reports whether a dock currently owns this sheet's positioning.
+     * @returns {boolean}
+     */
+    isDocked(): boolean;
+    /**
+     * Hands positioning to a dock, or takes it back. Called by `Dock.adopt()` and `Dock.release()`;
+     * applications go through those rather than here.
+     * @param {{el: Element}|null} dock Owning dock, or null to float again.
+     * @returns {void}
+     * @fires Sheet#dockchange
+     */
+    _setDock(dock: {
+        el: Element;
+    } | null): void;
+    /**
+     * Moves the dialog to its current mount and, when it was open, reopens it there.
+     *
+     * The close is unavoidable — a dialog cannot cross between the top layer and the flow while
+     * open — but it is invisible: `_isRealClose()` drops the stale event, and reopening bypasses
+     * `open()` so no lifecycle event is emitted for what is only a change of address.
+     * @returns {void}
+     */
+    _rehost(): void;
+    /**
+     * Drops the stale `close` a re-hosting handoff leaves behind.
+     * @returns {boolean}
+     */
+    _isRealClose(): boolean;
+    /**
+     * Opens the sheet, trapping focus first where the modality asks for it.
+     * @returns {this}
+     * @fires Modal#open
+     */
+    open(): this;
+    /**
+     * Closes the sheet with an optional result.
+     * @param {unknown} [result] Result included in the close event.
+     * @returns {this}
+     */
+    close(result?: unknown): this;
+    /**
+     * Moves the sheet to another edge. Takes effect immediately, open or closed.
+     * @param {SheetSide} side Edge to anchor to.
+     * @returns {this}
+     */
+    setSide(side: SheetSide): this;
+    /**
+     * Returns the edge the sheet is anchored to.
+     * @returns {SheetSide}
+     */
+    getSide(): SheetSide;
+    /**
+     * Resizes the sheet along its own axis.
+     * @param {string|number|null} size CSS length, pixel number, or null for the per-side default.
+     * @returns {this}
+     */
+    setSize(size: string | number | null): this;
+    /**
+     * Reports whether focus containment is active.
+     * @returns {boolean}
+     */
+    isModal(): boolean;
+    /**
+     * Sizes the sheet along whichever axis its side implies, by custom property rather than a fixed
+     * dimension so the per-side CSS default survives a null.
+     *
+     * Runs from `Dialog`'s constructor, before this class's field initializers — DOM only.
+     * @param {string|number|null} size CSS length, pixel number, or null.
+     * @returns {void}
+     */
+    _applySize(size: string | number | null): void;
+    /**
+     * Opens the sheet modally or not, as `modal` asks.
+     * @returns {void}
+     */
+    _show(): void;
+    /**
+     * Releases the focus trap and the owned dialog.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+/**
+ * Sheet resize event.
+ * @event Sheet#resize
+ * @type {CustomEvent<{size: number, ratio: number}>}
+ */
+/**
+ * Sheet dock-state event.
+ * @event Sheet#dockchange
+ * @type {CustomEvent<{docked: boolean, dock: import('../dock/dock.js').Dock|null}>}
+ */

package/dist/types/components/split-view/split-view.d.ts

@@ -1,4 +1,5 @@
 import { Component } from '../../core/component.js';
+export { resolveSize } from '../../core/drag-axis.js';
 export type SplitViewContent = string | Node | Component | null;
 export type SplitViewOptions = {
     /**
@@ -126,6 +127,7 @@ export type SplitViewOptions = {
  */
 export declare class SplitView extends Component<SplitViewOptions> {
     #private;
+    _startSize: number;
     _orientation: string;
     /** Current start size in pixels, or null while the CSS value in the property is in charge. */
     _size: number;
@@ -133,16 +135,6 @@ export declare class SplitView extends Component<SplitViewOptions> {
     _collapsed: 'start' | 'end' | null;
     _disabled: boolean;
     _destroyed: boolean;
-    _dragging: boolean;
-    /** Handle of the frame a pending drag update is scheduled in; `0` if none. */
-    _frame: number;
-    /** @type {number|null} */
-    _pointerId: number | null;
-    _startClient: number;
-    _startSize: number;
-    _pointerClient: number;
-    /** Whether the pointer left its starting position, which separates a drag from a click. */
-    _moved: boolean;
     /** Container size of the last observer pass; `-1` forces the next one to run. */
     _lastTotal: any;
     _createdRoot: boolean;
@@ -312,17 +304,6 @@ export type ClampSizeInput = {
  * @returns {number} A size in pixels, never negative.
  */
 export declare function clampSize({ size, min, max, total, divider }: ClampSizeInput): number;
-/**
- * Resolves a size option to pixels without touching the DOM.
- *
- * Numbers, bare numeric strings, and `px` lengths are pixels; a percentage resolves against
- * `total`. Every other CSS length — `rem`, `vh`, `calc()` — needs the browser, so it returns `NaN`
- * and the caller hands the value to CSS instead of guessing at it.
- * @param {number|string} value Size option.
- * @param {number} total Container size along the split axis, in pixels.
- * @returns {number} Pixels, or `NaN` when only the browser can resolve the value.
- */
-export declare function resolveSize(value: number | string, total: number): number;
 /**
  * Pulls a size onto the nearest target within a radius, leaving it alone when nothing is close.
  * The radius is inclusive, ties go to the target listed first, and a radius of zero or less turns