@zeyos/zx 2.3.0 → 3.0.0

package/dist/types/components/account-menu/account-menu.d.ts

@@ -0,0 +1,144 @@
+import { Component } from '../../core/component.js';
+import { Avatar } from '../avatar/avatar.js';
+import { MenuButton } from '../menu-button/menu-button.js';
+export type MenuButtonItem = import('../menu-button/menu-button.js').MenuButtonItem;
+export type AccountIdentity = {
+    /**
+     * Primary identity.
+     */
+    name?: string;
+    /**
+     * Email, company, or other secondary identity.
+     */
+    secondary?: string;
+    /**
+     * Avatar image URL.
+     */
+    src?: string | null;
+    /**
+     * Explicit avatar initials.
+     */
+    initials?: string | null;
+    /**
+     * Presence state.
+     */
+    status?: 'online' | 'away' | 'busy' | 'offline' | null;
+    /**
+     * Presence text alternative.
+     */
+    statusLabel?: string | null;
+};
+export type AccountMenuOptions = {
+    /**
+     * Account presentation supplied by the application.
+     */
+    account?: AccountIdentity;
+    /**
+     * Account actions and `'-'` separators.
+     */
+    items?: MenuButtonItem[];
+    /**
+     * Whether only the avatar is visually shown in the trigger.
+     */
+    compact?: boolean;
+    /**
+     * Trigger label; defaults to `Account menu for <name>`.
+     */
+    label?: string | null;
+    /**
+     * Popup placement.
+     */
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top' | 'right-start' | 'right-end' | 'left-start' | 'left-end' | 'right' | 'left';
+    /**
+     * Preventable action listener.
+     */
+    onselect?: (event: CustomEvent<{
+        value: unknown;
+        item: object;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/** @typedef {import('../menu-button/menu-button.js').MenuButtonItem} MenuButtonItem */
+/**
+ * @typedef {Object} AccountIdentity
+ * @property {string} [name=''] Primary identity.
+ * @property {string} [secondary=''] Email, company, or other secondary identity.
+ * @property {string|null} [src=null] Avatar image URL.
+ * @property {string|null} [initials=null] Explicit avatar initials.
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Presence state.
+ * @property {string|null} [statusLabel=null] Presence text alternative.
+ */
+/**
+ * @typedef {Object} AccountMenuOptions
+ * @property {AccountIdentity} [account={}] Account presentation supplied by the application.
+ * @property {MenuButtonItem[]} [items=[]] Account actions and `'-'` separators.
+ * @property {boolean} [compact=false] Whether only the avatar is visually shown in the trigger.
+ * @property {string|null} [label=null] Trigger label; defaults to `Account menu for <name>`.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'|'right-start'|'right-end'|'left-start'|'left-end'|'right'|'left'} [placement='top-start'] Popup placement.
+ * @property {(event: CustomEvent<{value: unknown, item: object}>) => void} [onselect] Preventable action listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ */
+/**
+ * Avatar-backed APG account action menu; session/authentication behavior remains application-owned.
+ * @fires AccountMenu#select
+ * @fires AccountMenu#open
+ * @fires AccountMenu#close
+ * @extends {Component<AccountMenuOptions>}
+ */
+export declare class AccountMenu extends Component<AccountMenuOptions> {
+    _avatar: Avatar;
+    _menu: MenuButton;
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _account: AccountIdentity & {
+        name: string;
+        secondary: string;
+    };
+    static cssName: string;
+    /** @type {Readonly<AccountMenuOptions>} */
+    static defaults: Readonly<AccountMenuOptions>;
+    /**
+     * Creates or enhances an account-menu host.
+     * @param {Element|string|null} target Host target.
+     * @param {AccountMenuOptions} [options={}] Account-menu options.
+     */
+    constructor(target?: Element | string | null, options?: AccountMenuOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Opens the account menu. @returns {this} */
+    open(): this;
+    /** Closes the account menu. @returns {this} */
+    close(): this;
+    /** Toggles the account menu. @returns {this} */
+    toggle(): this;
+    /** Reports whether the menu is open. @returns {boolean} */
+    isOpen(): boolean;
+    /** Replaces account presentation without touching session state. @param {AccountIdentity} account @returns {this} */
+    setAccount(account: AccountIdentity): this;
+    /** Replaces account actions. @param {MenuButtonItem[]} items @returns {this} */
+    setItems(items: MenuButtonItem[]): this;
+    /** Focuses the account trigger. @returns {this} */
+    focus(): this;
+    /** Returns the underlying menu panel for shell hover/focus coordination. @returns {HTMLElement} */
+    getPanel(): HTMLElement;
+    /** Destroys child components and restores/removes the host. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _renderIdentity(): void;
+    /** @returns {void} */
+    _renderPanelHeader(): void;
+}
+/** Fired when an action is activated. @event AccountMenu#select @type {CustomEvent<{value: unknown, item: object}>} */
+/** Fired after the popup opens. @event AccountMenu#open @type {CustomEvent<Record<string, never>>} */
+/** Fired after the popup closes. @event AccountMenu#close @type {CustomEvent<Record<string, never>>} */

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

@@ -0,0 +1,250 @@
+import { Component } from '../../core/component.js';
+import { Dropdown } from '../dropdown/dropdown.js';
+export type AppNavItem = {
+    /**
+     * Stable item identifier.
+     */
+    id: string | number;
+    /**
+     * Visible/accessibility label.
+     */
+    label: string;
+    /**
+     * Kernel icon name.
+     */
+    icon?: string;
+    /**
+     * Count or status badge.
+     */
+    badge?: string | number;
+    /**
+     * Emitted value; defaults to `id`.
+     */
+    value?: unknown;
+    /**
+     * Native navigation target.
+     */
+    href?: string;
+    /**
+     * Native link browsing context.
+     */
+    target?: string;
+    /**
+     * Application-owned non-link action.
+     */
+    invoke?: () => void;
+    /**
+     * Whether activation is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * Child destinations/actions.
+     */
+    children?: AppNavItem[];
+};
+export type AppRailOptions = {
+    /**
+     * Application navigation tree.
+     */
+    items?: AppNavItem[];
+    /**
+     * Active item id.
+     */
+    active?: string | number | null;
+    /**
+     * Rail flow.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Workspace edge occupied by the rail.
+     */
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * Navigation accessible label.
+     */
+    label?: string;
+    /**
+     * Leading rail content.
+     */
+    header?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Trailing rail content.
+     */
+    footer?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Hover-open delay in milliseconds.
+     */
+    openDelay?: number;
+    /**
+     * Pointer/focus crossing grace in milliseconds.
+     */
+    closeDelay?: number;
+    /**
+     * Preventable action listener.
+     */
+    onselect?: (event: CustomEvent<AppNavSelectDetail>) => void;
+    /**
+     * Flyout-state listener.
+     */
+    onflyoutchange?: (event: CustomEvent<{
+        item: AppNavItem;
+        id: string | number;
+        open: boolean;
+    }>) => void;
+};
+export type AppNavSelectDetail = {
+    item: AppNavItem;
+    id: string | number;
+    value: unknown;
+    href: string | null;
+    event: Event;
+};
+export type RailFlyout = {
+    key: string;
+    parentKey: string | null;
+    item: AppNavItem;
+    trigger: HTMLElement;
+    panel: HTMLElement;
+    dropdown: Dropdown;
+};
+/**
+ * @typedef {Object} AppNavItem
+ * @property {string|number} id Stable item identifier.
+ * @property {string} label Visible/accessibility label.
+ * @property {string} [icon] Kernel icon name.
+ * @property {string|number} [badge] Count or status badge.
+ * @property {unknown} [value] Emitted value; defaults to `id`.
+ * @property {string} [href] Native navigation target.
+ * @property {string} [target] Native link browsing context.
+ * @property {() => void} [invoke] Application-owned non-link action.
+ * @property {boolean} [disabled] Whether activation is unavailable.
+ * @property {AppNavItem[]} [children] Child destinations/actions.
+ */
+/**
+ * @typedef {Object} AppRailOptions
+ * @property {AppNavItem[]} [items=[]] Application navigation tree.
+ * @property {string|number|null} [active=null] Active item id.
+ * @property {'vertical'|'horizontal'} [orientation='vertical'] Rail flow.
+ * @property {'left'|'right'|'top'|'bottom'} [side='left'] Workspace edge occupied by the rail.
+ * @property {string} [label='Applications'] Navigation accessible label.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [header=null] Leading rail content.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [footer=null] Trailing rail content.
+ * @property {number} [openDelay=80] Hover-open delay in milliseconds.
+ * @property {number} [closeDelay=160] Pointer/focus crossing grace in milliseconds.
+ * @property {(event: CustomEvent<AppNavSelectDetail>) => void} [onselect] Preventable action listener.
+ * @property {(event: CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>) => void} [onflyoutchange] Flyout-state listener.
+ */
+/** @typedef {{item: AppNavItem, id: string|number, value: unknown, href: string|null, event: Event}} AppNavSelectDetail */
+/** @typedef {{key: string, parentKey: string|null, item: AppNavItem, trigger: HTMLElement, panel: HTMLElement, dropdown: Dropdown}} RailFlyout */
+/**
+ * Minimized application navigation; descendants always open in hover/focus flyouts, never inline.
+ * @fires AppRail#select
+ * @fires AppRail#flyoutchange
+ * @extends {Component<AppRailOptions>}
+ */
+export declare class AppRail extends Component<AppRailOptions> {
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _items: AppNavItem[];
+    _active: string | number;
+    _flyouts: Map<any, any>;
+    _tooltips: any[];
+    _tooltipById: Map<any, any>;
+    _interaction: RailListenerScope;
+    _openTimers: Map<any, any>;
+    _closeTimers: Map<any, any>;
+    _pointerFocus: WeakSet<object>;
+    _silenceFlyoutEvents: boolean;
+    static cssName: string;
+    /** @type {Readonly<AppRailOptions>} */
+    static defaults: Readonly<AppRailOptions>;
+    /**
+     * Creates or enhances a rail host.
+     * @param {Element|string|null} target Rail target.
+     * @param {AppRailOptions} [options={}] Rail options.
+     */
+    constructor(target?: Element | string | null, options?: AppRailOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Replaces navigation items and closes removed flyouts. @param {AppNavItem[]} items @returns {this} */
+    setItems(items: AppNavItem[]): this;
+    /** Sets the active item without routing. @param {string|number|null} id @returns {this} */
+    setActive(id: string | number | null): this;
+    /** Returns a shallow copy of normalized items. @returns {AppNavItem[]} */
+    getItems(): AppNavItem[];
+    /** Opens one item's flyout, optionally focusing its first action. @param {string|number} id @param {{focus?: boolean}} [options={}] @returns {this} */
+    openFlyout(id: string | number, { focus }?: {
+        focus?: boolean;
+    }): this;
+    /** Closes one flyout. @param {string|number} id @returns {this} */
+    closeFlyout(id: string | number): this;
+    /** Closes every flyout and cancels pending hover/focus transitions. @returns {this} */
+    closeAllFlyouts(): this;
+    /** Reports whether an item's flyout is open. @param {string|number} id @returns {boolean} */
+    isFlyoutOpen(id: string | number): boolean;
+    /** Focuses the first top-level rail item. @returns {this} */
+    focus(): this;
+    /** Reports whether a node belongs to this rail, including detached flyout panels. @param {Node|null} node @returns {boolean} @private */
+    private _containsNode;
+    /** Destroys body popovers/tooltips and restores or removes the root. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _rebuild(): void;
+    /** @param {AppNavItem} item @param {HTMLElement} trigger @param {string} key @param {string|null} parentKey @returns {void} */
+    _buildFlyout(item: AppNavItem, trigger: HTMLElement, key: string, parentKey: string | null): void;
+    /** @param {AppNavItem} item @param {Event} event @returns {Event} */
+    _select(item: AppNavItem, event: Event): Event;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onRailKeydown(event: KeyboardEvent): void;
+    /** @param {KeyboardEvent} event @param {RailFlyout} flyout @returns {void} */
+    _onFlyoutKeydown(event: KeyboardEvent, flyout: RailFlyout): void;
+    /** @param {string|number} id @returns {void} */
+    _scheduleOpen(id: string | number): void;
+    /** @param {string|number} id @returns {void} */
+    _scheduleClose(id: string | number): void;
+    /** Schedules a flyout and, when leaving a detached panel, each owning flyout for re-evaluation. @param {RailFlyout} flyout @param {boolean} ancestors @returns {void} */
+    _scheduleFlyoutClose(flyout: RailFlyout, ancestors: boolean): void;
+    /** Resolves a public id or internal descendant path. @param {string|number} id @returns {RailFlyout|null} */
+    _resolveFlyout(id: string | number): RailFlyout | null;
+    /** Closes the root flyout that owns a selected descendant. @param {string} key @returns {void} */
+    _closeFlyoutChain(key: string): void;
+    /** Reports whether one flyout owns another through its parent chain. @param {RailFlyout} ancestor @param {RailFlyout} descendant @returns {boolean} */
+    _isAncestor(ancestor: RailFlyout, descendant: RailFlyout): boolean;
+    /** Cancels crossing timers for a flyout and optionally every owning flyout. @param {RailFlyout} flyout @param {boolean} ancestors @returns {void} */
+    _cancelFlyoutTimers(flyout: RailFlyout, ancestors: boolean): void;
+    /** Reports pointer/focus presence in a flyout branch, including detached descendant panels. @param {RailFlyout} flyout @returns {boolean} */
+    _branchInteracting(flyout: RailFlyout): boolean;
+    /** Restores trigger focus without immediately reopening the flyout through its focus handler. @param {HTMLElement} trigger @returns {void} */
+    _restoreFocus(trigger: HTMLElement): void;
+    /** @param {string} key @returns {void} */
+    _cancelTimers(key: string): void;
+    /** @param {Map<string, ReturnType<typeof setTimeout>>} timers @param {string} key @returns {void} */
+    _cancelTimer(timers: Map<string, ReturnType<typeof setTimeout>>, key: string): void;
+    /** @returns {void} */
+    _syncActive(): void;
+    /** @returns {void} */
+    _clearArtifacts(): void;
+}
+/** Owns listeners attached to one dynamic rail render so `setItems()` can release them immediately. */
+declare class RailListenerScope extends Component {
+    /** @param {HTMLElement} host Rail host. */
+    constructor(host: HTMLElement);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+}
+/**
+ * Normalizes an application navigation tree without mutating caller data.
+ * @param {unknown} items Candidate tree.
+ * @returns {AppNavItem[]}
+ */
+export declare function normalizeAppItems(items: unknown): AppNavItem[];
+export {};
+/** Fired when a destination/action is activated. @event AppRail#select @type {CustomEvent<AppNavSelectDetail>} */
+/** Fired when a flyout opens or closes. @event AppRail#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */

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

@@ -0,0 +1,169 @@
+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;
+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 AppRail is shown.
+     */
+    collapsed?: boolean;
+    /**
+     * Workspace side.
+     */
+    side?: 'left' | 'right';
+    /**
+     * 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 rail header content.
+     */
+    railHeader?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Minimized rail footer content.
+     */
+    railFooter?: Node | string | number | {
+        toElement: () => Node | null;
+    } | null;
+    /**
+     * Preventable action listener.
+     */
+    onselect?: (event: CustomEvent<AppNavSelectDetail>) => void;
+    /**
+     * Branch-state listener; bulk replacement reports null state.
+     */
+    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;
+};
+/** @typedef {import('../app-rail/app-rail.js').AppNavItem} AppNavItem */
+/** @typedef {import('../app-rail/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 {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 {(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<{collapsed: boolean}>) => void} [oncollapsechange] Presentation-state listener.
+ */
+/**
+ * Expanded vertical application navigation; the only Xenon shell mode with inline descendants.
+ * @fires AppSidebar#select
+ * @fires AppSidebar#branchchange
+ * @fires AppSidebar#collapsechange
+ * @extends {Component<AppSidebarOptions>}
+ */
+export declare class AppSidebar extends Component<AppSidebarOptions> {
+    _railExpandButton: HTMLElement;
+    _rail: AppRail;
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _items: import("../app-rail/app-rail.js").AppNavItem[];
+    _active: string | number;
+    _expanded: Set<string>;
+    _collapsed: boolean;
+    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.
+     */
+    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} */
+    setItems(items: AppNavItem[]): this;
+    /** Sets the active id in both presentations 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 sidebar presentation. @param {{silent?: boolean}} [options={}] @returns {this} */
+    expand(options?: {
+        silent?: boolean;
+    }): this;
+    /** Shows the minimized AppRail 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} */
+    setCollapsed(collapsed: boolean, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Reports whether the rail presentation is active. @returns {boolean} */
+    isCollapsed(): boolean;
+    /** Returns the composed minimized rail. @returns {AppRail} */
+    getRail(): AppRail;
+    /** Destroys the rail and restores/removes the sidebar host. @returns {void} */
+    destroy(): 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} */
+    _onTreeClick(event: Event): 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}>} */

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;