@zeyos/zx 2.1.0 → 2.2.0

package/dist/types/components/number-field/number-field.d.ts

@@ -0,0 +1,292 @@
+import { Component } from '../../core/component.js';
+export type NumberFieldOptions = {
+    /**
+     * Initial value, or null for empty.
+     */
+    value?: number | null;
+    /**
+     * Lowest accepted value.
+     */
+    min?: number | null;
+    /**
+     * Highest accepted value.
+     */
+    max?: number | null;
+    /**
+     * Increment applied by the buttons and arrow keys.
+     */
+    step?: number;
+    /**
+     * Multiple of `step` applied by PageUp/PageDown.
+     */
+    largeStep?: number;
+    /**
+     * Decimal places; derived from `step` when null.
+     */
+    precision?: number | null;
+    /**
+     * Whether stepping past a bound wraps to the other one.
+     */
+    wrap?: boolean;
+    /**
+     * Empty-state text.
+     */
+    placeholder?: string;
+    /**
+     * Accessible name for the spinbutton.
+     */
+    label?: string | null;
+    /**
+     * Suffix rendered inside the control (e.g. `%`, `kg`).
+     */
+    unit?: string | null;
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the value is read-only.
+     */
+    readonly?: boolean;
+    /**
+     * Whether an empty value is invalid.
+     */
+    required?: boolean;
+    /**
+     * Native form field name.
+     */
+    name?: string | null;
+    /**
+     * Whether to render thousands separators while idle.
+     */
+    group?: boolean;
+    /**
+     * Locale for formatting; defaults to the document locale.
+     */
+    locale?: string | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Committed-value listener.
+     */
+    onchange?: (event: CustomEvent<{
+        value: number | null;
+    }>) => void;
+    /**
+     * Per-keystroke listener.
+     */
+    oninput?: (event: CustomEvent<{
+        value: number | null;
+    }>) => void;
+};
+/**
+ * @typedef {Object} NumberFieldOptions
+ * @property {number|null} [value=null] Initial value, or null for empty.
+ * @property {number|null} [min=null] Lowest accepted value.
+ * @property {number|null} [max=null] Highest accepted value.
+ * @property {number} [step=1] Increment applied by the buttons and arrow keys.
+ * @property {number} [largeStep=10] Multiple of `step` applied by PageUp/PageDown.
+ * @property {number|null} [precision=null] Decimal places; derived from `step` when null.
+ * @property {boolean} [wrap=false] Whether stepping past a bound wraps to the other one.
+ * @property {string} [placeholder=''] Empty-state text.
+ * @property {string|null} [label=null] Accessible name for the spinbutton.
+ * @property {string|null} [unit=null] Suffix rendered inside the control (e.g. `%`, `kg`).
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {boolean} [readonly=false] Whether the value is read-only.
+ * @property {boolean} [required=false] Whether an empty value is invalid.
+ * @property {string|null} [name=null] Native form field name.
+ * @property {boolean} [group=false] Whether to render thousands separators while idle.
+ * @property {string|null} [locale=null] Locale for formatting; defaults to the document locale.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{value: number|null}>) => void} [onchange] Committed-value listener.
+ * @property {(event: CustomEvent<{value: number|null}>) => void} [oninput] Per-keystroke listener.
+ */
+/**
+ * Numeric input with decrement and increment buttons, following the APG spinbutton pattern.
+ *
+ * The step buttons are pointer affordances only (`tabindex="-1"`, `aria-hidden`): the input
+ * itself is the spinbutton, so keyboard and screen-reader users step with the arrow keys rather
+ * than tabbing through two extra controls in every form row.
+ *
+ * @fires NumberField#change
+ * @fires NumberField#input
+ * @extends {Component<NumberFieldOptions>}
+ */
+export declare class NumberField extends Component<NumberFieldOptions> {
+    _value: number;
+    _disabled: boolean;
+    _readonly: boolean;
+    _editing: boolean;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _step: number;
+    _precision: number;
+    _min: number;
+    _max: number;
+    _localeSeparators: {
+        group: string;
+        decimal: string;
+    };
+    static cssName: string;
+    /** @type {NumberFieldOptions} */
+    static defaults: NumberFieldOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Current value, or null when empty. @returns {number|null} */
+    get value(): number | null;
+    /** @param {number|null} next Next value. */
+    set value(next: number | null);
+    /**
+     * Returns the current value.
+     * @returns {number|null}
+     */
+    get(): number | null;
+    /**
+     * Sets the value, snapping it to `step` and clamping it into `[min, max]`.
+     * @param {number|string|null} next Next value; empty strings and null clear the field.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+     * @returns {this}
+     * @fires NumberField#change
+     */
+    set(next: number | string | null, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Increases the value by `count` steps.
+     * @param {number} [count=1] Number of steps.
+     * @returns {this}
+     * @fires NumberField#change
+     */
+    stepUp(count?: number): this;
+    /**
+     * Decreases the value by `count` steps.
+     * @param {number} [count=1] Number of steps.
+     * @returns {this}
+     * @fires NumberField#change
+     */
+    stepDown(count?: number): this;
+    /**
+     * Restores the configured initial value.
+     * @param {{silent?: boolean}} [options={}] Reset behavior.
+     * @returns {this}
+     */
+    reset({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Focuses the input. @returns {this} */
+    focus(): this;
+    /** Returns the underlying input element. @returns {HTMLInputElement} */
+    getInput(): HTMLInputElement;
+    /** Enables user interaction. @returns {this} */
+    enable(): this;
+    /** Disables user interaction. @returns {this} */
+    disable(): this;
+    /**
+     * Sets the read-only state.
+     * @param {boolean} readonly Whether the value is read-only.
+     * @returns {this}
+     */
+    setReadonly(readonly: boolean): this;
+    /**
+     * Replaces the accepted range.
+     * @param {number|null} min Lowest accepted value.
+     * @param {number|null} max Highest accepted value.
+     * @returns {this}
+     */
+    setRange(min: number | null, max: number | null): this;
+    /** @param {'down'|'up'} direction @param {string} glyph @returns {HTMLButtonElement} */
+    _stepButton(direction: 'down' | 'up', glyph: string): HTMLButtonElement;
+    /** @returns {number|null} */
+    get _rangeMin(): number | null;
+    /** @returns {number|null} */
+    get _rangeMax(): number | null;
+    /**
+     * Parses, snaps, and clamps an arbitrary input value.
+     * @param {unknown} raw Value from an option, a method call, or the input element.
+     * @returns {number|null}
+     */
+    _coerce(raw: unknown): number | null;
+    /**
+     * Applies `count` steps relative to the current value.
+     * @param {number} count Signed step count.
+     * @returns {this}
+     */
+    _stepBy(count: number): this;
+    /**
+     * The grouping and decimal separators of the configured locale.
+     * @returns {{group: string, decimal: string}}
+     */
+    _separators(): {
+        group: string;
+        decimal: string;
+    };
+    /** @returns {void} */
+    _onInput(): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onKeydown(event: KeyboardEvent): void;
+    /** Parses whatever the user typed and normalizes the displayed text. @returns {void} */
+    _commit(): void;
+    /** @returns {void} */
+    _syncInput(): void;
+    /**
+     * @param {number|null} value Value to announce.
+     * @returns {void}
+     */
+    _syncAria(value: number | null): void;
+    /**
+     * @param {number} value Value to render.
+     * @param {boolean} editing Whether the field currently has focus.
+     * @returns {string}
+     */
+    _format(value: number, editing: boolean): string;
+    /**
+     * @param {string} key Message key.
+     * @param {string} fallback Text used when the host has no translation.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+    destroy(): void;
+}
+/**
+ * Committed value change.
+ * @event NumberField#change
+ * @type {CustomEvent<{value: number|null}>}
+ */
+/**
+ * Per-keystroke value change; the value may still be unsnapped or out of range.
+ * @event NumberField#input
+ * @type {CustomEvent<{value: number|null}>}
+ */
+/**
+ * Parses a user-entered number.
+ *
+ * With `separators` (from the field's locale) the grouping character is removed and the decimal
+ * character is honoured, so a displayed `1,234` in en-US reads back as 1234 rather than 1.234.
+ * Without them, the last of `.` or `,` is treated as the decimal point and the other as grouping,
+ * which is the best available guess for free-form typing.
+ *
+ * @param {unknown} raw Value to parse.
+ * @param {{group: string, decimal: string}|null} [separators=null] Known locale separators.
+ * @returns {number|null} The number, or null when the input is empty or unparseable.
+ */
+export declare function parseNumber(raw: unknown, separators?: {
+    group: string;
+    decimal: string;
+} | null): number | null;
+/**
+ * Snaps a number onto the step grid and clamps it into the accepted range.
+ * @param {number} value Raw value.
+ * @param {{min: number|null, max: number|null, step: number, precision: number}} spec Constraints.
+ * @returns {number}
+ */
+export declare function snapNumber(value: number, { min, max, step, precision }: {
+    min: number | null;
+    max: number | null;
+    step: number;
+    precision: number;
+}): number;

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

@@ -0,0 +1,267 @@
+import { Component } from '../../core/component.js';
+export type PaginationMode = 'pages' | 'loadmore';
+export type PaginationRangeOptions = {
+    /**
+     * One-based current page.
+     */
+    page: number;
+    /**
+     * Total number of pages.
+     */
+    pages: number;
+    /**
+     * Pages shown either side of the current one.
+     */
+    siblings?: number;
+    /**
+     * Pages pinned at each end of the range.
+     */
+    boundaries?: number;
+};
+/**
+ * @typedef {Object} PaginationRangeOptions
+ * @property {number} page One-based current page.
+ * @property {number} pages Total number of pages.
+ * @property {number} [siblings=1] Pages shown either side of the current one.
+ * @property {number} [boundaries=1] Pages pinned at each end of the range.
+ */
+/**
+ * Computes the page window: the numbers a pager shows, with `'…'` standing in for every run it
+ * skipped. Pure arithmetic, no DOM — the component renders whatever this returns.
+ *
+ * The window has a fixed width of `boundaries * 2 + siblings * 2 + 3` entries (the current page
+ * plus two possible gaps), so it never jitters as the user walks through the pages. Any shorter
+ * range is returned in full. A single skipped page is printed instead of a gap, because `…`
+ * standing for one number would be a lie. `boundaries: 0` drops the pinned first and last pages.
+ * @param {PaginationRangeOptions} options Window description.
+ * @returns {Array<number|'…'>} One-based page numbers interleaved with ellipses.
+ */
+export declare function paginationRange({ page, pages, siblings, boundaries }?: PaginationRangeOptions): Array<number | '…'>;
+export type PaginationOptions = {
+    /**
+     * One-based current page.
+     */
+    page?: number;
+    /**
+     * Rows per page.
+     */
+    pageSize?: number;
+    /**
+     * Total row count; 0 is one empty page.
+     */
+    total?: number;
+    /**
+     * Choices offered by the page-size select.
+     */
+    pageSizes?: number[];
+    /**
+     * Pages shown either side of the current one.
+     */
+    siblings?: number;
+    /**
+     * Pages pinned at each end of the range.
+     */
+    boundaries?: number;
+    /**
+     * Whether to render the page-size select.
+     */
+    showPageSize?: boolean;
+    /**
+     * Whether to render the "26–50 of 312" summary.
+     */
+    showSummary?: boolean;
+    /**
+     * `pages` renders a numbered pager, `loadmore` a single
+     * "Load more" button for append-style lists.
+     */
+    mode?: PaginationMode;
+    /**
+     * Whether every control starts disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<PaginationChangeDetail>) => void;
+};
+export type PaginationState = {
+    /**
+     * One-based current page.
+     */
+    page: number;
+    /**
+     * Rows per page.
+     */
+    pageSize: number;
+    /**
+     * Total row count.
+     */
+    total: number;
+    /**
+     * Number of pages; at least 1.
+     */
+    pages: number;
+    /**
+     * Zero-based row offset of the current page.
+     */
+    offset: number;
+};
+export type PaginationChangeDetail = PaginationState;
+/**
+ * @typedef {Object} PaginationOptions
+ * @property {number} [page=1] One-based current page.
+ * @property {number} [pageSize=25] Rows per page.
+ * @property {number} [total=0] Total row count; 0 is one empty page.
+ * @property {number[]} [pageSizes=[25, 50, 100]] Choices offered by the page-size select.
+ * @property {number} [siblings=1] Pages shown either side of the current one.
+ * @property {number} [boundaries=1] Pages pinned at each end of the range.
+ * @property {boolean} [showPageSize=true] Whether to render the page-size select.
+ * @property {boolean} [showSummary=true] Whether to render the "26–50 of 312" summary.
+ * @property {PaginationMode} [mode='pages'] `pages` renders a numbered pager, `loadmore` a single
+ *   "Load more" button for append-style lists.
+ * @property {boolean} [disabled=false] Whether every control starts disabled.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<PaginationChangeDetail>) => void} [onchange] Change listener.
+ */
+/**
+ * @typedef {Object} PaginationState
+ * @property {number} page One-based current page.
+ * @property {number} pageSize Rows per page.
+ * @property {number} total Total row count.
+ * @property {number} pages Number of pages; at least 1.
+ * @property {number} offset Zero-based row offset of the current page.
+ */
+/** @typedef {PaginationState} PaginationChangeDetail */
+/**
+ * The pager for a server-backed list. It owns no data: it reports which slice the user asked for
+ * and lets the application fetch it, which is exactly the shape `zeyosTable()` expects —
+ * `offset`/`pageSize` for `load()` in `pages` mode, or one `change` per `loadMore()` in
+ * `loadmore` mode.
+ *
+ * `page` is clamped into `[1, pages]` after every state change, so shrinking `total` under the
+ * user's feet can never leave the pager pointing past the end of the data.
+ * @fires Pagination#change
+ * @extends {Component<PaginationOptions>}
+ */
+export declare class Pagination extends Component<PaginationOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    _pageSize: number;
+    _total: number;
+    _page: number;
+    _disabled: boolean;
+    _sizeKey: any;
+    _pageSizes: number[];
+    static cssName: string;
+    /** @type {Readonly<PaginationOptions>} */
+    static defaults: Readonly<PaginationOptions>;
+    /**
+     * Creates or enhances a pager.
+     * @param {Element|string|null} target Existing container, selector, or null.
+     * @param {PaginationOptions} [options={}] Pagination options.
+     */
+    constructor(target: Element | string | null, options?: PaginationOptions);
+    /**
+     * Builds the pager. Runs inside the base constructor, so instance state is initialized here.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Moves to a page, clamped into `[1, pages]`.
+     * @param {number} page One-based page number.
+     * @returns {this}
+     * @fires Pagination#change
+     */
+    setPage(page: number): this;
+    /**
+     * Replaces the total row count and re-clamps the page. Silent: servers report the count as part
+     * of a response the pager itself asked for, so echoing a `change` back would loop.
+     * @param {number} total Total row count.
+     * @returns {this}
+     */
+    setTotal(total: number): this;
+    /**
+     * Replaces the page size and returns to page 1.
+     * @param {number} pageSize Rows per page.
+     * @returns {this}
+     * @fires Pagination#change
+     */
+    setPageSize(pageSize: number): this;
+    /**
+     * Applies any combination of page, page size, and total in one pass, then clamps the page.
+     * `change` fires when the effective page or page size moved — updating only `total` is silent
+     * unless the new count clamps the page.
+     * @param {Partial<Pick<PaginationState, 'page'|'pageSize'|'total'>>} [state={}] Values to change.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress the event.
+     * @returns {this}
+     * @fires Pagination#change
+     */
+    setState(state?: Partial<Pick<PaginationState, 'page' | 'pageSize' | 'total'>>, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Returns the current slice description.
+     * @returns {PaginationState}
+     */
+    getState(): PaginationState;
+    /**
+     * Enables every control.
+     * @returns {this}
+     */
+    enable(): this;
+    /**
+     * Disables every control, for instance while a page is in flight.
+     * @returns {this}
+     */
+    disable(): this;
+    /**
+     * Aborts listeners and restores an enhanced target to the markup it had before the takeover.
+     * @returns {void}
+     */
+    destroy(): void;
+    /** @returns {number} Page count; an empty list is one empty page. */
+    _pageCount(): number;
+    /** @returns {HTMLElement} The page-size select and its visible label. */
+    _renderPageSize(): HTMLElement;
+    /** @returns {HTMLElement} Previous / page buttons / next. */
+    _renderPages(): HTMLElement;
+    /**
+     * @param {string} ref Ref name.
+     * @param {string} glyph Icon name.
+     * @param {string} label Accessible name.
+     * @returns {HTMLElement}
+     */
+    _navButton(ref: string, glyph: string, label: string): HTMLElement;
+    /** @returns {HTMLElement} The append-style trigger. */
+    _renderLoadMore(): HTMLElement;
+    /** Attaches the delegated listeners once, after the shell exists. @returns {void} */
+    _wire(): void;
+    /** Pushes the current state onto every control. @returns {void} */
+    _sync(): void;
+    /**
+     * @returns {string} The "26–50 of 312" line.
+     */
+    _summary(): string;
+    /** Rebuilds the page-size options only when the choice set actually changed. @returns {void} */
+    _syncPageSize(): void;
+    /**
+     * Rebuilds the page buttons, keeping the keyboard focus on the same page number when the user
+     * paged with the keyboard and that number survived the rebuild.
+     * @param {number} pages Page count.
+     * @returns {void}
+     */
+    _syncPages(pages: number): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
+}