@zeyos/zx 3.0.0 → 4.1.0

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

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

@@ -21,19 +21,39 @@ export type LauncherItem = {
      */
     group?: string;
     /**
-     * Kernel icon name.
+     * Decorative icon name, node, or factory.
      */
-    icon?: string;
+    icon?: string | Node | ((item: LauncherItem) => Node | null);
     /**
      * Compact metadata.
      */
     badge?: string | number;
+    /**
+     * Tile or row presentation.
+     */
+    kind?: 'application' | 'record' | 'action';
+    /**
+     * Whether this is the current application or destination.
+     */
+    current?: boolean;
+    /**
+     * Query state in which the item is visible.
+     */
+    when?: 'always' | 'empty' | 'query';
+    /**
+     * Explicit group order.
+     */
+    groupOrder?: number;
+    /**
+     * Stable order within equally ranked results.
+     */
+    itemOrder?: number;
     /**
      * Emitted value; defaults to `id`.
      */
     value?: unknown;
     /**
-     * Native link target.
+     * Native link target; executable/data schemes are disabled.
      */
     href?: string;
     /**
@@ -66,6 +86,14 @@ export type LauncherSource = {
      * Per-source minimum query length.
      */
     minQuery?: number;
+    /**
+     * Query state in which the source runs.
+     */
+    when?: 'always' | 'empty' | 'query';
+    /**
+     * Whether Zx ranks results or preserves source order.
+     */
+    order?: 'rank' | 'source';
     /**
      * Loader.
      */
@@ -106,6 +134,14 @@ export type LauncherOptions = {
      * Dialog and field label.
      */
     label?: string;
+    /**
+     * Close-button accessible label.
+     */
+    closeLabel?: string;
+    /**
+     * Results-region accessible label.
+     */
+    resultsLabel?: string;
     /**
      * Empty-state text.
      */
@@ -118,6 +154,14 @@ export type LauncherOptions = {
      * Optional global keyboard shortcut.
      */
     shortcut?: 'mod+k' | false;
+    /**
+     * Visible keyboard hints, or false.
+     */
+    hints?: false | {
+        move?: string;
+        open?: string;
+        close?: string;
+    };
     /**
      * Preventable selection listener.
      */
@@ -161,10 +205,15 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {string} [description] Secondary text.
  * @property {string|string[]} [keywords] Additional search text.
  * @property {string} [group] Result group.
- * @property {string} [icon] Kernel icon name.
+ * @property {string|Node|((item: LauncherItem) => Node|null)} [icon] Decorative icon name, node, or factory.
  * @property {string|number} [badge] Compact metadata.
+ * @property {'application'|'record'|'action'} [kind='action'] Tile or row presentation.
+ * @property {boolean} [current=false] Whether this is the current application or destination.
+ * @property {'always'|'empty'|'query'} [when='always'] Query state in which the item is visible.
+ * @property {number} [groupOrder] Explicit group order.
+ * @property {number} [itemOrder] Stable order within equally ranked results.
  * @property {unknown} [value] Emitted value; defaults to `id`.
- * @property {string} [href] Native link target.
+ * @property {string} [href] Native link target; executable/data schemes are disabled.
  * @property {string} [target] Native link browsing context.
  * @property {() => void} [invoke] Application-owned callback for non-link actions.
  * @property {boolean|number} [pinned] Pinned state or explicit pinned order.
@@ -175,6 +224,8 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {string} id Source identifier.
  * @property {string} [label] Default group label.
  * @property {number} [minQuery] Per-source minimum query length.
+ * @property {'always'|'empty'|'query'} [when='always'] Query state in which the source runs.
+ * @property {'rank'|'source'} [order='rank'] Whether Zx ranks results or preserves source order.
  * @property {(query: string, context: {signal: AbortSignal}) => Promise<LauncherItem[]>|LauncherItem[]} load Loader.
  */
 /**
@@ -187,9 +238,12 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {number} [maxResults=100] Maximum combined results.
  * @property {string} [placeholder='Search applications and records'] Search-field placeholder.
  * @property {string} [label='Launcher'] Dialog and field label.
+ * @property {string} [closeLabel='Close launcher'] Close-button accessible label.
+ * @property {string} [resultsLabel='Launcher results'] Results-region accessible label.
  * @property {string} [emptyText='No results'] Empty-state text.
  * @property {string} [loadingText='Searching…'] Loading-state text.
  * @property {'mod+k'|false} [shortcut='mod+k'] Optional global keyboard shortcut.
+ * @property {false|{move?: string, open?: string, close?: string}} [hints] Visible keyboard hints, or false.
  * @property {(event: CustomEvent<LauncherSelectDetail>) => void} [onselect] Preventable selection listener.
  * @property {(event: CustomEvent<{query: string}>) => void} [onquery] Query-change listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
@@ -217,8 +271,9 @@ export declare class Launcher extends Component<LauncherOptions> {
     _sources: LauncherSource[];
     _sourceItems: Map<any, any>;
     _query: string;
+    _renderedQuery: string;
     _results: any[];
-    _active: number;
+    _active: any;
     _request: AbortController;
     _requestSequence: number;
     _queryTimer: number;
@@ -251,6 +306,8 @@ export declare class Launcher extends Component<LauncherOptions> {
     getQuery(): string;
     /** Replaces local catalogue items. @param {LauncherItem[]} items @returns {this} */
     setItems(items: LauncherItem[]): this;
+    /** Marks one local item as the current destination. @param {string|number|null} id Item id. @returns {this} */
+    setCurrent(id: string | number | null): this;
     /** Replaces asynchronous sources and aborts work from the old set. @param {LauncherSource[]} sources @returns {this} */
     setSources(sources: LauncherSource[]): this;
     /** Aborts sources and removes the owned dialog. @returns {void} */
@@ -273,6 +330,8 @@ export declare class Launcher extends Component<LauncherOptions> {
     _syncActive(): void;
     /** @param {KeyboardEvent} event @returns {void} */
     _onKeydown(event: KeyboardEvent): void;
+    /** @param {string} direction @param {number[]} enabled @returns {number|null} */
+    _spatialIndex(direction: string, enabled: number[]): number | null;
     /** @param {number} index @param {Event} event @returns {void} */
     _activate(index: number, event: Event): void;
     /** @param {KeyboardEvent} event @returns {void} */

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

@@ -3,6 +3,14 @@ export type Primitive = string | number | boolean | symbol | bigint | null | und
 export type SelectItem = Record<string, any> | Primitive;
 export type SelectValueReader = string | ((item: SelectItem) => unknown);
 export type SelectLabelReader = string | ((item: SelectItem) => string);
+export type SelectAction = {
+    id: string | number;
+    label: string;
+    icon?: string | Node;
+    description?: string;
+    group?: string;
+    invoke?: (detail: SelectActionDetail) => void;
+};
 export type SelectOptions = {
     /**
      * Available values.
@@ -12,6 +20,10 @@ export type SelectOptions = {
      * Choices pinned above the list, kept through filtering and async loads.
      */
     fixedItems?: SelectItem[];
+    /**
+     * Optional heading above pinned choices.
+     */
+    fixedLabel?: string | null;
     /**
      * Item ID property or reader.
      */
@@ -28,6 +40,22 @@ export type SelectOptions = {
      * Selected-value renderer.
      */
     renderValue?: ((item: SelectItem) => string) | null;
+    /**
+     * Decorative content before the selected text.
+     */
+    renderValueAdornment?: ((item: SelectItem) => Node | string | null) | null;
+    /**
+     * Clear-row renderer.
+     */
+    renderNone?: ((label: string) => Node | string) | null;
+    /**
+     * Clear-row label independent from the input placeholder.
+     */
+    noneLabel?: string | null;
+    /**
+     * Command rows that emit `action` without changing value.
+     */
+    actions?: SelectAction[];
     /**
      * Initially selected ID or item.
      */
@@ -92,6 +120,42 @@ export type SelectOptions = {
      * Async-loaded listener.
      */
     onloaded?: (event: CustomEvent<SelectLoadedDetail>) => void;
+    /**
+     * Preventable command-row listener.
+     */
+    onaction?: (event: CustomEvent<SelectActionDetail>) => void;
+};
+export type EntitySelectOptions = {
+    /**
+     * Choices pinned above ordinary results.
+     */
+    recent?: SelectItem[];
+    /**
+     * Heading above recent choices.
+     */
+    recentLabel?: string;
+    /**
+     * Optional create command at the bottom.
+     */
+    create?: boolean | SelectAction;
+    /**
+     * Item icon reader.
+     */
+    iconKey?: string | ((item: SelectItem) => unknown);
+    /**
+     * Optional icon colour reader.
+     */
+    colorKey?: string | ((item: SelectItem) => unknown);
+    /**
+     * Secondary-text reader.
+     */
+    subtitleKey?: string | ((item: SelectItem) => unknown);
+    /**
+     * Entity icon renderer.
+     */
+    renderIcon?: ((item: SelectItem, context: {
+        selected: boolean;
+    }) => Node | string | null) | null;
 };
 export type SelectChangeDetail = {
     value: unknown;
@@ -103,9 +167,16 @@ export type SelectQueryDetail = {
 export type SelectLoadedDetail = {
     items: SelectItem[];
 };
+export type SelectActionDetail = {
+    id: string | number;
+    action: SelectAction;
+    query: string;
+    select: Select;
+};
 export type SelectOptionEntry = {
     item: SelectItem | null;
     clear: boolean;
+    action: SelectAction | null;
     element: HTMLElement;
 };
 export type SelectSetOptions = {
@@ -126,6 +197,7 @@ export declare class Select extends Component<SelectOptions> {
     _visibleItems: any[];
     _fixedItems: any[] | SelectItem[];
     _visibleFixed: any[] | SelectItem[];
+    _actions: any[] | SelectAction[];
     _selected: SelectItem;
     _optionEntries: any[];
     _activeIndex: number;
@@ -137,8 +209,7 @@ export declare class Select extends Component<SelectOptions> {
     _position: import("../../core/position.js").PositionController;
     _createdRoot: boolean;
     _root: HTMLElement;
-    _originalChildren: any[] | ChildNode[];
-    _originalAttributes: Map<any, any>;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
     _handleTypeahead: (event: KeyboardEvent | string) => void;
     static cssName: string;
     /** @type {SelectOptions} */
@@ -171,6 +242,8 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {this}
      */
     setFixedItems(items: SelectItem[]): this;
+    /** Replaces command rows without changing the selected value. @param {SelectAction[]} actions @returns {this} */
+    setActions(actions: SelectAction[]): this;
     /**
      * Restores the configured initial value.
      * @param {{silent?: boolean}} [options={}] Reset behavior.
@@ -196,6 +269,22 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {Select}
      */
     static priority(target: Element | string | null, options?: SelectOptions): Select;
+    /**
+     * Creates a status picker with shape- and color-distinct workflow indicators.
+     * @param {Element|string|null} target Component target.
+     * @param {SelectOptions & {items?: Array<Record<string, any>>}} [options={}] Select overrides and status items.
+     * @returns {Select}
+     */
+    static status(target: Element | string | null, options?: SelectOptions & {
+        items?: Array<Record<string, any>>;
+    }): Select;
+    /**
+     * Creates a rich entity picker with optional Recent choices and a create command.
+     * @param {Element|string|null} target Component target.
+     * @param {SelectOptions & EntitySelectOptions} [options={}] Entity-preset options.
+     * @returns {Select}
+     */
+    static entity(target: Element | string | null, options?: SelectOptions & EntitySelectOptions): Select;
     /**
      * Creates the record-permission picker: the fixed Private and Public choices above the groups a
      * record can be shared with. The value is the tri-state ZeyOS stores — `false` for private,
@@ -228,6 +317,8 @@ export declare class Select extends Component<SelectOptions> {
     _renderOptions(): void;
     /** @param {SelectItem|null} item @param {boolean} clear @param {string} [label] @returns {void} */
     _appendOption(item: SelectItem | null, clear: boolean, label?: string): void;
+    /** @param {SelectAction} action @returns {void} */
+    _appendAction(action: SelectAction): void;
     /** @param {SelectItem|null} item @returns {Node|string} */
     _renderItem(item: SelectItem | null): Node | string;
     /** @param {string} query @returns {void} */
@@ -241,6 +332,8 @@ export declare class Select extends Component<SelectOptions> {
     /** @returns {void} */
     _syncInputValue(): void;
     /** @returns {void} */
+    _syncValueAdornment(): void;
+    /** @returns {void} */
     _syncDisabled(): void;
     /** @param {unknown} candidate @returns {SelectItem|null} */
     _findItem(candidate: unknown): SelectItem | null;
@@ -259,12 +352,12 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {SelectItem[]}
      */
     _matchFixed(query: string): SelectItem[];
+    /** De-duplicates choices by public value while preserving caller order. @param {SelectItem[]} items @param {SelectItem[]} [excluded=[]] @returns {SelectItem[]} */
+    _uniqueItems(items: SelectItem[], excluded?: SelectItem[]): SelectItem[];
     /** @returns {number} */
     _selectedEntryIndex(): number;
     /** @param {number} itemIndex @returns {number} */
     _itemEntryIndex(itemIndex: number): number;
-    /** @param {string} name @returns {void} */
-    _rememberAttribute(element: any, name: string): void;
     /** @param {string} key @param {string} fallback @returns {string} */
     _message(key: string, fallback: string): string;
 }