@zeyos/zx 5.0.0 → 5.2.0

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

@@ -1,6 +1,4 @@
 import { Component } from '../../core/component.js';
-declare const HANDLE_POINTER_DISMISS: unique symbol;
-declare const HANDLE_ESCAPE_DISMISS: unique symbol;
 export type DropdownOptions = {
     /**
      * Panel content.
@@ -55,6 +53,16 @@ export type DropdownOptions = {
  */
 /**
  * Generic anchored floating panel using the browser popover top layer.
+ *
+ * Open, the panel is one entry on the overlay stack (`core/overlay-stack.js`): Escape closes it
+ * only while it is the topmost layer that takes Escape, a press outside it and every overlay opened
+ * from it closes it, and it closes with the overlay its anchor sits in. Inside an open dialog the
+ * panel is hosted by that dialog, so `showModal()` does not make it inert.
+ *
+ * The panel follows its trigger in the Tab order: Tab on the anchor of an open panel moves into
+ * the panel's first focusable control (or onto the panel itself when it carries a `tabindex`),
+ * Tab past the panel's last control continues after the anchor, and Shift+Tab from the first goes
+ * back to the anchor. Closing while focus is inside returns it to the anchor.
  * @fires Dropdown#open
  * @fires Dropdown#close
  * @extends {Component<DropdownOptions>}
@@ -115,9 +123,16 @@ export declare class Dropdown extends Component<DropdownOptions> {
      * @returns {void}
      */
     destroy(): void;
-    /** @param {PointerEvent} event @returns {void} */
-    [HANDLE_POINTER_DISMISS](event: PointerEvent): void;
-    /** @param {KeyboardEvent} event @returns {void} */
-    [HANDLE_ESCAPE_DISMISS](event: KeyboardEvent): void;
+    /**
+     * Internal seam for components built on a Dropdown (MenuButton, ContextMenu, the app rail):
+     * replaces what Escape does when the overlay stack routes it to this panel, and takes the panel
+     * out of the anchor's Tab order — a menu is reached with the arrow keys, not Tab.
+     * @param {{onEscape?: ((event: KeyboardEvent) => void)|null, tabReach?: boolean}} settings
+     * @returns {this}
+     * @internal
+     */
+    _configure(settings: {
+        onEscape?: ((event: KeyboardEvent) => void) | null;
+        tabReach?: boolean;
+    }): this;
 }
-export {};

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

@@ -38,6 +38,12 @@ export type FieldOptions = {
      * Whether the control is disabled.
      */
     disabled?: boolean;
+    /**
+     * Whether the value is read-only: shown and focusable, not
+     * editable. Types whose control has no read-only state (`checkbox`, `select`, `optionlist`,
+     * `zxselect`, `date`, `time`, …) ignore it.
+     */
+    readonly?: boolean;
     /**
      * Select or option-list values.
      */
@@ -90,6 +96,11 @@ export type FieldAdapter = {
      * Set disabled state.
      */
     setDisabled: (disabled: boolean) => void;
+    /**
+     * Set read-only state; left out when the
+     * control has none.
+     */
+    setReadonly?: (readonly: boolean) => void;
     /**
      * Release adapter-owned resources.
      */
@@ -119,6 +130,9 @@ export type NumericCoercion = {
  * @property {string} [placeholder=''] Control placeholder.
  * @property {boolean} [required=false] Whether a value is required.
  * @property {boolean} [disabled=false] Whether the control is disabled.
+ * @property {boolean} [readonly=false] Whether the value is read-only: shown and focusable, not
+ *   editable. Types whose control has no read-only state (`checkbox`, `select`, `optionlist`,
+ *   `zxselect`, `date`, `time`, …) ignore it.
  * @property {string[]|Record<string, string>|null} [options=null] Select or option-list values.
  * @property {'stack'|'inline'} [layout='stack'] Label/control layout.
  * @property {Record<string, unknown>} [props={}] Adapter-specific control properties.
@@ -133,6 +147,8 @@ export type NumericCoercion = {
  * @property {(value: unknown, options?: {silent?: boolean}) => void} set Set the current value.
  * @property {() => void} focus Focus the control.
  * @property {(disabled: boolean) => void} setDisabled Set disabled state.
+ * @property {(readonly: boolean) => void} [setReadonly] Set read-only state; left out when the
+ *   control has none.
  * @property {() => void} [destroy] Release adapter-owned resources.
  * @property {Element} [labelTarget] The element the field's label, description, and validity
  *   belong to when it is not `el` — the text input inside a composite control. Left out, a
@@ -143,6 +159,7 @@ export type NumericCoercion = {
 /**
  * One labelled form control backed by a registered adapter.
  * @fires Field#change
+ * @fires Field#input
  * @fires Field#invalid
  * @extends {Component<FieldOptions>}
  */
@@ -213,6 +230,13 @@ export declare class Field extends Component<FieldOptions> {
      * @returns {this}
      */
     setDisabled(disabled: boolean): this;
+    /**
+     * Makes the value read-only or editable again, where the control has a read-only state (see
+     * the `readonly` option); reflected as `data-readonly` on the root either way.
+     * @param {boolean} readonly Read-only state.
+     * @returns {this}
+     */
+    setReadonly(readonly: boolean): this;
     /**
      * Displays a validation or status message.
      * @param {string} message Message text.
@@ -260,6 +284,12 @@ export declare function coerceFloat(input: unknown): NumericCoercion;
  * @event Field#change
  * @type {CustomEvent<{value: unknown}>}
  */
+/**
+ * Live edit before it is committed, from the types whose widget tells the two apart (`code`,
+ * `slider`): every keystroke or drag step, where `change` follows only on commit.
+ * @event Field#input
+ * @type {CustomEvent<{value: unknown}>}
+ */
 /**
  * Field validation failure event.
  * @event Field#invalid

package/dist/types/components/fieldset/external-adapter.d.ts

@@ -0,0 +1,83 @@
+export type Field = import('../field/field.js').Field;
+export type FieldAdapter = import('../field/field.js').FieldAdapter;
+export type ExternalSource = Element | {
+    el?: Element;
+    toElement?: () => Element;
+};
+/** @typedef {import('../field/field.js').Field} Field */
+/** @typedef {import('../field/field.js').FieldAdapter} FieldAdapter */
+/**
+ * An element or component a Fieldset adopts with `addField(id, source)`: anything that renders
+ * into an element. Components are read through the methods they have, elements through their
+ * native properties.
+ * @typedef {Element|{el?: Element, toElement?: () => Element}} ExternalSource
+ */
+/**
+ * The value accessor pairs the library's components use, in the order they are tried. A reader
+ * counts only when it takes no required argument (`Fieldset.getValue(id)` is not a reader), a
+ * writer of another pair only when the value is its sole required argument.
+ * - `getValue/setValue`: Field, CodeEditor, Filter, SortControl, Toggle (`getValue()` is the
+ *   configured on-value or `false`, the same as the `toggle` field type reads).
+ * - `get/set`: NumberField, Select, Slider, Rating, CheckButton, Datebox, Timebox, Search,
+ *   CopyInput, DatePicker and the other pickers.
+ * - `getValues/setValues`: Checklist, TagPicker, ValueList, MultiValueEditor, Fieldset, Form.
+ * - `isChecked/setChecked`: boolean controls that name their state that way.
+ * @type {ReadonlyArray<readonly [string, string]>}
+ */
+export declare const VALUE_METHODS: ReadonlyArray<readonly [string, string]>;
+/**
+ * The element a source renders into.
+ * @param {ExternalSource} source Element or component.
+ * @returns {Element}
+ */
+export declare function externalElement(source: ExternalSource): Element;
+/**
+ * Reads the current value of an element or component through the first value dialect it
+ * supports (see {@link VALUE_METHODS}), then a `value`, `values`, or `checked` property, then the
+ * element itself: `checked` for a checkbox or radio, `value` for any other control. Null when
+ * the source has no value at all.
+ * @param {ExternalSource} source Element or component.
+ * @returns {unknown}
+ */
+export declare function readExternalValue(source: ExternalSource): unknown;
+/**
+ * Reports whether an element or component is disabled: its `isDisabled()`, a `disabled`
+ * property, the element's own `disabled`, an `aria-disabled="true"` or `data-disabled` root, or
+ * a wrapper whose every form control is disabled.
+ * @param {ExternalSource} source Element or component.
+ * @returns {boolean}
+ */
+export declare function readExternalDisabled(source: ExternalSource): boolean;
+/**
+ * Reports whether an element or component is read-only: a `readonly`/`readOnly` property, the
+ * element's own `readOnly`, or an `aria-readonly="true"` or `data-readonly` root.
+ * @param {ExternalSource} source Element or component.
+ * @returns {boolean}
+ */
+export declare function readExternalReadonly(source: ExternalSource): boolean;
+/**
+ * Builds the Field adapter for an element or component that is not a registered field type.
+ *
+ * Values go through the source's own accessors ({@link readExternalValue}); disabling through
+ * `setDisabled(bool)`, then `enable()`/`disable()`, then a `disabled` property, and only then the
+ * DOM — the element's `disabled`, or for a plain wrapper `aria-disabled` plus `disabled` on every
+ * form control inside it. Read-only goes through `setReadonly(bool)`/`setReadOnly(bool)`, a
+ * `readonly`/`readOnly` property, or the element's own `readOnly`.
+ *
+ * Writes pass the caller's options to the component: `Field.setValue(v)` or
+ * `Fieldset.setValues(values)` without `silent` lets the component emit its own `change` to its
+ * own listeners, while the field emits one `change` for the write; with `silent` neither does.
+ *
+ * Given the field, a component's own `change` event becomes the field's `change`, and the native
+ * `change` its inner controls bubble is dropped unless it carries a value the component did not
+ * already report — so one edit is one field `change`, whether the component reports it, its
+ * input does, or (Search, CopyInput) only its input does.
+ *
+ * `destroy()` puts the element back where it was found and undoes what the adapter changed:
+ * attributes, the native value, disabled and read-only state.
+ * @param {ExternalSource} source Element or component to adopt.
+ * @param {Field|null} [field=null] The field the adapter serves; needed to forward events. Its
+ *   `listen()` owns every listener the adapter adds, so destroying the field removes them.
+ * @returns {FieldAdapter}
+ */
+export declare function externalAdapter(source: ExternalSource, field?: Field | null): FieldAdapter;

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

@@ -53,6 +53,13 @@ export declare class Fieldset extends Component<FieldsetOptions> {
      * Adds a field from options, an existing field, an element, or a component. The key becomes the
      * field's `name` and its `data-field-id`; the control's DOM id is `<idPrefix>-<key>`, unless the
      * field options give an `id` of their own that differs from the key.
+     *
+     * An element or a component that is not a registered field type is wrapped in a `custom` field
+     * that reads and writes it through its own API — `getValue`/`setValue`, `get`/`set`,
+     * `getValues`/`setValues`, `isChecked`/`setChecked`, or a `value` property — disables it
+     * through `setDisabled(bool)` or `enable()`/`disable()`, and makes it read-only through
+     * `setReadonly(bool)`, falling back to the element's native properties only when the component
+     * has none of these. The component's own `change` becomes the field's `change`, once per edit.
      * @param {string} id Logical field identifier.
      * @param {FieldOptions|Field|Element|Component} field Field source.
      * @returns {Field}

package/dist/types/components/file-list/file-list.d.ts

@@ -75,6 +75,12 @@ export type FileListOptions = {
 /**
  * Accessible collection for durable and transient files. Ordering and mutation are local
  * presentation concerns only; transport, authorization, and persistence remain host-owned.
+ *
+ * Mutations are reconciled by file `id`: a file whose descriptor did not change keeps its row
+ * untouched, a changed one is updated in place through `FileItem.set()`, and only added or removed
+ * files create or drop rows. Upload progress can therefore tick through `updateItem()` while the
+ * reader's focus — on that file's Cancel button, say — and the list's scroll position stay put.
+ * Files without an `id` cannot be matched and are rebuilt on every mutation.
  * @fires FileList#activate
  * @fires FileList#action
  * @fires FileList#datachange
@@ -86,7 +92,16 @@ export declare class FileList extends Component<FileListOptions> {
     _destroyed: boolean;
     _items: import("../file-item/file-item.js").FileItemState[];
     _loading: any;
-    _itemComponents: any[];
+    _itemComponents: any[] | FileItem[];
+    /** @type {Map<FileItem, {row: HTMLElement, state: FileItemState}>} */
+    _itemRecords: Map<FileItem, {
+        row: HTMLElement;
+        state: FileItemState;
+    }>;
+    _itemList: HTMLElement;
+    _emptyRegion: HTMLElement;
+    _loadingRegion: HTMLElement;
+    _loadingPlaceholders: boolean;
     static cssName: string;
     /** @type {Readonly<FileListOptions>} */
     static defaults: Readonly<FileListOptions>;
@@ -144,10 +159,27 @@ export declare class FileList extends Component<FileListOptions> {
     setLoading(loading: boolean): this;
     /** Restores an enhanced target exactly, or removes an owned collection. @returns {void} */
     destroy(): void;
-    /** @returns {void} */
+    /**
+     * Brings the rendered rows in line with `_items`, keyed by file id, and keeps focus on the
+     * control that held it when that control's row was updated or removed.
+     * @returns {void}
+     */
     _renderList(): void;
-    /** @param {boolean} placeholders @returns {HTMLElement} */
+    /**
+     * Keyed reconciliation of `FileItem` children. Rows are only moved when out of place, because
+     * detaching a row — even to re-insert it a moment later — takes focus out of it.
+     * @returns {void}
+     */
+    _reconcileItems(): void;
+    /**
+     * The loading region, kept across renders while its shape stays the same so that its live
+     * status is not re-announced by every mutation that happens during a load.
+     * @param {boolean} placeholders Whether skeleton rows stand in for an empty list.
+     * @returns {HTMLElement}
+     */
     _createLoading(placeholders: boolean): HTMLElement;
+    /** @param {boolean} placeholders @returns {HTMLElement} */
+    _buildLoading(placeholders: boolean): HTMLElement;
     /** @returns {void} */
     _destroyItems(): void;
     /** @param {CustomEvent} event @returns {void} */

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

@@ -22,7 +22,13 @@ export type FilterField = {
      */
     defaultOperator?: string;
     /**
-     * Static choices.
+     * Glyph beside the field's name in a `searchable` field picker, an
+     * icon name or a node; a native `<select>` cannot show one.
+     */
+    icon?: string | Node;
+    /**
+     * Static choices; a
+     * choice's `icon` shows beside it in a `searchable` value picker.
      */
     choices?: Array<{
         value: string | number | boolean;
@@ -96,11 +102,13 @@ export type FilterOptions = {
      */
     maxConditions?: number;
     /**
-     * Searchable field, operator and single-choice controls.
+     * Searchable field, operator and single-choice controls; a many-valued
+     * operator on a field with static choices gets a `TagPicker`.
      */
     searchable?: boolean;
     /**
-     * Condition layout; compact rows adapt to container width.
+     * Condition layout; compact rows adapt to container width and
+     * show the group's "and"/"or" between them, a click on it switching the group's logic.
      */
     layout?: 'standard' | 'compact';
     /**
@@ -186,6 +194,8 @@ export type FilterValueMessages = {
      */
     valueAt: (label: string, position: number) => string;
 };
+/** Units a relative date span may be counted in, in the order the editor offers them. */
+export declare const RELATIVE_DATE_UNITS: readonly string[];
 /**
  * Backend-neutral dynamic filter expression editor.
  * @fires Filter#change
@@ -205,6 +215,7 @@ export declare class Filter extends Component<FilterOptions> {
         type: 'text' | 'number' | 'money' | 'date' | 'datetime' | 'boolean' | 'enum' | 'status' | 'priority' | 'country' | 'currency' | 'unit' | 'entity' | 'tags' | 'custom';
         operators?: string[];
         defaultOperator?: string;
+        icon?: string | Node;
         choices?: Array<{
             value: string | number | boolean;
             label: string;
@@ -289,10 +300,36 @@ export declare class Filter extends Component<FilterOptions> {
     _render(): void;
     /** @param {any} group @param {number} depth @param {boolean} root @returns {HTMLElement} */
     _renderGroup(group: any, depth: number, root: boolean): HTMLElement;
+    /**
+     * The word between two rows of a compact group — "and" or "or" — so the logic reads down the
+     * list rather than only from the group's legend. A click switches the group's logic. It is a
+     * pointer shortcut kept out of the Tab order: the legend's select is the same control, reached
+     * once per group rather than once per row. A restricted root shows the word without the switch.
+     * @param {any} group Group the rows belong to.
+     * @param {boolean} root Whether it is the root group.
+     * @returns {HTMLElement}
+     */
+    _connector(group: any, root: boolean): HTMLElement;
+    /**
+     * Rewrites a group's connectors after its logic changed through the legend's select, which is
+     * not redrawn — the reader's focus is on it.
+     * @param {any} group
+     * @returns {void}
+     */
+    _syncConnectors(group: any): void;
     /** @param {any} node @returns {HTMLElement} */
     _renderCondition(node: any): HTMLElement;
     /** @param {any} node @param {FilterField|null} field @param {any} operator @returns {HTMLElement} */
     _renderValue(node: any, field: FilterField | null, operator: any): HTMLElement;
+    /**
+     * The editor for a relative date span (`withinLast`, `withinNext`): a whole-number amount and a
+     * unit select. Both controls write the pair `[amount, unit]`; a value that is not such a pair —
+     * two dates saved by an older editor, say — shows as an empty amount in days.
+     * @param {any} node Condition.
+     * @param {FilterField} field Date field.
+     * @returns {HTMLElement}
+     */
+    _relativeDateEditor(node: any, field: FilterField): HTMLElement;
     /**
      * Owns a themed picker and defers mutation until Select finishes its selection event.
      * @param {Array<{value:unknown,label:string}>} items Choices.
@@ -307,6 +344,16 @@ export declare class Filter extends Component<FilterOptions> {
         value: unknown;
         label: string;
     }>, value: unknown, label: string, nodeId: string, part: string, changed: (value: unknown) => void): HTMLElement;
+    /**
+     * Owns a themed multi-value picker for a many-valued operator on a field with static choices:
+     * the chosen values as removable tags, the rest in a searchable list. It writes the value without
+     * redrawing the editor, so the list stays open while the reader picks several.
+     * @param {FilterField} field Field with `choices`.
+     * @param {any} node Condition.
+     * @param {FilterValueMessages} messages Resolved value-builder text.
+     * @returns {HTMLElement} Picker root.
+     */
+    _tagPicker(field: FilterField, node: any, messages: FilterValueMessages): HTMLElement;
     /** @param {Event} event @returns {void} */
     _handleChange(event: Event): void;
     /** @param {Event} event @returns {void} */
@@ -371,6 +418,83 @@ export declare class Filter extends Component<FilterOptions> {
      */
     _message(key: string, fallback: string, ...args: unknown[]): string;
 }
+/**
+ * The word a compact row's connector shows for a group's logic, and the name it is read by. The
+ * name starts with the visible word (WCAG 2.5.3, label in name) and says what a click does.
+ * @param {'and'|'or'} logic Group logic.
+ * @param {(key: string, fallback: string, ...args: unknown[]) => string} [message] Message
+ *   resolver; omitted uses the built-in English text.
+ * @returns {{word: string, name: string}}
+ */
+export declare function filterConnectorText(logic: 'and' | 'or', message?: (key: string, fallback: string, ...args: unknown[]) => string): {
+    word: string;
+    name: string;
+};
+/**
+ * The logic a group's connector switches it to: the other one, or null when there is no such
+ * group or it is the root and `rootLogic` restricts it. The group's select offers the same two
+ * values, so the connector and the select always name one state.
+ * @param {FilterAst} value Expression.
+ * @param {string} groupId Group to switch.
+ * @param {'and'|'or'|null} [rootLogic=null] Root restriction, as the `rootLogic` option.
+ * @returns {'and'|'or'|null}
+ */
+export declare function nextFilterGroupLogic(value: FilterAst, groupId: string, rootLogic?: 'and' | 'or' | null): 'and' | 'or' | null;
+/**
+ * Builds the value of a relative date condition from what its two controls hold: the pair
+ * `[amount, unit]`. An empty or non-numeric amount is kept as null — the condition is then
+ * incomplete rather than silently zero — and an unknown unit falls back to days.
+ * @param {unknown} amount Amount control value.
+ * @param {unknown} unit Unit control value.
+ * @returns {[number|null, 'days'|'weeks'|'months']}
+ */
+export declare function relativeDateValue(amount: unknown, unit: unknown): [number | null, 'days' | 'weeks' | 'months'];
+/**
+ * Reads a stored relative date value for display. Anything that is not `[amount, unit]` — null,
+ * or two dates written by the date-pair editor these operators used to get — reads as an empty
+ * amount in days.
+ * @param {unknown} value Stored condition value.
+ * @returns {{amount: number|null, unit: 'days'|'weeks'|'months'}}
+ */
+export declare function readRelativeDateValue(value: unknown): {
+    amount: number | null;
+    unit: 'days' | 'weeks' | 'months';
+};
+/**
+ * Why a relative date value is unusable, or null when it is a positive whole number of a known
+ * unit: `[7, 'days']`, `[2, 'weeks']`, `[3, 'months']`.
+ * @param {unknown} value Condition value.
+ * @returns {'shape'|'amount'|'unit'|null}
+ */
+export declare function relativeDateValueError(value: unknown): 'shape' | 'amount' | 'unit' | null;
+/**
+ * Static choices as `TagPicker` items: the raw value — a number stays a number — the label, and
+ * the icon as given, a name or a node (the picker copies a node).
+ * @param {FilterField['choices']} choices
+ * @returns {Array<{value: string|number|boolean, label: string, icon?: Node|string, color?: string}>}
+ */
+export declare function filterTagItems(choices: FilterField['choices']): Array<{
+    value: string | number | boolean;
+    label: string;
+    icon?: Node | string;
+    color?: string;
+}>;
+/**
+ * The value a `TagPicker` change writes into a many-valued condition: a JSON-safe copy of the
+ * chosen raw values, in the order chosen.
+ * @param {unknown} values Picker values.
+ * @returns {import('./filter-model.js').FilterJson}
+ */
+export declare function filterTagValue(values: unknown): import('./filter-model.js').FilterJson;
+/**
+ * A host's `msg` option with one more message: added as a plain key and to every locale table,
+ * since a locale entry is looked up first and would otherwise win.
+ * @param {Record<string, any>|null|undefined} msg Host messages, flat or by locale.
+ * @param {string} key Message key.
+ * @param {string} value Message text.
+ * @returns {Record<string, any>}
+ */
+export declare function withFilterMessage(msg: Record<string, any> | null | undefined, key: string, value: string): Record<string, any>;
 /** @event Filter#change @type {CustomEvent<Record<string,unknown>>} */
 /** @event Filter#apply @type {CustomEvent<{value:FilterAst}>} */
 /** @event Filter#invalid @type {CustomEvent<Record<string,unknown>>} */

package/dist/types/components/filter-panel/filter-panel.d.ts

@@ -107,6 +107,14 @@ export type FilterPanelOptions = {
      * lower bound takes the start of its day and its upper bound the end, so a one-day range matches.
      */
     serialize?: FilterPanelSerialize;
+    /**
+     * IANA zone the calendar days are counted in, such as the
+     * ZeyOS instance's `Europe/Vienna`. A day serializes as the first (or last) instant of that day
+     * in this zone, and an incoming instant shows as the day it falls on there — the same rule
+     * `zeyosForm()` and `zeyosTable()` apply to date-only fields. Null uses the runtime's own zone.
+     * An unknown zone throws a `RangeError`.
+     */
+    timeZone?: string | null;
     /**
      * Text shown when `fields` is empty; null resolves
      * `filterPanel.empty`.
@@ -175,6 +183,11 @@ export type FilterPanelOptions = {
  *   applies every committed edit.
  * @property {FilterPanelSerialize} [serialize='seconds'] How a date leaves the component. A range's
  *   lower bound takes the start of its day and its upper bound the end, so a one-day range matches.
+ * @property {string|null} [timeZone=null] IANA zone the calendar days are counted in, such as the
+ *   ZeyOS instance's `Europe/Vienna`. A day serializes as the first (or last) instant of that day
+ *   in this zone, and an incoming instant shows as the day it falls on there — the same rule
+ *   `zeyosForm()` and `zeyosTable()` apply to date-only fields. Null uses the runtime's own zone.
+ *   An unknown zone throws a `RangeError`.
  * @property {string|null} [emptyText=null] Text shown when `fields` is empty; null resolves
  *   `filterPanel.empty`.
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
@@ -211,6 +224,7 @@ export declare class FilterPanel extends Component<FilterPanelOptions> {
     _draft: {};
     _applied: {};
     _appliedDraft: string;
+    _timeZone: string;
     _fields: {
         key: string;
         field: FilterPanelField;
@@ -402,23 +416,29 @@ export declare function isActiveValue(value: unknown): boolean;
 export declare function pruneValue(value: Record<string, unknown>): Record<string, unknown>;
 /**
  * Converts anything a calendar day can arrive as — a `YYYY-MM-DD` string, an ISO timestamp, a
- * `Date`, Unix seconds or milliseconds — into the local calendar day a native date input holds.
+ * `Date`, Unix seconds or milliseconds — into the calendar day a native date input holds.
  * Numbers below 1e11 are read as seconds, which is the boundary between the two epochs in use.
+ * An instant — Unix seconds or milliseconds, an ISO timestamp — names the day it falls on in
+ * `timeZone`. A `Date` is read as a picked day and keeps its local calendar day, matching
+ * `calendarDayToUnixSeconds()` in the ZeyOS binding.
  * @param {unknown} value Candidate day.
+ * @param {string|null} [timeZone=null] IANA zone instants are read in; null for the runtime's own.
  * @returns {string} `YYYY-MM-DD`, or an empty string when there is no day in it.
  */
-export declare function toDateInput(value: unknown): string;
+export declare function toDateInput(value: unknown, timeZone?: string | null): string;
 /**
  * Serializes one calendar day at one edge of a range. The `from` edge takes the first instant of
- * its local day and the `to` edge the last, so a range whose ends name the same day still matches
- * everything recorded on it.
+ * its day and the `to` edge the last, so a range whose ends name the same day still matches
+ * everything recorded on it. The day is counted in `timeZone`: with `Europe/Vienna`, 2026-03-10
+ * starts at 23:00 UTC on the 9th whatever zone the browser is in.
  * @param {unknown} day Calendar day in any form `toDateInput()` accepts.
  * @param {FilterPanelEdge} edge Which end of the range the day is.
  * @param {FilterPanelSerialize} [serialize='seconds'] Output format, or a function receiving the
  *   edge instant as a `Date`.
+ * @param {string|null} [timeZone=null] IANA zone the day is counted in; null for the runtime's own.
  * @returns {unknown} The serialized day, or null when there is no day.
  */
-export declare function serializeDate(day: unknown, edge: FilterPanelEdge, serialize?: FilterPanelSerialize): unknown;
+export declare function serializeDate(day: unknown, edge: FilterPanelEdge, serialize?: FilterPanelSerialize, timeZone?: string | null): unknown;
 /**
  * Normalizes declared select options. `{value, label}`, `{ID, name}`, and bare primitives all
  * arrive from one instance or another.
@@ -435,15 +455,24 @@ export declare function normalizeOptions(options: unknown): Array<{
  * Running it on a draft returns the same draft, so it is safe on either shape.
  * @param {Record<string, unknown>|null|undefined} value Incoming values keyed by field.
  * @param {Record<string, FilterPanelField>} fields Field metadata.
+ * @param {string|null} [timeZone=null] IANA zone incoming instants are read in.
  * @returns {Record<string, unknown>}
  */
-export declare function toDraft(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>): Record<string, unknown>;
+export declare function toDraft(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>, timeZone?: string | null): Record<string, unknown>;
 /**
  * Turns values into the query object a list endpoint is sent: only the constraints that are set,
  * dates serialized at the right edge, unknown field types excluded.
  * @param {Record<string, unknown>|null|undefined} value Values keyed by field, raw or drafted.
  * @param {Record<string, FilterPanelField>} fields Field metadata.
  * @param {FilterPanelSerialize} [serialize='seconds'] Date output format.
+ * @param {string|null} [timeZone=null] IANA zone calendar days are counted in.
  * @returns {Record<string, unknown>}
  */
-export declare function serializeFilterValue(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>, serialize?: FilterPanelSerialize): Record<string, unknown>;
+export declare function serializeFilterValue(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>, serialize?: FilterPanelSerialize, timeZone?: string | null): Record<string, unknown>;
+/**
+ * Validates the `timeZone` option.
+ * @param {unknown} timeZone IANA zone name; nullish or empty means the runtime's own zone.
+ * @returns {string|null} Canonical zone name, or null for the runtime's own zone.
+ * @throws {RangeError} When the runtime does not know the zone.
+ */
+export declare function normalizePanelTimeZone(timeZone: unknown): string | null;

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

@@ -397,6 +397,8 @@ export type LauncherPageEntry = {
  */
 export declare class Launcher extends Component<LauncherOptions> {
     _createdRoot: boolean;
+    /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} Entry on the overlay stack while open. */
+    _overlay: import('../../core/overlay-stack.js').OverlayHandle | null;
     _original: {
         attributes: string[][];
         children: ChildNode[];
@@ -468,6 +470,12 @@ export declare class Launcher extends Component<LauncherOptions> {
     setCurrent(id: string | number | null): this;
     /** Replaces the root's asynchronous sources and aborts work from the old set; on a page they load once the root is back. @param {LauncherSource[]} sources @returns {this} */
     setSources(sources: LauncherSource[]): this;
+    /**
+     * Takes the launcher off the overlay stack. Safe to call repeatedly.
+     * @returns {void}
+     * @private
+     */
+    private _releaseOverlay;
     /** Aborts sources and removes the owned dialog. @returns {void} */
     destroy(): void;
     /**

package/dist/types/components/list-toolbar/list-toolbar.d.ts

@@ -341,8 +341,10 @@ export declare class ListToolbar extends Component<ListToolbarOptions> {
      */
     focusSearch(): this;
     /**
-     * Optional sugar for a `TableView` or `CardView`: it wires the shape switch to the view and
-     * mounts the view's field chooser into this bar.
+     * Optional sugar for a `TableView`, `CardView`, or `KanbanView`: it wires the shape switch to
+     * the view and mounts the view's field chooser into this bar — through the view's public
+     * `mountFieldControls()` when it has one, which every `RecordView` does. A `TableView` with the
+     * default `fieldControls: true` contributes its Table's column chooser.
      *
      * Nothing is imported and nothing is required — every capability is feature-detected, so a view
      * that offers none of them still works and still gets `viewchange`, and the host swaps the view
@@ -410,7 +412,8 @@ export declare class ListToolbar extends Component<ListToolbarOptions> {
      */
     _mountFieldControls(view: Record<string, any>): void;
     /**
-     * Finds a view's field chooser without importing the view, newest accessor first.
+     * Finds a view's field chooser without importing the view: its public `getFieldControls()`,
+     * else — for an object that only looks like a record view — the shared chooser's class.
      * @param {Record<string, any>} view Bound view.
      * @returns {Element|null}
      */
@@ -470,6 +473,7 @@ export type AdoptedElement = {
     element: Element;
     parent: Node | null;
     next: Node | null;
+    viaView?: boolean;
 };
 export type RecordViewCapabilities = {
     /**
@@ -489,7 +493,8 @@ export type RecordViewCapabilities = {
      */
     events: boolean;
     /**
-     * Whether the object offers its field chooser through a method.
+     * Whether the object offers its field chooser through a method
+     * (`getFieldControls()`, which every `RecordView` has).
      */
     fieldControls: boolean;
 };
@@ -521,14 +526,18 @@ export type RecordViewCapabilities = {
  * @property {boolean} pressed Current pressed state.
  * @property {((event: MouseEvent) => void)|null} onclick Descriptor callback.
  */
-/** @typedef {{element: Element, parent: Node|null, next: Node|null}} AdoptedElement */
+/**
+ * @typedef {{element: Element, parent: Node|null, next: Node|null, viaView?: boolean}} AdoptedElement
+ * `viaView` marks a field chooser the bound view moved here itself and takes back on `unbind()`.
+ */
 /**
  * @typedef {Object} RecordViewCapabilities
  * @property {boolean} isRecordView Whether the object publishes the record-view state surface.
  * @property {string|null} setShape Method that changes the view shape, if any.
  * @property {string|null} getShape Method that reads the view shape, if any.
  * @property {boolean} events Whether the object emits component events.
- * @property {boolean} fieldControls Whether the object offers its field chooser through a method.
+ * @property {boolean} fieldControls Whether the object offers its field chooser through a method
+ *   (`getFieldControls()`, which every `RecordView` has).
  */
 /**
  * Describes what `bind()` can wire on an object, by feature rather than by class.

package/dist/types/components/menu-button/menu-button.d.ts

@@ -110,6 +110,12 @@ export declare class MenuButton extends Component<MenuButtonOptions> {
      * @returns {this}
      */
     close(): this;
+    /**
+     * Opens the menu when it is closed, and closes it when it is open. Opening this way moves no
+     * focus; `focusFirst()` opens with focus on the first item.
+     * @returns {this}
+     */
+    toggle(): this;
     /**
      * Reports whether the menu is open.
      * @returns {boolean}