@zeyos/zx 4.4.0 → 5.2.0

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

@@ -1,9 +1,15 @@
 import { Component } from '../../core/component.js';
 export type FieldOptions = {
     /**
-     * Control ID and logical field identifier.
+     * DOM id of the control. Generated when omitted; a Fieldset
+     * derives it from its `idPrefix` and the field key, so a key never becomes a DOM id by itself.
      */
     id?: string | null;
+    /**
+     * Field name: the `name` of a native control and the key the
+     * field is filed under. A Fieldset sets it to the field key; a standalone field falls back to `id`.
+     */
+    name?: string | null;
     /**
      * Registered field type.
      */
@@ -32,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.
      */
@@ -84,10 +96,21 @@ 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.
      */
     destroy?: () => void;
+    /**
+     * 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
+     * wrapper that cannot be labelled hands them to the first unnamed form control inside it.
+     */
+    labelTarget?: Element;
 };
 export type FieldAdapterFactory = (field: Field, options: Readonly<FieldOptions>) => FieldAdapter;
 export type NumericCoercion = {
@@ -96,7 +119,10 @@ export type NumericCoercion = {
 };
 /**
  * @typedef {Object} FieldOptions
- * @property {string|null} [id=null] Control ID and logical field identifier.
+ * @property {string|null} [id=null] DOM id of the control. Generated when omitted; a Fieldset
+ *   derives it from its `idPrefix` and the field key, so a key never becomes a DOM id by itself.
+ * @property {string|null} [name=null] Field name: the `name` of a native control and the key the
+ *   field is filed under. A Fieldset sets it to the field key; a standalone field falls back to `id`.
  * @property {string} [type='text'] Registered field type.
  * @property {string} [label=''] Visible label.
  * @property {string} [description=''] Supporting description.
@@ -104,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.
@@ -118,13 +147,19 @@ 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
+ *   wrapper that cannot be labelled hands them to the first unnamed form control inside it.
  */
 /** @typedef {(field: Field, options: Readonly<FieldOptions>) => FieldAdapter} FieldAdapterFactory */
 /** @typedef {{valid: boolean, value: number|string}} NumericCoercion */
 /**
  * One labelled form control backed by a registered adapter.
  * @fires Field#change
+ * @fires Field#input
  * @fires Field#invalid
  * @extends {Component<FieldOptions>}
  */
@@ -133,8 +168,12 @@ export declare class Field extends Component<FieldOptions> {
     _ownedComponents: Set<any>;
     _ownedNodes: any[];
     _rootAttributes: Map<string, string>;
+    /** @type {string} The control's DOM id: `options.id`, or a generated one. */
     controlId: string;
+    /** @type {string} The field name (`options.name`, else `options.id`), '' when there is none. */
+    name: string;
     adapter: FieldAdapter;
+    _labelled: Element;
     _baseDescribedBy: string;
     _descriptionId: string;
     _highlightId: string;
@@ -191,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.
@@ -238,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

@@ -13,6 +13,12 @@ export type FieldsetOptions = {
      * Initial fields.
      */
     fields?: Record<string, FieldOptions | Field | Element | Component>;
+    /**
+     * Prefix of the DOM ids generated for the fields, as
+     * `<idPrefix>-<key>`. Null generates one per instance, so the same fieldset mounted twice
+     * never repeats an id and a field key never collides with an element id elsewhere on the page.
+     */
+    idPrefix?: string | null;
 };
 export type FieldOptions = import('../field/field.js').FieldOptions;
 /**
@@ -20,6 +26,9 @@ export type FieldOptions = import('../field/field.js').FieldOptions;
  * @property {string} [title=''] Legend text.
  * @property {1|2|3} [columns=1] Grid column count.
  * @property {Record<string, FieldOptions|Field|Element|Component>} [fields={}] Initial fields.
+ * @property {string|null} [idPrefix=null] Prefix of the DOM ids generated for the fields, as
+ *   `<idPrefix>-<key>`. Null generates one per instance, so the same fieldset mounted twice
+ *   never repeats an id and a field key never collides with an element id elsewhere on the page.
  */
 /** @typedef {import('../field/field.js').FieldOptions} FieldOptions */
 /**
@@ -32,6 +41,7 @@ export declare class Fieldset extends Component<FieldsetOptions> {
     _origins: Map<any, any>;
     _fieldIdAttributes: Map<any, any>;
     _ownedNodes: any[];
+    _idPrefix: string;
     _columnAttribute: string;
     _grid: HTMLElement;
     static cssName: string;
@@ -40,7 +50,16 @@ export declare class Fieldset extends Component<FieldsetOptions> {
     /** @returns {HTMLElement} */
     render(): HTMLElement;
     /**
-     * Adds a field from options, an existing field, an element, or a component.
+     * 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}
@@ -118,6 +137,12 @@ export declare class Fieldset extends Component<FieldsetOptions> {
      * @returns {this}
      */
     clearHighlights(): this;
+    /**
+     * The DOM id generated for a field key: unique per instance unless `idPrefix` was given.
+     * @param {string} key Field key.
+     * @returns {string}
+     */
+    _controlId(key: string): string;
     /** @param {Field} field @returns {void} */
     _releaseField(field: Field): void;
     /** @returns {void} */

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

@@ -20,15 +20,22 @@ export type FileItemOptions = {
      */
     size?: number | string | null;
     /**
-     * MIME type.
+     * MIME type. Shown as a readable type ("PDF", "Image"), never as
+     * the raw string, and used to pick the icon.
      */
     mime?: string;
+    /**
+     * Type shown beside the size; null derives it from the
+     * MIME type (or the name's extension when the MIME type is unfamiliar), an empty string hides it.
+     */
+    typeLabel?: string | null;
     /**
      * Optional supporting text before generated metadata.
      */
     subtitle?: EntityRefContent;
     /**
-     * File icon name, node, component, or lazy renderer.
+     * File icon name, node, component, or lazy renderer. The
+     * generic `'file'` glyph gives way to one for the MIME type when the active icon set has it.
      */
     icon?: EntityRefIcon;
     /**
@@ -60,9 +67,9 @@ export type FileItemOptions = {
      */
     indeterminate?: boolean;
     /**
-     * File-identity presentation size.
+     * Size of the file's icon and name.
      */
-    density?: 'sm' | 'md' | 'lg';
+    identitySize?: 'sm' | 'md' | 'lg';
     /**
      * Whether long identity text may wrap.
      */
@@ -112,6 +119,10 @@ export type FileItemState = {
      * MIME type.
      */
     mime: string;
+    /**
+     * Explicit type label, or null for the one derived from `mime`.
+     */
+    typeLabel: string | null;
     /**
      * Supporting content.
      */
@@ -149,9 +160,9 @@ export type FileItemState = {
      */
     indeterminate: boolean;
     /**
-     * Identity size.
+     * Size of the file's icon and name.
      */
-    density: 'sm' | 'md' | 'lg';
+    identitySize: 'sm' | 'md' | 'lg';
     /**
      * Wrapping state.
      */
@@ -230,5 +241,22 @@ export declare class FileItem extends Component<FileItemOptions> {
  * @returns {FileItemState}
  */
 export declare function normalizeFileItem(values?: Partial<FileItemOptions> | null | undefined): FileItemState;
+/**
+ * A readable name for a file's type: "PDF", "CSV", "Image", "Spreadsheet". An unfamiliar MIME type
+ * falls back to the name's extension in capitals ("EXE"); without a MIME type, or with neither,
+ * the result is empty — a raw MIME string is never shown.
+ * @param {string} mime MIME type, possibly with parameters (`text/csv; charset=utf-8`).
+ * @param {string} [name=''] File name, consulted only when the MIME type is unfamiliar.
+ * @returns {string}
+ */
+export declare function fileTypeLabel(mime: string, name?: string): string;
+/**
+ * The icon name for a MIME type: a type-specific glyph when the active icon set can draw one,
+ * `'file'` otherwise. Font Awesome resolves every name it is given; the bundled inline set only
+ * those it carries or that `registerIcons()` added, so a missing glyph never shows a placeholder.
+ * @param {string} mime MIME type, possibly with parameters.
+ * @returns {string}
+ */
+export declare function fileTypeIcon(mime: string): string;
 /** Fired before a native file link continues. @event FileItem#activate @type {CustomEvent<{id: unknown, file: Readonly<FileItemState>, href: string, event: MouseEvent}>} */
 /** Fired before a descriptor action callback runs. @event FileItem#action @type {CustomEvent<{id: string, fileId: unknown, action: object, file: Readonly<FileItemState>, event: MouseEvent}>} */

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>>} */