@zeyos/zx 3.0.0 → 4.1.0

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

@@ -1,7 +1,7 @@
 import { Component } from '../../core/component.js';
-import { AppRail } from '../app-rail/app-rail.js';
-export type AppNavItem = import('../app-rail/app-rail.js').AppNavItem;
-export type AppNavSelectDetail = import('../app-rail/app-rail.js').AppNavSelectDetail;
+import { AppRailPresenter as MinimizedPresenter } from '../../internal/app-rail.js';
+export type AppNavItem = import('../../internal/app-rail.js').AppNavItem;
+export type AppNavSelectDetail = import('../../internal/app-rail.js').AppNavSelectDetail;
 export type AppSidebarOptions = {
     /**
      * Application navigation tree.
@@ -16,13 +16,21 @@ export type AppSidebarOptions = {
      */
     expanded?: Array<string | number>;
     /**
-     * Whether the minimized AppRail is shown.
+     * Whether the minimized presentation is shown.
      */
     collapsed?: boolean;
     /**
-     * Workspace side.
+     * Whether vertical navigation exposes a mode toggle.
      */
-    side?: 'left' | 'right';
+    collapsible?: boolean;
+    /**
+     * Navigation flow; horizontal is always minimized.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Workspace edge occupied by navigation.
+     */
+    side?: 'left' | 'right' | 'top' | 'bottom';
     /**
      * Navigation accessible label.
      */
@@ -40,23 +48,35 @@ export type AppSidebarOptions = {
         toElement: () => Node | null;
     } | null;
     /**
-     * Minimized rail header content.
+     * Minimized leading content.
      */
     railHeader?: Node | string | number | {
         toElement: () => Node | null;
     } | null;
     /**
-     * Minimized rail footer content.
+     * Minimized trailing content.
      */
     railFooter?: Node | string | number | {
         toElement: () => Node | null;
     } | null;
+    /**
+     * Minimized flyout hover-open delay.
+     */
+    openDelay?: number;
+    /**
+     * Minimized flyout crossing grace.
+     */
+    closeDelay?: number;
+    /**
+     * Optional host icon renderer.
+     */
+    renderIcon?: (item: AppNavItem, context: Record<string, any>) => Node | null;
     /**
      * Preventable action listener.
      */
     onselect?: (event: CustomEvent<AppNavSelectDetail>) => void;
     /**
-     * Branch-state listener; bulk replacement reports null state.
+     * Branch-state listener.
      */
     onbranchchange?: (event: CustomEvent<{
         item: AppNavItem | null;
@@ -70,58 +90,79 @@ export type AppSidebarOptions = {
     oncollapsechange?: (event: CustomEvent<{
         collapsed: boolean;
     }>) => void;
+    /**
+     * Minimized flyout-state listener.
+     */
+    onflyoutchange?: (event: CustomEvent<{
+        item: AppNavItem;
+        id: string | number;
+        open: boolean;
+    }>) => void;
 };
-/** @typedef {import('../app-rail/app-rail.js').AppNavItem} AppNavItem */
-/** @typedef {import('../app-rail/app-rail.js').AppNavSelectDetail} AppNavSelectDetail */
+/** @typedef {import('../../internal/app-rail.js').AppNavItem} AppNavItem */
+/** @typedef {import('../../internal/app-rail.js').AppNavSelectDetail} AppNavSelectDetail */
 /**
  * @typedef {Object} AppSidebarOptions
  * @property {AppNavItem[]} [items=[]] Application navigation tree.
  * @property {string|number|null} [active=null] Active item id.
  * @property {Array<string|number>} [expanded=[]] Initially expanded branch ids.
- * @property {boolean} [collapsed=false] Whether the minimized AppRail is shown.
- * @property {'left'|'right'} [side='left'] Workspace side.
+ * @property {boolean} [collapsed=false] Whether the minimized presentation is shown.
+ * @property {boolean} [collapsible=true] Whether vertical navigation exposes a mode toggle.
+ * @property {'vertical'|'horizontal'} [orientation='vertical'] Navigation flow; horizontal is always minimized.
+ * @property {'left'|'right'|'top'|'bottom'} [side='left'] Workspace edge occupied by navigation.
  * @property {string} [label='Applications'] Navigation accessible label.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [header=null] Expanded header content.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [footer=null] Expanded sticky footer content.
- * @property {Node|string|number|{toElement: () => Node|null}|null} [railHeader=null] Minimized rail header content.
- * @property {Node|string|number|{toElement: () => Node|null}|null} [railFooter=null] Minimized rail footer content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railHeader=null] Minimized leading content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railFooter=null] Minimized trailing content.
+ * @property {number} [openDelay=80] Minimized flyout hover-open delay.
+ * @property {number} [closeDelay=160] Minimized flyout crossing grace.
+ * @property {(item: AppNavItem, context: Record<string, any>) => Node|null} [renderIcon] Optional host icon renderer.
  * @property {(event: CustomEvent<AppNavSelectDetail>) => void} [onselect] Preventable action listener.
- * @property {(event: CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>) => void} [onbranchchange] Branch-state listener; bulk replacement reports null state.
+ * @property {(event: CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>) => void} [onbranchchange] Branch-state listener.
  * @property {(event: CustomEvent<{collapsed: boolean}>) => void} [oncollapsechange] Presentation-state listener.
+ * @property {(event: CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>) => void} [onflyoutchange] Minimized flyout-state listener.
  */
 /**
- * Expanded vertical application navigation; the only Xenon shell mode with inline descendants.
+ * One application navigation component. Vertical expanded descendants render inline; minimized
+ * vertical and horizontal descendants use pointer-, focus-, and keyboard-accessible flyouts.
  * @fires AppSidebar#select
  * @fires AppSidebar#branchchange
  * @fires AppSidebar#collapsechange
+ * @fires AppSidebar#flyoutchange
  * @extends {Component<AppSidebarOptions>}
  */
 export declare class AppSidebar extends Component<AppSidebarOptions> {
+    _rail: MinimizedPresenter;
     _railExpandButton: HTMLElement;
-    _rail: AppRail;
     _createdRoot: boolean;
     _original: {
         attributes: string[][];
         children: ChildNode[];
     };
-    _items: import("../app-rail/app-rail.js").AppNavItem[];
+    _items: import("../../internal/app-rail.js").AppNavItem[];
     _active: string | number;
     _expanded: Set<string>;
     _collapsed: boolean;
+    _orientation: any;
+    _side: "bottom" | "left" | "right" | "top";
+    _modeAbort: AbortController;
     static cssName: string;
     /** @type {Readonly<AppSidebarOptions>} */
     static defaults: Readonly<AppSidebarOptions>;
     /**
-     * Creates or enhances an application-sidebar host.
-     * @param {Element|string|null} target Sidebar target.
-     * @param {AppSidebarOptions} [options={}] Sidebar options.
+     * Creates or enhances an application-navigation host.
+     * @param {Element|string|null} [target=null] Navigation target.
+     * @param {AppSidebarOptions} [options={}] Navigation options.
      */
     constructor(target?: Element | string | null, options?: AppSidebarOptions);
     /** @returns {HTMLElement} */
     render(): HTMLElement;
-    /** Replaces the navigation tree in both expanded and rail presentations. @param {AppNavItem[]} items @returns {this} */
+    /** Replaces the navigation tree in the active presentation. @param {AppNavItem[]} items @returns {this} */
     setItems(items: AppNavItem[]): this;
-    /** Sets the active id in both presentations without routing. @param {string|number|null} id @returns {this} */
+    /** Returns a shallow copy of normalized items. @returns {AppNavItem[]} */
+    getItems(): AppNavItem[];
+    /** Sets the active id without routing. @param {string|number|null} id @returns {this} */
     setActive(id: string | number | null): this;
     /** Replaces expanded branch ids. @param {Array<string|number>} ids @param {{silent?: boolean}} [options={}] @returns {this} */
     setExpanded(ids: Array<string | number>, { silent }?: {
@@ -133,30 +174,62 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     toggleBranch(id: string | number, { silent }?: {
         silent?: boolean;
     }): this;
-    /** Shows the expanded sidebar presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    /** Shows the expanded vertical presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
     expand(options?: {
         silent?: boolean;
     }): this;
-    /** Shows the minimized AppRail presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    /** Shows the minimized presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
     collapse(options?: {
         silent?: boolean;
     }): this;
-    /** Sets expanded/minimized presentation while preserving branch state. @param {boolean} collapsed @param {{silent?: boolean}} [options={}] @returns {this} */
+    /** Sets the saved vertical expanded/minimized state. @param {boolean} collapsed @param {{silent?: boolean}} [options={}] @returns {this} */
     setCollapsed(collapsed: boolean, { silent }?: {
         silent?: boolean;
     }): this;
-    /** Reports whether the rail presentation is active. @returns {boolean} */
+    /** Reports the effective presentation state; horizontal navigation is always minimized. @returns {boolean} */
     isCollapsed(): boolean;
-    /** Returns the composed minimized rail. @returns {AppRail} */
-    getRail(): AppRail;
-    /** Destroys the rail and restores/removes the sidebar host. @returns {void} */
+    /**
+     * Changes navigation flow/edge without replacing state.
+     * @param {{orientation?: 'vertical'|'horizontal', side?: 'left'|'right'|'top'|'bottom'}} layout
+     * @param {{silent?: boolean}} [options]
+     * @returns {this}
+     */
+    setLayout(layout?: {
+        orientation?: 'vertical' | 'horizontal';
+        side?: 'left' | 'right' | 'top' | 'bottom';
+    }, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Opens a minimized descendant flyout. @param {string|number} id @param {{focus?: boolean}} [options={}] @returns {this} */
+    openFlyout(id: string | number, options?: {
+        focus?: boolean;
+    }): this;
+    /** Closes a minimized descendant flyout. @param {string|number} id @returns {this} */
+    closeFlyout(id: string | number): this;
+    /** Closes every minimized flyout. @returns {this} */
+    closeAllFlyouts(): this;
+    /** Reports whether a minimized flyout is open. @param {string|number} id @returns {boolean} */
+    isFlyoutOpen(id: string | number): boolean;
+    /** Focuses the first navigation action. @returns {this} */
+    focus(): this;
+    /** Destroys flyouts and restores/removes the host. @returns {void} */
     destroy(): void;
+    /** Mounts exactly one expanded tree or minimized flyout presentation. @returns {void} */
+    _renderMode(): void;
+    /** @returns {void} */
+    _renderExpanded(): void;
+    /** @returns {void} */
+    _renderRail(): void;
+    /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
+    _listenMode(target: EventTarget, type: string, listener: EventListener): void;
     /** @returns {void} */
     _renderTree(): void;
     /** @param {AppNavItem} item @param {number} level @returns {HTMLElement} */
     _treeRow(item: AppNavItem, level: number): HTMLElement;
-    /** Handles dynamic tree controls without retaining detached nodes after a rerender. @param {Event} event @returns {void} */
+    /** @param {Event} event @returns {void} */
     _onTreeClick(event: Event): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onTreeKeydown(event: KeyboardEvent): void;
     /** @param {AppNavItem} item @param {Event} event @returns {void} */
     _select(item: AppNavItem, event: Event): void;
     /** @returns {void} */
@@ -167,3 +240,4 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
 /** Fired when a destination/action is activated. @event AppSidebar#select @type {CustomEvent<AppNavSelectDetail>} */
 /** Fired when an inline branch changes. @event AppSidebar#branchchange @type {CustomEvent<{item: AppNavItem|null, id: string|number|null, expanded: boolean|null, ids: Array<string|number>}>} */
 /** Fired when expanded/minimized presentation changes. @event AppSidebar#collapsechange @type {CustomEvent<{collapsed: boolean}>} */
+/** Fired when a minimized flyout changes. @event AppSidebar#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */

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

@@ -0,0 +1,128 @@
+import { Component } from '../../core/component.js';
+export type CardContent = string | Node | Component | null;
+export type ButtonOptions = import('../button/button.js').ButtonOptions;
+export type CardAction = Element | ButtonOptions;
+export type CardLinkDescriptor = {
+    /**
+     * Native link destination; executable/data schemes are rejected.
+     */
+    href: string;
+    /**
+     * Native browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+    /**
+     * Native click listener.
+     */
+    onclick?: (event: MouseEvent) => void;
+};
+export type CardLink = string | CardLinkDescriptor | null;
+export type CardOptions = {
+    /**
+     * Card title.
+     */
+    title?: string;
+    /**
+     * Optional image, avatar, icon, or other media.
+     */
+    media?: CardContent;
+    /**
+     * Main card content; enhanced children are adopted by default.
+     */
+    content?: CardContent;
+    /**
+     * Secondary native controls beside the title.
+     */
+    actions?: CardAction[];
+    /**
+     * Optional metadata or trailing content.
+     */
+    footer?: CardContent;
+    /**
+     * Optional native primary link rendered around the title.
+     */
+    link?: CardLink;
+    /**
+     * Surface treatment.
+     */
+    variant?: 'outlined' | 'raised' | 'filled';
+    /**
+     * Media/content arrangement.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Semantic title heading level.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+};
+/** @typedef {string|Node|Component|null} CardContent */
+/** @typedef {import('../button/button.js').ButtonOptions} ButtonOptions */
+/** @typedef {Element|ButtonOptions} CardAction */
+/**
+ * @typedef {Object} CardLinkDescriptor
+ * @property {string} href Native link destination; executable/data schemes are rejected.
+ * @property {string} [target] Native browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {(event: MouseEvent) => void} [onclick] Native click listener.
+ */
+/** @typedef {string|CardLinkDescriptor|null} CardLink */
+/**
+ * @typedef {Object} CardOptions
+ * @property {string} [title=''] Card title.
+ * @property {CardContent} [media=null] Optional image, avatar, icon, or other media.
+ * @property {CardContent} [content=null] Main card content; enhanced children are adopted by default.
+ * @property {CardAction[]} [actions=[]] Secondary native controls beside the title.
+ * @property {CardContent} [footer=null] Optional metadata or trailing content.
+ * @property {CardLink} [link=null] Optional native primary link rendered around the title.
+ * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Surface treatment.
+ * @property {'vertical'|'horizontal'} [orientation='vertical'] Media/content arrangement.
+ * @property {1|2|3|4|5|6} [headingLevel=3] Semantic title heading level.
+ */
+/**
+ * Semantic content or record surface with optional media, native primary link, actions, and footer.
+ * The root is never interactive: linked cards keep a real title anchor, so secondary controls are
+ * siblings rather than invalid nested actions.
+ * @extends {Component<CardOptions>}
+ */
+export declare class Card extends Component<CardOptions> {
+    _createdRoot: boolean;
+    _original: import("../../core/dom.js").TargetSnapshot;
+    _cleaned: boolean;
+    _title: string;
+    _link: CardLinkDescriptor;
+    _actionAbort: AbortController;
+    _linkAbort: AbortController;
+    static cssName: string;
+    /** @type {Readonly<CardOptions>} */
+    static defaults: Readonly<CardOptions>;
+    /**
+     * Creates or enhances one card.
+     * @param {Element|string|null} [target=null] Existing card container, selector, or null.
+     * @param {CardOptions} [options={}] Card options.
+     */
+    constructor(target?: Element | string | null, options?: CardOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Replaces the card title. @param {string} title Next title. @returns {this} */
+    setTitle(title: string): this;
+    /** Replaces or removes the media region. @param {CardContent} content Media. @returns {this} */
+    setMedia(content: CardContent): this;
+    /** Replaces or clears the main content. @param {CardContent} content Content. @returns {this} */
+    setContent(content: CardContent): this;
+    /** Replaces the secondary action controls. @param {CardAction[]} actions Actions. @returns {this} */
+    setActions(actions: CardAction[]): this;
+    /** Replaces or removes the footer. @param {CardContent} content Footer. @returns {this} */
+    setFooter(content: CardContent): this;
+    /** Sets or removes the title's native primary link. @param {CardLink} link Link. @returns {this} */
+    setLink(link: CardLink): this;
+    /** Restores an enhanced target exactly, or removes an owned card. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _renderHeading(): void;
+    /** @returns {void} */
+    _syncHeader(): void;
+}

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

@@ -219,6 +219,7 @@ export declare class Chart extends Component<ChartOptions> {
     _chartOptions: Record<string, unknown>;
     _loading: boolean;
     _error: unknown;
+    _hasError: boolean;
     _handle: ChartHandle;
     _destroyed: boolean;
     _observer: ResizeObserver;

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[];
+};