@zeyos/zx 2.3.0 → 4.0.0

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

@@ -0,0 +1,243 @@
+import { Component } from '../../core/component.js';
+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.
+     */
+    items?: AppNavItem[];
+    /**
+     * Active item id.
+     */
+    active?: string | number | null;
+    /**
+     * Initially expanded branch ids.
+     */
+    expanded?: Array<string | number>;
+    /**
+     * Whether the minimized presentation is shown.
+     */
+    collapsed?: boolean;
+    /**
+     * Whether vertical navigation exposes a mode toggle.
+     */
+    collapsible?: boolean;
+    /**
+     * Navigation flow; horizontal is always minimized.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Workspace edge occupied by navigation.
+     */
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * Navigation accessible label.
+     */
+    label?: string;
+    /**
+     * Expanded header content.
+     */
+    header?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Expanded sticky footer content.
+     */
+    footer?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Minimized leading content.
+     */
+    railHeader?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * 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.
+     */
+    onbranchchange?: (event: CustomEvent<{
+        item: AppNavItem | null;
+        id: string | number | null;
+        expanded: boolean | null;
+        ids: Array<string | number>;
+    }>) => void;
+    /**
+     * Presentation-state listener.
+     */
+    oncollapsechange?: (event: CustomEvent<{
+        collapsed: boolean;
+    }>) => void;
+    /**
+     * Minimized flyout-state listener.
+     */
+    onflyoutchange?: (event: CustomEvent<{
+        item: AppNavItem;
+        id: string | number;
+        open: boolean;
+    }>) => void;
+};
+/** @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 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 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.
+ * @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.
+ */
+/**
+ * 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;
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _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-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 the active presentation. @param {AppNavItem[]} items @returns {this} */
+    setItems(items: AppNavItem[]): 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 }?: {
+        silent?: boolean;
+    }): this;
+    /** Returns expanded branch ids in navigation order. @returns {Array<string|number>} */
+    getExpanded(): Array<string | number>;
+    /** Toggles one inline branch. @param {string|number} id @param {{silent?: boolean}} [options={}] @returns {this} */
+    toggleBranch(id: string | number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Shows the expanded vertical presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    expand(options?: {
+        silent?: boolean;
+    }): this;
+    /** Shows the minimized presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    collapse(options?: {
+        silent?: boolean;
+    }): 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 the effective presentation state; horizontal navigation is always minimized. @returns {boolean} */
+    isCollapsed(): boolean;
+    /**
+     * 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;
+    /** @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} */
+    _syncActive(): void;
+    /** @returns {void} */
+    _reconcileExpanded(): void;
+}
+/** 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/avatar/avatar.d.ts

@@ -0,0 +1,100 @@
+import { Component } from '../../core/component.js';
+export type AvatarOptions = {
+    /**
+     * Image URL.
+     */
+    src?: string | null;
+    /**
+     * Name used to derive fallback initials.
+     */
+    name?: string;
+    /**
+     * Explicit fallback initials.
+     */
+    initials?: string | null;
+    /**
+     * Accessible label; null makes the avatar decorative.
+     */
+    label?: string | null;
+    /**
+     * Preset (`sm`, `md`, `lg`) or pixel size.
+     */
+    size?: string | number;
+    /**
+     * Avatar shape.
+     */
+    shape?: 'circle' | 'rounded' | 'square';
+    /**
+     * Optional presence state.
+     */
+    status?: 'online' | 'away' | 'busy' | 'offline' | null;
+    /**
+     * Text alternative for the presence state.
+     */
+    statusLabel?: string | null;
+};
+/**
+ * @typedef {Object} AvatarOptions
+ * @property {string|null} [src=null] Image URL.
+ * @property {string} [name=''] Name used to derive fallback initials.
+ * @property {string|null} [initials=null] Explicit fallback initials.
+ * @property {string|null} [label=null] Accessible label; null makes the avatar decorative.
+ * @property {string|number} [size='md'] Preset (`sm`, `md`, `lg`) or pixel size.
+ * @property {'circle'|'rounded'|'square'} [shape='circle'] Avatar shape.
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
+ * @property {string|null} [statusLabel=null] Text alternative for the presence state.
+ */
+/**
+ * Stable-size user image with deterministic initials fallback and optional presence state.
+ * @extends {Component<AvatarOptions>}
+ */
+export declare class Avatar extends Component<AvatarOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _state: {
+        src: string;
+        name: string;
+        initials: string;
+        label: string;
+        size: string | number;
+        shape: "circle" | "rounded" | "square";
+        status: "away" | "busy" | "offline" | "online";
+        statusLabel: string;
+    };
+    static cssName: string;
+    /** @type {Readonly<AvatarOptions>} */
+    static defaults: Readonly<AvatarOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces avatar identity and presentation values.
+     * @param {Partial<AvatarOptions>} values New values.
+     * @returns {this}
+     */
+    set(values?: Partial<AvatarOptions>): this;
+    /** Sets the presence state and its text alternative. @param {AvatarOptions['status']} status @param {string|null} [label=null] @returns {this} */
+    setStatus(status: AvatarOptions['status'], label?: string | null): this;
+    /** Returns whether the image is currently visible. @returns {boolean} */
+    hasImage(): boolean;
+    /** Restores an enhanced target or removes an owned root. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /** Synchronizes the standalone accessible name, including valid presence text. @returns {void} */
+    _syncLabel(): void;
+    /** @param {boolean} visible @returns {void} */
+    _showImage(visible: boolean): void;
+    /** Ignores a late load/error from a source that has already been replaced. @returns {boolean} */
+    _isCurrentImageSource(): boolean;
+    /** @returns {void} */
+    _syncStatus(): void;
+}
+/**
+ * Derives at most two uppercase initials from the first and last words of a name.
+ * @param {unknown} name Name-like value.
+ * @returns {string}
+ */
+export declare function avatarInitials(name: unknown): string;

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