@zeyos/zx 2.3.0 → 4.0.0

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

@@ -0,0 +1,167 @@
+/** @typedef {import('./sheet.js').Sheet} Sheet */
+export type Sheet = import('./sheet.js').Sheet;
+export type SheetStackOptions = {
+    /**
+     * How depth is expressed. `stack` slides each
+     * covered sheet back toward its edge and scales it down, leaving only the top one usable —
+     * the drill-down feel. `cascade` shifts each covered sheet clear of the ones in front so they
+     * sit side by side and all stay usable, which is what an ERP screen usually wants: the parent
+     * record stays readable while a line item is edited.
+     */
+    layout?: 'stack' | 'cascade';
+    /**
+     * Pixels a `stack` layout moves per depth step.
+     */
+    offset?: number;
+    /**
+     * How much a `stack` layout shrinks per depth step, as a fraction.
+     */
+    scale?: number;
+    /**
+     * Depth at which a sheet stops being drawn. Deeper sheets stay open and
+     * in the stack; they are simply no longer visible behind the ones in front.
+     */
+    max?: number;
+    /**
+     * Push listener.
+     */
+    onpush?: (event: CustomEvent<{
+        sheet: Sheet;
+        depth: number;
+    }>) => void;
+    /**
+     * Pop listener.
+     */
+    onpop?: (event: CustomEvent<{
+        sheet: Sheet;
+    }>) => void;
+};
+/**
+ * @typedef {Object} SheetStackOptions
+ * @property {'stack'|'cascade'} [layout='stack'] How depth is expressed. `stack` slides each
+ *   covered sheet back toward its edge and scales it down, leaving only the top one usable —
+ *   the drill-down feel. `cascade` shifts each covered sheet clear of the ones in front so they
+ *   sit side by side and all stay usable, which is what an ERP screen usually wants: the parent
+ *   record stays readable while a line item is edited.
+ * @property {number} [offset=24] Pixels a `stack` layout moves per depth step.
+ * @property {number} [scale=0.04] How much a `stack` layout shrinks per depth step, as a fraction.
+ * @property {number} [max=3] Depth at which a sheet stops being drawn. Deeper sheets stay open and
+ *   in the stack; they are simply no longer visible behind the ones in front.
+ * @property {(event: CustomEvent<{sheet: Sheet, depth: number}>) => void} [onpush] Push listener.
+ * @property {(event: CustomEvent<{sheet: Sheet}>) => void} [onpop] Pop listener.
+ */
+/**
+ * An ordered group of Sheets that read as one drill-down.
+ *
+ * Deliberately tiny, because the browser already does the hard part: nested dialogs stack in the
+ * top layer by open order, so there is no z-index bookkeeping here, and Escape closes only the
+ * topmost, so unwinding one level at a time is native behaviour rather than something to
+ * implement. What is left is bookkeeping — which sheet is at which depth — written onto the
+ * elements as `data-depth` and `--zx-sheet-depth` for CSS to interpret.
+ *
+ * Owns no element of its own, so it is a controller rather than a `Component`: there is nothing
+ * to render, only sheets to arrange.
+ *
+ * @fires SheetStack#push
+ * @fires SheetStack#pop
+ */
+export declare class SheetStack extends EventTarget {
+    #private;
+    options: Readonly<{
+        layout?: 'stack' | 'cascade';
+        offset?: number;
+        scale?: number;
+        max?: number;
+        onpush?: (event: CustomEvent<{
+            sheet: Sheet;
+            depth: number;
+        }>) => void;
+        onpop?: (event: CustomEvent<{
+            sheet: Sheet;
+        }>) => void;
+    }>;
+    /** @type {Readonly<SheetStackOptions>} */
+    static defaults: Readonly<SheetStackOptions>;
+    /**
+     * Creates a sheet stack.
+     * @param {SheetStackOptions} [options={}] Stack options.
+     */
+    constructor(options?: SheetStackOptions);
+    /**
+     * Adds a sheet to the top of the stack, opening it if it is closed. A sheet already in the stack
+     * is raised rather than added twice.
+     * @param {Sheet} sheet Sheet to push.
+     * @returns {this}
+     * @fires SheetStack#push
+     */
+    push(sheet: Sheet): this;
+    /**
+     * Closes the top sheet and removes it from the stack.
+     *
+     * The removal is synchronous while the close is not — a dialog dispatches `close` in a queued
+     * task — so the stack updates itself here rather than waiting for the event. The close listener
+     * is left to handle the other direction: a sheet dismissed by Escape or its own button.
+     * @returns {Sheet|null} The sheet that was closed, or null on an empty stack.
+     * @fires SheetStack#pop
+     */
+    pop(): Sheet | null;
+    /**
+     * Closes everything above a sheet, leaving it on top.
+     * @param {Sheet} sheet Sheet to return to.
+     * @returns {this}
+     */
+    popTo(sheet: Sheet): this;
+    /**
+     * Closes every sheet, from the top down.
+     * @returns {this}
+     */
+    clear(): this;
+    /**
+     * The sheet currently on top.
+     * @returns {Sheet|null}
+     */
+    top(): Sheet | null;
+    /**
+     * How many sheets the stack holds.
+     * @returns {number}
+     */
+    size(): number;
+    /**
+     * The sheets, bottom first.
+     * @returns {Sheet[]}
+     */
+    sheets(): Sheet[];
+    /**
+     * Whether a sheet is in this stack.
+     * @param {Sheet} sheet Sheet to look for.
+     * @returns {boolean}
+     */
+    has(sheet: Sheet): boolean;
+    /**
+     * Subscribes to a stack event.
+     * @param {string} type Event name.
+     * @param {(event: any) => void} fn Listener.
+     * @returns {this}
+     */
+    on(type: string, fn: (event: any) => void): this;
+    /**
+     * Removes a stack event listener.
+     * @param {string} type Event name.
+     * @param {(event: any) => void} fn Listener.
+     * @returns {this}
+     */
+    off(type: string, fn: (event: any) => void): this;
+    /**
+     * Subscribes to one occurrence of a stack event.
+     * @param {string} type Event name.
+     * @param {(event: any) => void} fn Listener.
+     * @returns {this}
+     */
+    once(type: string, fn: (event: any) => void): this;
+    /**
+     * Empties the stack without closing anything. The sheets are not the stack's to destroy, so
+     * they are simply released with their depth styling removed.
+     * @returns {void}
+     */
+    destroy(): void;
+}

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