@zeyos/zx 2.1.0 → 2.2.0

package/dist/types/components/date-picker/date-range-picker.d.ts

@@ -0,0 +1,350 @@
+import { Component } from '../../core/component.js';
+export type DateRange = {
+    start: Date | null;
+    end: Date | null;
+};
+export type DateRangeState = 'start' | 'middle' | 'end';
+export type DateRangeBounds = {
+    /**
+     * Earliest selectable local calendar day.
+     */
+    min?: Date | null;
+    /**
+     * Latest selectable local calendar day.
+     */
+    max?: Date | null;
+    /**
+     * Smallest number of nights a complete range may span.
+     */
+    minNights?: number;
+    /**
+     * Largest number of nights a complete range may span.
+     */
+    maxNights?: number | null;
+};
+export type DateRangePreset = {
+    /**
+     * Stable identifier, emitted on the preset button as `data-preset`.
+     */
+    name: string;
+    /**
+     * Button text.
+     */
+    label: string;
+    /**
+     * Factory returning the range the preset applies.
+     */
+    range: () => DateRange;
+};
+export type DateRangePickerOptions = {
+    /**
+     * Initially selected first day.
+     */
+    start?: Date | null;
+    /**
+     * Initially selected last day.
+     */
+    end?: Date | null;
+    /**
+     * Earliest selectable local calendar day.
+     */
+    min?: Date | null;
+    /**
+     * Latest selectable local calendar day.
+     */
+    max?: Date | null;
+    /**
+     * Month panels to render; narrow containers show only the first.
+     */
+    months?: number;
+    /**
+     * First weekday, from 0 (Sunday) through 6 (Saturday).
+     */
+    weekStart?: number;
+    /**
+     * Show ISO week numbers.
+     */
+    showWeekNumbers?: boolean;
+    /**
+     * Smallest number of nights a complete range may span.
+     */
+    minNights?: number;
+    /**
+     * Largest number of nights a complete range may span.
+     */
+    maxNights?: number | null;
+    /**
+     * Preset buttons, or `true` for the built-in set.
+     */
+    presets?: DateRangePreset[] | boolean;
+    /**
+     * Disable every control.
+     */
+    disabled?: boolean;
+    /**
+     * Complete-range listener.
+     */
+    onchange?: (event: CustomEvent<DateRange>) => void;
+    /**
+     * Every-click listener.
+     */
+    onselect?: (event: CustomEvent<DateRange>) => void;
+    /**
+     * Visible-month listener.
+     */
+    onmonthchange?: (event: CustomEvent<{
+        year: number;
+        month: number;
+    }>) => void;
+};
+export type DateRangePickerSetOptions = {
+    silent?: boolean;
+};
+/**
+ * Puts a start/end pair in chronological order at local midnight.
+ * Values that are not usable `Date` instances become `null`.
+ * @param {unknown} start Range start.
+ * @param {unknown} end Range end.
+ * @returns {DateRange}
+ */
+export declare function normalizeRange(start: unknown, end: unknown): DateRange;
+/**
+ * Counts the nights between two days. The same day spans zero nights, and the count is derived
+ * from calendar days so daylight-saving transitions never add or drop a night.
+ * @param {unknown} start Range start.
+ * @param {unknown} end Range end.
+ * @returns {number} Nights, or `0` when the range is incomplete.
+ */
+export declare function rangeNights(start: unknown, end: unknown): number;
+/**
+ * Classifies one day against a range. A half-open range only matches its single endpoint, and a
+ * one-day range reports `'start'`.
+ * @param {unknown} day Day to classify.
+ * @param {unknown} start Range start.
+ * @param {unknown} end Range end.
+ * @returns {DateRangeState|null} The day's role, or `null` when it is outside the range.
+ */
+export declare function rangeStateOf(day: unknown, start: unknown, end: unknown): DateRangeState | null;
+/**
+ * Normalizes a range and pulls it inside the configured bounds: endpoints are clamped into
+ * `min`/`max`, an over-long range is shortened to `maxNights`, and a too-short one is stretched to
+ * `minNights` — moving `end` forward, or `start` backward when `max` blocks the way. When the
+ * `min`/`max` window itself is narrower than `minNights` the range cannot be honoured and both
+ * endpoints come back `null`.
+ * @param {DateRange|null|undefined} range Range to clamp.
+ * @param {DateRangeBounds} [bounds={}] Selection bounds.
+ * @returns {DateRange} A new range of new `Date` objects.
+ */
+export declare function clampRange(range: DateRange | null | undefined, bounds?: DateRangeBounds): DateRange;
+/**
+ * Inline two-month range calendar following the APG date-picker grid pattern. Both grids form a
+ * single roving-focus unit, so arrowing off the end of one month continues in the next.
+ * @fires DateRangePicker#change
+ * @fires DateRangePicker#select
+ * @fires DateRangePicker#monthchange
+ * @extends {Component<DateRangePickerOptions>}
+ */
+export declare class DateRangePicker extends Component<DateRangePickerOptions> {
+    _rootAttributes: Map<string, string>;
+    _min: Date;
+    _max: Date;
+    _minNights: number;
+    _maxNights: number;
+    _weekStart: number;
+    _monthCount: number;
+    _presets: DateRangePreset[];
+    _disabled: boolean;
+    _hover: Date;
+    /** @type {{date: Date, cell: HTMLTableCellElement, button: HTMLButtonElement}[]} */
+    _dayCells: {
+        date: Date;
+        cell: HTMLTableCellElement;
+        button: HTMLButtonElement;
+    }[];
+    _start: Date;
+    _end: any;
+    _picking: boolean;
+    _focused: Date;
+    _viewYear: any;
+    _viewMonth: any;
+    _nodes: any[] | HTMLElement[];
+    _committedStart: any;
+    _committedEnd: any;
+    static cssName: string;
+    /** @type {DateRangePickerOptions} */
+    static defaults: DateRangePickerOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns copies of the selected endpoints; the internal dates are never handed out.
+     * @returns {DateRange}
+     */
+    get(): DateRange;
+    /**
+     * Selects a range, clamped to the configured bounds, and scrolls the first visible month to the
+     * range start.
+     * @param {DateRange|null} [range={}] Range to select; omit either endpoint to clear it.
+     * @param {DateRangePickerSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires DateRangePicker#change
+     * @fires DateRangePicker#monthchange
+     */
+    set(range?: DateRange | null, { silent }?: DateRangePickerSetOptions): this;
+    /**
+     * Clears the selection.
+     * @param {DateRangePickerSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires DateRangePicker#change
+     */
+    clear({ silent }?: DateRangePickerSetOptions): this;
+    /**
+     * Moves focus to the currently roving calendar day.
+     * @returns {this}
+     */
+    focus(): this;
+    /** Enables every control. @returns {this} */
+    enable(): this;
+    /** Disables every control. @returns {this} */
+    disable(): this;
+    /** Removes generated content and restores the host element's attributes. @returns {void} */
+    destroy(): void;
+    /** @returns {DateRangeBounds} */
+    _bounds(): DateRangeBounds;
+    /**
+     * Reports whether a day may be clicked. Days before the pending start always may — they restart
+     * the range there instead of producing an inverted one.
+     * @param {Date} date Day to test.
+     * @returns {boolean}
+     */
+    _selectable(date: Date): boolean;
+    /**
+     * Applies one day click: the first sets the start, the second the end, and a click on or before
+     * the pending start restarts the range there.
+     * @param {Date} date Clicked day.
+     * @returns {void}
+     * @fires DateRangePicker#select
+     * @fires DateRangePicker#change
+     */
+    _choose(date: Date): void;
+    /**
+     * Snapshots the selection Escape falls back to. Only a complete range is worth restoring, so a
+     * half-open one is remembered as no selection at all.
+     * @returns {void}
+     */
+    _remember(): void;
+    /**
+     * Abandons a half-picked range, restoring the last complete selection.
+     * @returns {boolean} Whether a half-picked range was discarded.
+     * @fires DateRangePicker#select
+     */
+    _abandon(): boolean;
+    /** @param {Date} date @returns {Date} */
+    _clampFocus(date: Date): Date;
+    /**
+     * Counts the month panels the container query is currently showing, falling back to the
+     * configured count while the picker is not rendered.
+     * @returns {number}
+     */
+    _visibleMonthCount(): number;
+    /**
+     * Points the first visible month at a date's month.
+     * @param {Date} date Day whose month becomes the leftmost panel.
+     * @returns {void}
+     * @fires DateRangePicker#monthchange
+     */
+    _setView(date: Date): void;
+    /**
+     * Shifts the view by the smallest number of months that brings a date into a visible panel.
+     * @param {Date} date Day that must be visible.
+     * @returns {boolean} Whether the view moved.
+     */
+    _ensureVisible(date: Date): boolean;
+    /** @param {number} amount @returns {void} */
+    _pageView(amount: number): void;
+    /**
+     * Keeps the roving tab stop inside the visible panels after the view moved on its own.
+     * @param {Date} date Current roving day.
+     * @returns {Date}
+     */
+    _focusInView(date: Date): Date;
+    /** @param {Date} date @returns {void} */
+    _moveFocus(date: Date): void;
+    /** @returns {void} */
+    _emitMonthChange(): void;
+    /** @param {Event} event @returns {void} */
+    _onPresetClick(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _onCalendarClick(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _onDayHover(event: Event): void;
+    /** @param {Date|null} date @returns {void} */
+    _setHover(date: Date | null): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onDayKeydown(event: KeyboardEvent): void;
+    /** @returns {void} */
+    _renderCalendars(): void;
+    /** @param {Date} first First day of the month to render. @returns {HTMLElement} */
+    _renderMonth(first: Date): HTMLElement;
+    /** @returns {HTMLTableRowElement} */
+    _weekdayRow(): HTMLTableRowElement;
+    /**
+     * Refreshes every day cell's range, selection, and focus state without rebuilding the grids, so
+     * hovering and arrowing never disturb the focused element.
+     * @returns {void}
+     */
+    _paint(): void;
+    /**
+     * Resolves how a day should paint: committed endpoints and band, or the live preview while an
+     * end date is being picked.
+     * @param {Date} date Day to classify.
+     * @returns {{range: DateRangeState|'preview'|null, edge: 'start'|'end'|'both'|null}}
+     */
+    _dayState(date: Date): {
+        range: DateRangeState | 'preview' | null;
+        edge: 'start' | 'end' | 'both' | null;
+    };
+    /**
+     * The day the range would end at right now — the hovered day, or the roving focus when the
+     * pointer is elsewhere.
+     * @returns {Date|null}
+     */
+    _previewEnd(): Date | null;
+    /** @param {Date} date @param {string|null} state @returns {string} */
+    _dayLabel(date: Date, state: string | null): string;
+    /** @returns {void} */
+    _syncDisabled(): void;
+    /** Writes the current selection into the visually hidden live region. @returns {void} */
+    _announce(): void;
+    /** @returns {string} */
+    _selectionLabel(): string;
+    /** @param {Element|null} target @returns {{date: Date, cell: Element, button: Element}|null} */
+    _cellFor(target: Element | null): {
+        date: Date;
+        cell: Element;
+        button: Element;
+    } | null;
+    /** @param {Date} date @returns {HTMLButtonElement|null} */
+    _buttonForDate(date: Date): HTMLButtonElement | null;
+}
+/**
+ * Fired once a complete range is selected, and when the selection is cleared.
+ * @event DateRangePicker#change
+ * @type {CustomEvent<DateRange>}
+ */
+/**
+ * Fired on every day click and preset, including the half-open state where `end` is still null,
+ * and when Escape abandons a half-picked range.
+ * @event DateRangePicker#select
+ * @type {CustomEvent<DateRange>}
+ */
+/**
+ * Fired when the first visible month changes. Month is zero-based.
+ * @event DateRangePicker#monthchange
+ * @type {CustomEvent<{year: number, month: number}>}
+ */
+/**
+ * Builds the shipped preset set: Today, Yesterday, Last 7 days, Last 30 days, This month,
+ * Last month, This quarter, This year.
+ * @returns {DateRangePreset[]}
+ */
+export declare function defaultDateRangePresets(): DateRangePreset[];

package/dist/types/components/date-picker/field-adapter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Registers the MonthPicker-backed `month` field type. Date and datetime fields are registered
+ * by the Datebox adapter so those types retain formatted text-input behavior.
+ * @returns {void}
+ */
+export declare function registerDatePickerFieldAdapters(): void;

package/dist/types/components/date-picker/month-picker.d.ts

@@ -0,0 +1,75 @@
+import { DatePicker } from './date-picker.js';
+export type MonthPickerOptions = {
+    /**
+     * Initially selected month.
+     */
+    value?: Date | null;
+    /**
+     * Earliest selectable month.
+     */
+    min?: Date | null;
+    /**
+     * Latest selectable month.
+     */
+    max?: Date | null;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        date: Date | null;
+    }>) => void;
+};
+export type MonthPickerSetOptions = {
+    silent?: boolean;
+};
+/**
+ * @typedef {Object} MonthPickerOptions
+ * @property {Date|null} [value=null] Initially selected month.
+ * @property {Date|null} [min=null] Earliest selectable month.
+ * @property {Date|null} [max=null] Latest selectable month.
+ * @property {(event: CustomEvent<{date: Date|null}>) => void} [onchange] Change listener.
+ */
+/** @typedef {{silent?: boolean}} MonthPickerSetOptions */
+/**
+ * Twelve-month grid with a year stepper.
+ * @fires MonthPicker#change
+ */
+export declare class MonthPicker extends DatePicker {
+    _year: number;
+    _focusedMonth: number;
+    static cssName: string;
+    /** @type {MonthPickerOptions} */
+    static defaults: MonthPickerOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** @returns {Date|null} */
+    get(): Date | null;
+    /**
+     * Selects the first day of a month.
+     * @param {Date|null} date Month to select, or null to clear.
+     * @param {MonthPickerSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires MonthPicker#change
+     */
+    set(date: Date | null, { silent }?: MonthPickerSetOptions): this;
+    /** @returns {this} */
+    focus(): this;
+    /** Removes generated content from an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @param {Date|null} date @returns {Date|null} */
+    _normalizeMonth(date: Date | null): Date | null;
+    /** @returns {void} */
+    _renderMonths(): void;
+    /** @param {number} amount @returns {void} */
+    _stepYear(amount: number): void;
+    /** @param {Event} event @returns {void} */
+    _onMonthClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onMonthKeydown(event: KeyboardEvent): void;
+    /** @param {number} month @returns {void} */
+    _selectMonth(month: number): void;
+    /** @param {Date} date @returns {boolean} */
+    _inRange(date: Date): boolean;
+    /** @param {number} month @returns {HTMLButtonElement|null} */
+    _button(month: number): HTMLButtonElement | null;
+}

package/dist/types/components/date-picker/range-field-adapter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Registers the DateRangeBox-backed `daterange` field type, so a Form field declared as
+ * `{ type: 'daterange', label, props: {…} }` renders a formatted range input with an anchored
+ * two-month calendar. Field values are `{start, end}` objects of `Date|null`.
+ * @returns {void}
+ */
+export declare function registerDateRangeFieldAdapter(): void;

package/dist/types/components/date-picker/time-picker.d.ts

@@ -0,0 +1,127 @@
+import { Component } from '../../core/component.js';
+export type TimePickerValue = {
+    h: number;
+    m: number;
+    s: number;
+};
+export type ClockUnit = 'h' | 'm';
+export type TimePickerOptions = {
+    /**
+     * Initial local time.
+     */
+    value?: TimePickerValue | Date | null;
+    /**
+     * Show the seconds spinbutton.
+     */
+    seconds?: boolean;
+    /**
+     * Minute increment used by arrow keys.
+     */
+    step?: number;
+    /**
+     * Offer a clock-face dial behind a toggle button.
+     */
+    clock?: boolean;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        time: TimePickerValue;
+    }>) => void;
+};
+export type TimePickerSetOptions = {
+    silent?: boolean;
+};
+export type ClockMark = {
+    value: number;
+    label: string;
+    angle: number;
+    ring: 'outer' | 'inner';
+};
+/**
+ * Accessible segmented time picker made from spinbutton inputs, with an optional clock face for
+ * picking an hour and a minute by eye. The spinbuttons stay the primary control: the dial is a
+ * second, visual route to the same value, and every mark is a radio in an APG radio group.
+ * @fires TimePicker#change
+ * @extends {Component<TimePickerOptions>}
+ */
+export declare class TimePicker extends Component<TimePickerOptions> {
+    _value: TimePickerValue | {
+        h: number;
+        m: number;
+        s: number;
+    };
+    _display: TimePickerValue | {
+        h: number;
+        m: number;
+        s: number;
+    };
+    _inputs: any[];
+    _clockOpen: boolean;
+    /** @type {ClockUnit} */
+    _clockUnit: ClockUnit;
+    _clock: HTMLElement;
+    _content: HTMLElement;
+    static cssName: string;
+    /** @type {TimePickerOptions} */
+    static defaults: TimePickerOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Returns a copy of the selected time, or null when no initial value has been committed.
+     * @returns {TimePickerValue|null}
+     */
+    get(): TimePickerValue | null;
+    /**
+     * Sets the displayed local time.
+     * @param {TimePickerValue|Date|null} value Time object, Date, or null.
+     * @param {TimePickerSetOptions} [options={}] Update behavior.
+     * @returns {this}
+     * @fires TimePicker#change
+     */
+    set(value: TimePickerValue | Date | null, { silent }?: TimePickerSetOptions): this;
+    /**
+     * Opens the clock face on the given unit.
+     * @param {ClockUnit} [unit='h'] Dial to show first.
+     * @returns {this}
+     */
+    openClock(unit?: ClockUnit): this;
+    /** Closes the clock face. @returns {this} */
+    closeClock(): this;
+    /** Toggles the clock face. @returns {this} */
+    toggleClock(): this;
+    /** Removes generated content from an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @param {HTMLElement} parent @param {'h'|'m'|'s'} segment @param {string} label @param {number} max @returns {void} */
+    _addSpin(parent: HTMLElement, segment: 'h' | 'm' | 's', label: string, max: number): void;
+    /** @param {KeyboardEvent} event @param {'h'|'m'|'s'} segment @param {number} max @returns {void} */
+    _onKeydown(event: KeyboardEvent, segment: 'h' | 'm' | 's', max: number): void;
+    /** @param {HTMLInputElement} input @param {'h'|'m'|'s'} segment @param {number} max @returns {void} */
+    _onInput(input: HTMLInputElement, segment: 'h' | 'm' | 's', max: number): void;
+    /** @returns {void} */
+    _commitFromInputs(): void;
+    /** @returns {void} */
+    _writeInputs(): void;
+    /**
+     * Builds the collapsible clock face: a read-out that doubles as the hour/minute switch, and a
+     * dial whose marks are radios.
+     * @param {string} id Element id the toggle button controls.
+     * @returns {HTMLElement}
+     */
+    _buildClock(id: string): HTMLElement;
+    /**
+     * Applies a mark's value to the active unit, then moves on to the minutes so a whole time can
+     * be set with two clicks.
+     * @param {number} value Hour or minute the mark stands for.
+     * @returns {void}
+     */
+    _pick(value: number): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onDialKeydown(event: KeyboardEvent): void;
+    /** Reflects the open state, the active unit, the marks, and the hand. @returns {void} */
+    _syncClock(): void;
+    /** @param {ClockMark} mark @param {number} selected @returns {HTMLElement} */
+    _buildMark(mark: ClockMark, selected: number): HTMLElement;
+    /** @param {HTMLElement} element @param {ClockMark} mark @param {number} selected @returns {void} */
+    _syncMark(element: HTMLElement, mark: ClockMark, selected: number): void;
+}