@zeyos/zx 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 4.1.0 — 2026-08-25
+
+### Added
+
+- **`AppIcon`.** A reusable application-identity surface with safe semantic colours, badges,
+  accessible labelled and decorative modes, and an optional CSS-only translucent glass material.
+  The ZeyOS adapter supplies presets for all 29 current applications while keeping glyph loading
+  and routing application-owned.
+- **`Filter`.** A backend-neutral visual expression builder with a versioned JSON-safe AST,
+  nested AND/OR groups, typed operators and value editors, abortable asynchronous choices,
+  structural and semantic validation, defensive limits, deterministic keyboard focus, and
+  valid-only Apply events. Query compilation, saved views, and URL state remain adapter concerns.
+- **Richer entity and tag selection.** `Select.entity()` supports optional recent items and an
+  application-owned create command; `TagPicker` now renders native item icons and semantic colours
+  without overriding a custom renderer.
+
+### Changed
+
+- **Transaction grids are faster to operate.** `Grid.BillingItems()` and `Table` now support
+  single-click typed editing, opt-in double-click compatibility, same-parent row reordering by
+  drag or keyboard, hierarchy-safe branch moves, and accessible column visibility controls.
+- **ZeyOS identity is consistent across workflows.** Launcher application tiles use the new
+  AppIcons, while Launcher recents and entity-select results use module/entity identities and
+  colours rather than generic placeholders.
+- **The documentation shell is easier to navigate.** Global search is centred in every header and
+  reports full breadcrumb paths; component groups are alphabetized, application-shell primitives
+  are collected under Layout, narrow API tables remain locally scrollable, and public navigation
+  and footer links are reduced to their canonical destinations.
+- **Theme Studio now applies complete recipes.** Presets change typography, tint, radius, density,
+  control sizing, and glass strength in addition to colour; the house preset is named `ZeyOS`.
+
+### Fixed
+
+- Select preset chevrons retain their alignment across theme recipes and enhanced
+  `Select.entity()` targets restore their exact original DOM when destroyed.
+- Floating messages default to a content-sized upper-right glass surface instead of stretching
+  with the document, with opaque and reduced-transparency fallbacks.
+- Filter mutations preserve keyboard focus and accessible announcements; asynchronous editors
+  expose busy state and abort stale work.
+- Row editing no longer targets hidden columns or hijacks buttons and links rendered inside cells;
+  column toggles retain focus and row drags do not export record identifiers as plain text.
+- Application and tag colour overrides reject CSS image and URL values before reaching public
+  custom properties.
+
 ## 4.0.0 — 2026-08-24
 
 ### Added

package/DESIGN-SYSTEM.md

@@ -33,16 +33,72 @@ and navigation remain application-owned.
 | Forms and fieldsets | Covered, including component-backed field adapters | Use for record editors; keep validation/business rules application-owned. |
 | Dialogs, sheets, dropdowns, context menus, tooltips, messages | Covered | Consolidate duplicate menu behavior before building account/launcher surfaces. |
 | Tabs, panels, toolbar, breadcrumbs, stepper, split view, dock | Covered | Compose layouts; do not let navigation components own routes. |
-| Sorting, selection, filtering, pagination, trees/finder | Covered | Suitable for generic data screens. |
-| Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes typed editable currency/unit columns and flat hierarchy over `Table`. Tax, subtotal, posting, rounding, and persistence stay domain code. |
+| Sorting, selection, dynamic/local filtering, pagination, trees/finder | Covered | `Filter` authors typed nested expressions; `DataFilter` executes simple local predicates. Backend query compilation stays in adapters. |
+| Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes single-click typed currency/unit editors, flat hierarchy, same-parent row movement, and column visibility over `Table`. Tax, subtotal, posting, rounding, and persistence stay domain code. |
 | Global launcher/search | Covered | `Launcher` combines an application grid, current/pinned state, recent records, and abortable grouped sources. The optional ZeyOS adapter maps the complete 29-app shell catalogue while the host retains permissions, icons, and routing. |
 | Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. The host supplies permitted actions and owns preferences, authentication, and logout. |
 | Persistent app rail / side navigation | Covered | One route-agnostic `AppSidebar` owns expanded, minimized, and horizontal presentations. Only expanded vertical branches render inline; every rail presentation uses flyouts. |
 | Charts and analytical summaries | Covered through an adapter | `Chart` is engine-neutral and accessible; `ChartJsAdapter` accepts an injected Chart.js 4 engine. Chart.js is documentation/test tooling only. |
-| Local product/module icons | Partial | Use bundled icons or registered local assets; do not require the optional remote Font Awesome kit. |
+| Local product/module icons | Covered | `AppIcon` is generic; `zeyosAppIcon()` maps every current ZeyOS module/entity identity and accepts an offline glyph override. The optional remote Font Awesome kit is never loaded automatically. |
 | Domain entity selectors/cards/links | Covered at generic presentation level | `Card` provides media, native primary links, secondary actions, and metadata; applications own entity routing and policy. |
 | Persistent notification/activity center | Missing, lower priority | `Message` covers ephemeral feedback, not read/unread activity history. |
 
+## Current ZeyOS delta audit (25 August 2026)
+
+This is a source audit, not a visual inventory. The comparison uses the current ZeyOS DOM/UI
+implementation as evidence: its generic control catalogue is concentrated in
+[`4-ui.orig.js`](../zeyos/ext/global.orig/4-ui.orig.js), configurable index-column management in
+[`4-pg.orig.js`](../zeyos/ext/global.orig/4-pg.orig.js#L3464), and the multi-view scheduling surface
+in [`calendar.orig.js`](../zeyos/ext/mod/calendar.orig.js#L61). Capabilities already represented by
+a Zx component or a documented composition are not counted as gaps.
+
+### Already closed by Zx core
+
+| ZeyOS behavior | Source evidence | Xenon/Zx coverage |
+| --- | --- | --- |
+| Dynamic search/filter authoring and saved filter controls | [`UI.newSearch`](../zeyos/ext/global.orig/4-ui.orig.js#L3378) and [`UI.newContainerFilters`](../zeyos/ext/global.orig/4-ui.orig.js#L7723) | `Filter` supplies a typed/versioned AST editor; `DataFilter` remains the lightweight local-row helper. A compiler and persistence service are intentionally not core. |
+| Editable transaction rows and row movement | [`_newTblAddColEdit`](../zeyos/ext/global.orig/4-ui.orig.js#L5613) and [`newTblItems`](../zeyos/ext/global.orig/4-ui.orig.js#L6070) | `Table`/`Grid.BillingItems()` cover typed editing, currencies/units, hierarchy, single-click entry, same-parent drag/keyboard reorder, and show/hide columns. |
+| Entity selection, priority, status, and permission choices | [`newSelEntity`](../zeyos/ext/global.orig/4-ui.orig.js#L3296), [`newSelPriority`](../zeyos/ext/global.orig/4-ui.orig.js#L3101), and the surrounding Select family | `Select.entity()`, `.priority()`, `.status()`, and `.permission()` cover the interaction contract; the ZeyOS adapter owns schemas and localized catalogues. |
+| Application launcher and module/entity identity | [`newExpLst`](../zeyos/ext/global.orig/4-ui.orig.js#L4355) and entity/module item builders through line 4457 | `Launcher`, `AppIcon`, and the optional ZeyOS adapter cover the full app catalogue, current/pinned state, recent records, grouped abortable search, forks/weblets, and injected routing. |
+| Expanded/minimized/horizontal app navigation | Current shell navigation plus the same module identity catalogue | One public `AppSidebar` owns all presentations. The rail renderer is an internal presenter, not a second component; only expanded vertical branches render inline and rail branches use anchored flyouts. |
+| Toasts, loading, cards, dialogs, forms, grids, charts, and layout primitives | Multiple `newContainer*`, input, table, and progress families in `4-ui.orig.js` | Covered by existing Zx components and documented composition; these are not delta items merely because the legacy factory names differ. |
+
+### Recommended additions to Zx core
+
+| Priority | Missing reusable contract | Evidence and proposed boundary |
+| --- | --- | --- |
+| P0 | **EntityRef** | ZeyOS has a large family of linked/static entity presentations with subtitle, owner/group/assignee context, fork, and record actions: [`newLinkEntity*`](../zeyos/ext/global.orig/4-ui.orig.js#L225) and [`newEntityStatic`/`newEntity*`](../zeyos/ext/global.orig/4-ui.orig.js#L8262). A generic `EntityRef` should own icon/title/subtitle/metadata/link/action semantics; ZeyOS routing, permissions, and context menus remain injected. `Card` is too large for dense table/feed rows. |
+| P0 | **FileItem / FileList** | Existing-file, temporary-file, waiting/progress, MIME, size, and download rows recur in [`newFile`, `newFileTemp`, and `newFileWait`](../zeyos/ext/global.orig/4-ui.orig.js#L8158). `FieldUpload` owns selection/upload but not durable file presentation. Core should render file identity/state/actions; transport, authorization, preview, and download URLs stay with the host. |
+| P0 | **ActivityList / ActivityItem** | [`newFeed`](../zeyos/ext/global.orig/4-ui.orig.js#L8704) combines chronological records, comments, attachments, likes, and incremental updates. Core should own an accessible chronological list, grouping, loading/empty state, and action slots. Posting, reactions, channels, permissions, and persistence remain application code. |
+| P1 | **Scheduler** | The current calendar implements agenda/day/week/month/year views, timed and spanning items, keyboard/routing affordances, and dense collision layout in [`calendar.orig.js`](../zeyos/ext/mod/calendar.orig.js#L61). A generic scheduler is a real core gap, but should be a separate workstream with interval-layout and accessibility invariants; recurrence, DAV, permissions, and routes are adapters/application logic. |
+| P1 | **FacetList** | Counted activity/status/tag/entity side filters appear in [`newNavActivityStatus`](../zeyos/ext/global.orig/4-ui.orig.js#L3967), `newNavTag`, and `newNavEntity`. `Filter` is an expression author, not a compact persistent facet navigator. Core should own selection/count/collapse/loading behavior; query mapping stays injected. |
+| P1 | **EditorHost** | ZeyOS uses plain/Markdown/contenteditable/iframe editors through [`newEditor`](../zeyos/ext/global.orig/4-ui.orig.js#L1607) and `newFrameEditor`. Like `Chart`, core should provide labels, toolbar/action slots, value/lifecycle, dirty/read-only/error states, and an injected engine adapter. Sanitization and document/media policy must not be implicit core behavior. |
+| P1 | **ColorPicker** | The reusable swatch picker is [`newCl`](../zeyos/ext/global.orig/4-ui.orig.js#L3753). A dependency-free accessible swatch/custom-color picker belongs in core and would also serve the Theme Studio. |
+| P2 | **Metric / Summary** | [`newSummary`](../zeyos/ext/global.orig/4-ui.orig.js#L7312) repeatedly formats counts, money, timing, size, stock, and relative values. These can currently be composed from Card and format helpers, but a small semantic Metric/DescriptionList pair would remove repeated markup without importing business formulas. |
+| P2 | **RecordPreview** | Typed preview builders for appointments, contacts, links, messages, tasks, and tickets start at [`newPreviewForm`](../zeyos/ext/global.orig/4-ui.orig.js#L9589). Core should offer a generic preview anatomy or engine-neutral preview host, not one component per ZeyOS entity. |
+| P2 | **Shortcut / Kbd** | Launcher and menus expose shortcuts but Zx has no reusable semantic `<kbd>` treatment. A tiny factory is justified once shortcuts appear outside those components. |
+
+### Adapter work, not new core components
+
+- A **ZeyOS Filter compiler** mapping allowlisted AST field/operator IDs to the server's plural
+  `filters` query shape, plus a parser for stored legacy filter state. Compilation must use bound/
+  structured values and never accept raw SQL or URL fragments.
+- A shared **ZeyOS field/status/priority catalogue** built from runtime schemas and localization,
+  feeding `Field`, `Filter`, `Select.status()`, and `Select.priority()` without hard-coding
+  entity-specific policy in core.
+- **EntityRef/FileItem/ActivityList adapters** that resolve routes, icons, permissions, server
+  payloads, and action menus while leaving their visual/interaction contracts reusable.
+- Optional persistence connectors for column visibility/order, sidebar state, saved filters, recent
+  items, and theme preferences. Core should expose serializable state and events only.
+
+### Deliberately application-owned
+
+Routing/history, authentication/session/logout, authorization, server transport/caching, saved-view
+storage, audit policy, transaction tax/discount/subtotal/posting formulas, optimistic writes/undo,
+calendar recurrence/DAV synchronization, rich-text sanitization, and activity actions are not
+design-system responsibilities. Moving them into Zx would reproduce ZeyOS application logic inside
+the library and make Xenon less reusable.
+
 ### Launcher contract
 
 The launcher searches applications, recent records, and grouped remote record types. The generic

package/dist/types/components/app-icon/app-icon.d.ts

@@ -0,0 +1,88 @@
+import { Component } from '../../core/component.js';
+export type AppIconOptions = {
+    /**
+     * Icon name, node, or lazy renderer.
+     */
+    icon?: string | Node | (() => string | Node) | null;
+    /**
+     * Identity colour; falls back to the accent colour.
+     */
+    color?: string | null;
+    /**
+     * Edge length in pixels or any CSS length.
+     */
+    size?: number | string;
+    /**
+     * Glyph size.
+     */
+    iconSize?: number | string;
+    /**
+     * Accessible image label; null makes the icon decorative.
+     */
+    label?: string | null;
+    /**
+     * Optional corner badge.
+     */
+    badge?: string | number | null;
+    /**
+     * Whether the icon represents the active application.
+     */
+    selected?: boolean;
+    /**
+     * CSS-first glass treatment.
+     */
+    glass?: false | 'subtle' | 'strong';
+    /**
+     * Additional class names.
+     */
+    class?: string | string[];
+};
+/**
+ * @typedef {Object} AppIconOptions
+ * @property {string|Node|(()=>string|Node)|null} [icon=null] Icon name, node, or lazy renderer.
+ * @property {string|null} [color=null] Identity colour; falls back to the accent colour.
+ * @property {number|string} [size=36] Edge length in pixels or any CSS length.
+ * @property {number|string} [iconSize='52%'] Glyph size.
+ * @property {string|null} [label=null] Accessible image label; null makes the icon decorative.
+ * @property {string|number|null} [badge=null] Optional corner badge.
+ * @property {boolean} [selected=false] Whether the icon represents the active application.
+ * @property {false|'subtle'|'strong'} [glass='subtle'] CSS-first glass treatment.
+ * @property {string|string[]} [class] Additional class names.
+ */
+/**
+ * Stable application-identity tile with progressive CSS glass treatment.
+ * @extends {Component<AppIconOptions>}
+ */
+export declare class AppIcon extends Component<AppIconOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _state: {
+        icon?: string | Node | (() => string | Node) | null;
+        color?: string | null;
+        size?: number | string;
+        iconSize?: number | string;
+        label?: string | null;
+        badge?: string | number | null;
+        selected?: boolean;
+        glass?: false | 'subtle' | 'strong';
+        class?: string | string[];
+    };
+    _appliedClasses: any[] | string[];
+    static cssName: string;
+    /** @type {Readonly<AppIconOptions>} */
+    static defaults: Readonly<AppIconOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Updates identity or presentation without replacing the root. @param {Partial<AppIconOptions>} values @returns {this} */
+    set(values?: Partial<AppIconOptions>): this;
+    /** Restores an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+}
+/**
+ * Creates an AppIcon element without retaining a component lifecycle handle.
+ * @param {AppIconOptions} [options={}] Icon options.
+ * @returns {HTMLElement}
+ */
+export declare function appIcon(options?: AppIconOptions): HTMLElement;

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

@@ -0,0 +1,87 @@
+export type FilterJson = null | boolean | number | string | FilterJson[] | {
+    [key: string]: FilterJson;
+};
+export type FilterCondition = {
+    kind: 'condition';
+    id: string;
+    field: string;
+    operator: string;
+    value: FilterJson;
+};
+export type FilterGroup = {
+    kind: 'group';
+    id: string;
+    logic: 'and' | 'or';
+    children: FilterNode[];
+};
+export type FilterNode = FilterCondition | FilterGroup;
+export type FilterAst = {
+    version: 1;
+    root: FilterGroup;
+};
+export type FilterOperator = {
+    id: string;
+    label: string;
+    arity: 'none' | 'single' | 'pair' | 'many';
+    types: string[];
+};
+export type FilterField = {
+    id: string;
+    label: string;
+    type: string;
+    operators?: string[];
+    defaultOperator?: string;
+};
+export type FilterValidationError = {
+    nodeId: string;
+    code: string;
+    message: string;
+};
+/** @typedef {null|boolean|number|string|FilterJson[]|{[key:string]: FilterJson}} FilterJson */
+/** @typedef {{kind:'condition', id:string, field:string, operator:string, value:FilterJson}} FilterCondition */
+/** @typedef {{kind:'group', id:string, logic:'and'|'or', children:FilterNode[]}} FilterGroup */
+/** @typedef {FilterCondition|FilterGroup} FilterNode */
+/** @typedef {{version:1, root:FilterGroup}} FilterAst */
+/** @typedef {{id:string, label:string, arity:'none'|'single'|'pair'|'many', types:string[]}} FilterOperator */
+/** @typedef {{id:string, label:string, type:string, operators?:string[], defaultOperator?:string}} FilterField */
+/** @typedef {{nodeId:string, code:string, message:string}} FilterValidationError */
+/** Core operators are application-neutral IDs; an adapter maps them to executable query syntax. */
+export declare const filterOperators: readonly FilterOperator[];
+/** @returns {FilterAst} */
+export declare function emptyFilterAst(): FilterAst;
+/** @param {Partial<FilterCondition>} [initial={}] @returns {FilterCondition} */
+export declare function filterCondition(initial?: Partial<FilterCondition>): FilterCondition;
+/**
+ * Returns a defensive JSON-safe copy suitable for a condition value.
+ * @param {unknown} value
+ * @returns {FilterJson}
+ */
+export declare function cloneFilterValue(value: unknown): FilterJson;
+/** @param {'and'|'or'} [logic='and'] @param {FilterNode[]} [children=[]] @returns {FilterGroup} */
+export declare function filterGroup(logic?: 'and' | 'or', children?: FilterNode[]): FilterGroup;
+/**
+ * Parses untrusted state into a defensive JSON-safe AST. It rejects structural corruption but
+ * deliberately keeps unknown field/operator IDs for semantic validation and migration UI.
+ * @param {unknown} value
+ * @param {{maxDepth?:number, maxConditions?:number}} [limits={}]
+ * @returns {FilterAst}
+ */
+export declare function parseFilterAst(value: unknown, limits?: {
+    maxDepth?: number;
+    maxConditions?: number;
+}): FilterAst;
+/** @param {FilterAst} value @returns {FilterAst} */
+export declare function cloneFilterAst(value: FilterAst): FilterAst;
+/** @param {FilterAst} value @returns {string} */
+export declare function stringifyFilterAst(value: FilterAst): string;
+/**
+ * Performs field/operator/arity validation without compiling or executing the expression.
+ * @param {FilterAst} ast
+ * @param {FilterField[]} fields
+ * @param {FilterOperator[]} [operators=filterOperators]
+ * @returns {{valid:boolean, errors:FilterValidationError[]}}
+ */
+export declare function validateFilterAst(ast: FilterAst, fields: FilterField[], operators?: FilterOperator[]): {
+    valid: boolean;
+    errors: FilterValidationError[];
+};

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

@@ -0,0 +1,331 @@
+import { Component } from '../../core/component.js';
+export type FilterAst = import('./filter-model.js').FilterAst;
+export type FilterField = {
+    /**
+     * Stable allowlisted field ID.
+     */
+    id: string;
+    /**
+     * Display label.
+     */
+    label: string;
+    /**
+     * Editor/operator type.
+     */
+    type: 'text' | 'number' | 'money' | 'date' | 'datetime' | 'boolean' | 'enum' | 'status' | 'priority' | 'country' | 'currency' | 'unit' | 'entity' | 'tags' | 'custom';
+    /**
+     * Explicit allowlisted operator IDs.
+     */
+    operators?: string[];
+    /**
+     * Initial operator ID.
+     */
+    defaultOperator?: string;
+    /**
+     * Static choices.
+     */
+    choices?: Array<{
+        value: string | number | boolean;
+        label: string;
+        icon?: Node | string;
+        color?: string;
+    }>;
+    /**
+     * Async choices.
+     */
+    loadChoices?: (context: {
+        query: string;
+        signal: AbortSignal;
+        conditionId: string;
+        field: FilterField;
+    }) => Promise<Array<{
+        value: string | number | boolean;
+        label: string;
+    }>> | Array<{
+        value: string | number | boolean;
+        label: string;
+    }>;
+    /**
+     * Custom editor.
+     */
+    editor?: (target: Element, context: {
+        value: unknown;
+        setValue: (value: unknown) => void;
+        field: FilterField;
+        conditionId: string;
+    }) => ({
+        destroy?: () => void;
+    } | void);
+    /**
+     * Async minimum query length.
+     */
+    minQuery?: number;
+    /**
+     * Async debounce in milliseconds.
+     */
+    debounce?: number;
+};
+export type FilterOptions = {
+    /**
+     * Field definitions.
+     */
+    fields: FilterField[];
+    /**
+     * Initial expression.
+     */
+    value?: FilterAst;
+    /**
+     * Additional/overridden operators.
+     */
+    operators?: Array<{
+        id: string;
+        label: string;
+        arity: 'none' | 'single' | 'pair' | 'many';
+        types: string[];
+    }>;
+    /**
+     * Whether nested groups may be authored.
+     */
+    allowGroups?: boolean;
+    /**
+     * Maximum nested group depth.
+     */
+    maxDepth?: number;
+    /**
+     * Maximum condition count.
+     */
+    maxConditions?: number;
+    /**
+     * Emit apply after every valid mutation.
+     */
+    autoApply?: boolean;
+    /**
+     * Prevent mutations while keeping values readable.
+     */
+    readonly?: boolean;
+    /**
+     * Disable all controls.
+     */
+    disabled?: boolean;
+    /**
+     * Apply button label.
+     */
+    applyLabel?: string;
+    /**
+     * Clear button label.
+     */
+    clearLabel?: string;
+    /**
+     * Draft-change listener.
+     */
+    onchange?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Valid-apply listener.
+     */
+    onapply?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Invalid-apply listener.
+     */
+    oninvalid?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Async query listener.
+     */
+    onquery?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Async loaded listener.
+     */
+    onloaded?: (event: CustomEvent<Record<string, unknown>>) => void;
+    /**
+     * Async failure listener.
+     */
+    onerror?: (event: CustomEvent<Record<string, unknown>>) => void;
+};
+/** @typedef {import('./filter-model.js').FilterAst} FilterAst */
+/**
+ * @typedef {Object} FilterField
+ * @property {string} id Stable allowlisted field ID.
+ * @property {string} label Display label.
+ * @property {'text'|'number'|'money'|'date'|'datetime'|'boolean'|'enum'|'status'|'priority'|'country'|'currency'|'unit'|'entity'|'tags'|'custom'} type Editor/operator type.
+ * @property {string[]} [operators] Explicit allowlisted operator IDs.
+ * @property {string} [defaultOperator] Initial operator ID.
+ * @property {Array<{value:string|number|boolean,label:string,icon?:Node|string,color?:string}>} [choices] Static choices.
+ * @property {(context:{query:string,signal:AbortSignal,conditionId:string,field:FilterField})=>Promise<Array<{value:string|number|boolean,label:string}>>|Array<{value:string|number|boolean,label:string}>} [loadChoices] Async choices.
+ * @property {(target:Element, context:{value:unknown,setValue:(value:unknown)=>void,field:FilterField,conditionId:string})=>({destroy?:()=>void}|void)} [editor] Custom editor.
+ * @property {number} [minQuery=0] Async minimum query length.
+ * @property {number} [debounce=200] Async debounce in milliseconds.
+ */
+/**
+ * @typedef {Object} FilterOptions
+ * @property {FilterField[]} fields Field definitions.
+ * @property {FilterAst} [value] Initial expression.
+ * @property {Array<{id:string,label:string,arity:'none'|'single'|'pair'|'many',types:string[]}>} [operators] Additional/overridden operators.
+ * @property {boolean} [allowGroups=true] Whether nested groups may be authored.
+ * @property {number} [maxDepth=3] Maximum nested group depth.
+ * @property {number} [maxConditions=50] Maximum condition count.
+ * @property {boolean} [autoApply=false] Emit apply after every valid mutation.
+ * @property {boolean} [readonly=false] Prevent mutations while keeping values readable.
+ * @property {boolean} [disabled=false] Disable all controls.
+ * @property {string} [applyLabel='Apply filters'] Apply button label.
+ * @property {string} [clearLabel='Clear'] Clear button label.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onchange] Draft-change listener.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onapply] Valid-apply listener.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [oninvalid] Invalid-apply listener.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onquery] Async query listener.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onloaded] Async loaded listener.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onerror] Async failure listener.
+ */
+/**
+ * Backend-neutral dynamic filter expression editor.
+ * @fires Filter#change
+ * @fires Filter#apply
+ * @fires Filter#invalid
+ * @fires Filter#query
+ * @fires Filter#loaded
+ * @fires Filter#error
+ * @extends {Component<FilterOptions>}
+ */
+export declare class Filter extends Component<FilterOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _fields: {
+        id: string;
+        label: string;
+        type: 'text' | 'number' | 'money' | 'date' | 'datetime' | 'boolean' | 'enum' | 'status' | 'priority' | 'country' | 'currency' | 'unit' | 'entity' | 'tags' | 'custom';
+        operators?: string[];
+        defaultOperator?: string;
+        choices?: Array<{
+            value: string | number | boolean;
+            label: string;
+            icon?: Node | string;
+            color?: string;
+        }>;
+        loadChoices?: (context: {
+            query: string;
+            signal: AbortSignal;
+            conditionId: string;
+            field: FilterField;
+        }) => Promise<Array<{
+            value: string | number | boolean;
+            label: string;
+        }>> | Array<{
+            value: string | number | boolean;
+            label: string;
+        }>;
+        editor?: (target: Element, context: {
+            value: unknown;
+            setValue: (value: unknown) => void;
+            field: FilterField;
+            conditionId: string;
+        }) => ({
+            destroy?: () => void;
+        } | void);
+        minQuery?: number;
+        debounce?: number;
+    }[];
+    _operators: any[];
+    _readonly: boolean;
+    _disabled: boolean;
+    _async: Map<any, any>;
+    _customEditors: any[];
+    _value: import("./filter-model.js").FilterAst;
+    _renderVersion: any;
+    static cssName: string;
+    /** @type {Readonly<FilterOptions>} */
+    static defaults: Readonly<FilterOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Returns a defensive AST copy. @returns {FilterAst} */
+    getValue(): FilterAst;
+    /** Atomically replaces the AST. @param {unknown} value @param {{silent?:boolean}} [options={}] @returns {this} */
+    setValue(value: unknown, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Adds a condition to a group. @param {string|null} [parentId=null] @param {Record<string,unknown>} [initial={}] @returns {string|null} */
+    addCondition(parentId?: string | null, initial?: Record<string, unknown>): string | null;
+    /** Adds a nested group. @param {string|null} [parentId=null] @param {'and'|'or'} [logic='and'] @returns {string|null} */
+    addGroup(parentId?: string | null, logic?: 'and' | 'or'): string | null;
+    /** Updates a node by stable ID. @param {string} id @param {Record<string,unknown>} patch @returns {this} */
+    update(id: string, patch?: Record<string, unknown>): this;
+    /** Removes a non-root node. @param {string} id @returns {this} */
+    remove(id: string): this;
+    /** Moves a node into a group while preserving its identity. @param {string} id @param {string} parentId @param {number} index @returns {this} */
+    move(id: string, parentId: string, index: number): this;
+    /** Returns semantic validity and errors. @returns {{valid:boolean,errors:Array<Record<string,string>>}} */
+    validate(): {
+        valid: boolean;
+        errors: Array<Record<string, string>>;
+    };
+    /** Applies only a valid AST. @returns {FilterAst|null} */
+    apply(): FilterAst | null;
+    /** Clears all conditions. @param {{silent?:boolean}} [options={}] @returns {this} */
+    clear({ silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Focuses a condition's field or the Add button. @param {string|null} [id=null] @returns {this} */
+    focus(id?: string | null): this;
+    /** @param {boolean} readonly @returns {this} */
+    setReadonly(readonly: boolean): this;
+    /** @returns {this} */
+    enable(): this;
+    /** @returns {this} */
+    disable(): this;
+    /** @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _render(): void;
+    /** @param {any} group @param {number} depth @param {boolean} root @returns {HTMLElement} */
+    _renderGroup(group: any, depth: number, root: boolean): HTMLElement;
+    /** @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;
+    /** @param {Event} event @returns {void} */
+    _handleChange(event: Event): void;
+    /** @param {Event} event @returns {void} */
+    _handleInput(event: Event): void;
+    /** @param {HTMLInputElement|HTMLSelectElement} target @returns {void} */
+    _valueInput(target: HTMLInputElement | HTMLSelectElement): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleClick(event: MouseEvent): void;
+    /** @param {string} id @param {any} value @returns {void} */
+    _setNodeValue(id: string, value: any): void;
+    /** @param {string} reason @param {string} nodeId @returns {void} */
+    _changed(reason: string, nodeId: string): void;
+    /** @param {string} id @param {FilterField} field @param {string} query @returns {void} */
+    _scheduleChoices(id: string, field: FilterField, query: string): void;
+    /** @param {string} id @returns {void} */
+    _abort(id: string): void;
+    /** @param {string} id @param {boolean} busy @returns {void} */
+    _setAsyncBusy(id: string, busy: boolean): void;
+    /** @param {any} node @returns {void} */
+    _abortTree(node: any): void;
+    /** @returns {void} */
+    _abortAll(): void;
+    /** @returns {void} */
+    _destroyEditors(): void;
+    /** @returns {boolean} */
+    _blocked(): boolean;
+    /** @returns {boolean} */
+    _canMutate(): boolean;
+    /** @returns {{maxDepth:number,maxConditions:number}} */
+    _limits(): {
+        maxDepth: number;
+        maxConditions: number;
+    };
+    /** @param {string} id @returns {FilterField|null} */
+    _field(id: string): FilterField | null;
+    /** @param {string} id @returns {any} */
+    _operator(id: string): any;
+    /** @param {FilterField|null} field @returns {any[]} */
+    _operatorsFor(field: FilterField | null): any[];
+    /** @param {FilterField|null} field @returns {string|null} */
+    _defaultOperator(field: FilterField | null): string | null;
+    /** @param {string} text @returns {void} */
+    _announce(text: string): void;
+}
+/** @event Filter#change @type {CustomEvent<Record<string,unknown>>} */
+/** @event Filter#apply @type {CustomEvent<{value:FilterAst}>} */
+/** @event Filter#invalid @type {CustomEvent<Record<string,unknown>>} */
+/** @event Filter#query @type {CustomEvent<Record<string,unknown>>} */
+/** @event Filter#loaded @type {CustomEvent<Record<string,unknown>>} */
+/** @event Filter#error @type {CustomEvent<Record<string,unknown>>} */