@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/activity-list/activity-list.d.ts

@@ -3,6 +3,7 @@ export type ActivityItemOptions = import('../activity-item/activity-item.js').Ac
 export type ActivityListContent = string | number | Node | Component | null;
 export type ActivityGroupReader = string | ((item: ActivityItemOptions, index: number) => unknown) | null;
 export type ActivityGroupLabel = (group: unknown, items: ActivityItemOptions[]) => ActivityListContent;
+export type ActivityListVariant = 'default' | 'compact';
 export type ActivityGroup = {
     /**
      * Group identity returned by the configured reader.
@@ -30,6 +31,11 @@ export type ActivityListOptions = {
      * Accessible collection name.
      */
     label?: string;
+    /**
+     * Entry layout, reflected as `data-variant` on
+     * the root. `'compact'` also makes an avatar descriptor without a `size` small.
+     */
+    variant?: ActivityListVariant;
     /**
      * Whether initial or incremental activity is loading.
      */
@@ -62,6 +68,13 @@ export type ActivityListOptions = {
 /** @typedef {string|number|Node|Component|null} ActivityListContent */
 /** @typedef {string|((item:ActivityItemOptions,index:number)=>unknown)|null} ActivityGroupReader */
 /** @typedef {(group:unknown,items:ActivityItemOptions[])=>ActivityListContent} ActivityGroupLabel */
+/**
+ * Entry layout. `'default'` gives each entry its avatar, a heading row, and room for content;
+ * below 30rem the time moves under the heading. `'compact'` is one line per entry at any width —
+ * actor and summary reading as one sentence, the time at the trailing end, a small avatar, and
+ * metadata as a muted second line — for a summary card narrower than 30rem.
+ * @typedef {'default'|'compact'} ActivityListVariant
+ */
 /**
  * @typedef {Object} ActivityGroup
  * @property {unknown} id Group identity returned by the configured reader.
@@ -73,6 +86,8 @@ export type ActivityListOptions = {
  * @property {ActivityGroupReader} [groupBy=null] Property or resolver used for stable grouping.
  * @property {ActivityGroupLabel|null} [groupLabel=null] Group-heading renderer.
  * @property {string} [label='Activity'] Accessible collection name.
+ * @property {ActivityListVariant} [variant='default'] Entry layout, reflected as `data-variant` on
+ * the root. `'compact'` also makes an avatar descriptor without a `size` small.
  * @property {boolean} [loading=false] Whether initial or incremental activity is loading.
  * @property {number} [loadingCount=3] Placeholder rows shown for an empty loading list.
  * @property {string} [loadingText='Loading activity'] Loading status text.
@@ -97,6 +112,7 @@ export declare class ActivityList extends Component<ActivityListOptions> {
     _loading: any;
     _itemComponents: any[];
     _groupSequence: number;
+    _variant: ActivityListVariant;
     static cssName: string;
     /** @type {Readonly<ActivityListOptions>} */
     static defaults: Readonly<ActivityListOptions>;
@@ -162,8 +178,16 @@ export declare class ActivityList extends Component<ActivityListOptions> {
     setLoading(loading: boolean): this;
     /** Restores an enhanced target exactly, or removes an owned list. @returns {void} */
     destroy(): void;
-    /** @private @returns {void} */
+    /**
+     * Rebuilds the list. Items are regrouped on every mutation, so the rows are new; focus that sat
+     * on an item's control is put back on the same control of the same activity (matched by `id`,
+     * else by position), so a live feed prepending entries does not throw the reader to `<body>`.
+     * @private
+     * @returns {void}
+     */
     private _renderList;
+    /** @private @returns {void} */
+    private _renderItems;
     /** @private @param {ActivityGroup} group @param {boolean} grouped @returns {HTMLElement} */
     private _createGroup;
     /** @private @param {boolean} placeholders @returns {HTMLElement} */
@@ -188,6 +212,12 @@ export declare function groupActivityItems(items: ActivityItemOptions[], groupBy
  * @returns {ActivityItemOptions[]}
  */
 export declare function normalizeActivityItems(value: unknown): ActivityItemOptions[];
+/**
+ * Resolves the entry layout; anything but `'compact'` is the default layout.
+ * @param {unknown} value Requested variant.
+ * @returns {ActivityListVariant}
+ */
+export declare function normalizeActivityListVariant(value: unknown): ActivityListVariant;
 /**
  * Activity descriptors changed through a list mutation method.
  * @event ActivityList#datachange

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

@@ -1,13 +1,22 @@
 import { Component } from '../../core/component.js';
+export type AppIconTone = 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet' | 'slate';
+/** @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AppIconTone */
+/** The categorical tones a `tone` option accepts. @type {ReadonlyArray<AppIconTone>} */
+export declare const APP_ICON_TONES: ReadonlyArray<AppIconTone>;
 export type AppIconOptions = {
     /**
      * Icon name, node, or lazy renderer.
      */
     icon?: string | Node | (() => string | Node) | null;
     /**
-     * Identity colour; falls back to the accent colour.
+     * Identity colour, any CSS colour; takes precedence over `tone`.
      */
     color?: string | null;
+    /**
+     * Categorical identity colour from the theme's tone palette,
+     * drawn with its `--zx-color-tone-<tone>-solid` fill. Without `color` or `tone` the icon takes the accent.
+     */
+    tone?: AppIconTone | null;
     /**
      * Edge length in pixels or any CSS length.
      */
@@ -44,7 +53,9 @@ export type AppIconOptions = {
 /**
  * @typedef {Object} AppIconOptions
  * @property {string|Node|(()=>string|Node)|null} [icon=null] Icon name, node, or lazy renderer.
- * @property {string|null} [color=null] Identity colour; falls back to the accent colour.
+ * @property {string|null} [color=null] Identity colour, any CSS colour; takes precedence over `tone`.
+ * @property {AppIconTone|null} [tone=null] Categorical identity colour from the theme's tone palette,
+ *   drawn with its `--zx-color-tone-<tone>-solid` fill. Without `color` or `tone` the icon takes the accent.
  * @property {number|string} [size=36] Edge length in pixels or any CSS length.
  * @property {number|string} [iconSize='52%'] Glyph size.
  * @property {string|null} [label=null] Accessible image label; null makes the icon decorative.
@@ -65,6 +76,7 @@ export declare class AppIcon extends Component<AppIconOptions> {
     _state: {
         icon?: string | Node | (() => string | Node) | null;
         color?: string | null;
+        tone?: AppIconTone | null;
         size?: number | string;
         iconSize?: number | string;
         label?: string | null;

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

@@ -1,12 +1,43 @@
 import { Component } from '../../core/component.js';
 import { AppRailPresenter as MinimizedPresenter } from '../../internal/app-rail.js';
+import { ModuleBar } from '../module-bar/module-bar.js';
 export type AppNavItem = import('../../internal/app-rail.js').AppNavItem;
 export type AppNavSelectDetail = import('../../internal/app-rail.js').AppNavSelectDetail;
+export type ModuleItem = import('../module-bar/module-bar.js').ModuleItem;
+export type AppSidebarModule = ModuleItem & {
+    header?: Node | {
+        toElement: () => Node | null;
+    };
+    content?: Node | {
+        toElement: () => Node | null;
+    };
+};
+export type AppSidebarModuleBarOptions = {
+    /**
+     * Tile treatment.
+     */
+    appearance?: 'tint' | 'solid' | 'plain';
+    /**
+     * Module names on the strip: `'auto'`
+     * prints them beside the tiles while expanded and leaves the icons alone while collapsed;
+     * `'hidden'` keeps the icon strip beside the panel; `'below'` prints them under the tiles.
+     */
+    labels?: 'auto' | 'beside' | 'below' | 'hidden';
+    /**
+     * The "All modules" button.
+     */
+    allModules?: 'auto' | 'always' | 'never';
+    /**
+     * Strip accessible label; omitted resolves `moduleBar.label`.
+     */
+    label?: string | null;
+};
 export type AppSidebarOptions = {
     /**
-     * Application navigation tree.
+     * Application navigation tree; in the
+     * modules layout its top level is the modules.
      */
-    items?: AppNavItem[];
+    items?: AppNavItem[] | AppSidebarModule[];
     /**
      * Active item id.
      */
@@ -31,12 +62,44 @@ export type AppSidebarOptions = {
      * Workspace edge occupied by navigation.
      */
     side?: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * `'modules'` draws the top level as a module strip
+     * beside a panel showing one module's menu; minimized, the strip remains and menus open as flyouts.
+     */
+    layout?: 'tree' | 'modules';
+    /**
+     * Modules layout: the module the panel shows first.
+     * Defaults to the module containing `active`, else the first module with a panel.
+     */
+    module?: string | number | null;
+    /**
+     * Modules layout: strip presentation.
+     */
+    moduleBar?: AppSidebarModuleBarOptions;
+    /**
+     * Modules layout: how much
+     * of the navigation shows — both menus expanded (module names beside the side menu), the module
+     * menu collapsed to icons beside the side menu, or both collapsed to the icon strip. Defaults
+     * to `collapsed` ? `'collapsed'` : `'expanded'`.
+     */
+    presentation?: 'expanded' | 'compact' | 'collapsed' | null;
+    /**
+     * Modules layout: the presentations offered, widest first.
+     */
+    presentations?: Array<'expanded' | 'compact' | 'collapsed'>;
+    /**
+     * Modules layout: whether the strip's foot carries the
+     * switch between presentations. Turn it off when the choice lives elsewhere — an account menu,
+     * through `presentationChoice()`.
+     */
+    presentationSwitch?: boolean;
     /**
      * Navigation accessible label.
      */
     label?: string;
     /**
-     * Expanded header content.
+     * Expanded header content;
+     * in the modules layout, content above every module's menu.
      */
     header?: Node | string | number | {
         toElement: () => Node | null;
@@ -48,13 +111,15 @@ export type AppSidebarOptions = {
         toElement: () => Node | null;
     } | null;
     /**
-     * Minimized leading content.
+     * Minimized leading content;
+     * in the modules layout, the strip's leading content in both states.
      */
     railHeader?: Node | string | number | {
         toElement: () => Node | null;
     } | null;
     /**
-     * Minimized trailing content.
+     * Minimized trailing content;
+     * in the modules layout, the strip's trailing content in both states.
      */
     railFooter?: Node | string | number | {
         toElement: () => Node | null;
@@ -98,23 +163,71 @@ export type AppSidebarOptions = {
         id: string | number;
         open: boolean;
     }>) => void;
+    /**
+     * Preventable module-switch listener.
+     */
+    onmodulechange?: (event: CustomEvent<{
+        item: AppNavItem;
+        id: string | number;
+        previous: string | number | null;
+    }>) => void;
+    /**
+     * Presentation listener.
+     */
+    onpresentationchange?: (event: CustomEvent<{
+        presentation: 'expanded' | 'compact' | 'collapsed';
+        previous: 'expanded' | 'compact' | 'collapsed';
+    }>) => void;
 };
 /** @typedef {import('../../internal/app-rail.js').AppNavItem} AppNavItem */
 /** @typedef {import('../../internal/app-rail.js').AppNavSelectDetail} AppNavSelectDetail */
+/** @typedef {import('../module-bar/module-bar.js').ModuleItem} ModuleItem */
+/**
+ * A module in the modules layout: a `ModuleItem` whose panel may carry content of its own.
+ * @typedef {ModuleItem & {header?: Node|{toElement: () => Node|null}, content?: Node|{toElement: () => Node|null}}} AppSidebarModule
+ */
+/**
+ * Presentation of the module strip in the modules layout.
+ * @typedef {Object} AppSidebarModuleBarOptions
+ * @property {'tint'|'solid'|'plain'} [appearance='tint'] Tile treatment.
+ * @property {'auto'|'beside'|'below'|'hidden'} [labels='auto'] Module names on the strip: `'auto'`
+ *   prints them beside the tiles while expanded and leaves the icons alone while collapsed;
+ *   `'hidden'` keeps the icon strip beside the panel; `'below'` prints them under the tiles.
+ * @property {'auto'|'always'|'never'} [allModules='auto'] The "All modules" button.
+ * @property {string|null} [label=null] Strip accessible label; omitted resolves `moduleBar.label`.
+ */
 /**
  * @typedef {Object} AppSidebarOptions
- * @property {AppNavItem[]} [items=[]] Application navigation tree.
+ * @property {AppNavItem[]|AppSidebarModule[]} [items=[]] Application navigation tree; in the
+ *   modules layout its top level is the modules.
  * @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 {'tree'|'modules'} [layout='tree'] `'modules'` draws the top level as a module strip
+ *   beside a panel showing one module's menu; minimized, the strip remains and menus open as flyouts.
+ * @property {string|number|null} [module=null] Modules layout: the module the panel shows first.
+ *   Defaults to the module containing `active`, else the first module with a panel.
+ * @property {AppSidebarModuleBarOptions} [moduleBar={}] Modules layout: strip presentation.
+ * @property {'expanded'|'compact'|'collapsed'|null} [presentation=null] Modules layout: how much
+ *   of the navigation shows — both menus expanded (module names beside the side menu), the module
+ *   menu collapsed to icons beside the side menu, or both collapsed to the icon strip. Defaults
+ *   to `collapsed` ? `'collapsed'` : `'expanded'`.
+ * @property {Array<'expanded'|'compact'|'collapsed'>} [presentations=['expanded','compact','collapsed']]
+ *   Modules layout: the presentations offered, widest first.
+ * @property {boolean} [presentationSwitch=true] Modules layout: whether the strip's foot carries the
+ *   switch between presentations. Turn it off when the choice lives elsewhere — an account menu,
+ *   through `presentationChoice()`.
  * @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} [header=null] Expanded header content;
+ *   in the modules layout, content above every module's menu.
  * @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 {Node|string|number|{toElement: () => Node|null}|null} [railHeader=null] Minimized leading content;
+ *   in the modules layout, the strip's leading content in both states.
+ * @property {Node|string|number|{toElement: () => Node|null}|null} [railFooter=null] Minimized trailing content;
+ *   in the modules layout, the strip's trailing content in both states.
  * @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.
@@ -122,19 +235,24 @@ export type AppSidebarOptions = {
  * @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.
+ * @property {(event: CustomEvent<{item: AppNavItem, id: string|number, previous: string|number|null}>) => void} [onmodulechange] Preventable module-switch listener.
+ * @property {(event: CustomEvent<{presentation: 'expanded'|'compact'|'collapsed', previous: 'expanded'|'compact'|'collapsed'}>) => void} [onpresentationchange] Presentation listener.
  */
 /**
  * One application navigation component. Vertical expanded descendants render inline; minimized
- * vertical and horizontal descendants use pointer-, focus-, and keyboard-accessible flyouts.
+ * vertical and horizontal descendants use pointer-, focus-, and keyboard-accessible flyouts. The
+ * modules layout puts a `ModuleBar` of the top level beside a panel with the current module's menu.
  * @fires AppSidebar#select
  * @fires AppSidebar#branchchange
  * @fires AppSidebar#collapsechange
  * @fires AppSidebar#flyoutchange
+ * @fires AppSidebar#modulechange
+ * @fires AppSidebar#presentationchange
  * @extends {Component<AppSidebarOptions>}
  */
 export declare class AppSidebar extends Component<AppSidebarOptions> {
-    _rail: MinimizedPresenter;
-    _railExpandButton: HTMLElement;
+    _rail: MinimizedPresenter | ModuleBar;
+    _railExpandButton: HTMLButtonElement | HTMLElement;
     _createdRoot: boolean;
     _original: {
         attributes: string[][];
@@ -146,6 +264,12 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     _collapsed: boolean;
     _orientation: any;
     _side: "bottom" | "left" | "right" | "top";
+    _modules: boolean;
+    _moduleLabels: "auto" | "below" | "beside" | "hidden";
+    _compact: boolean;
+    _presentationGroup: HTMLElement;
+    _stripTooltips: any[];
+    _shownId: string | number;
     _modeAbort: AbortController;
     static cssName: string;
     /** @type {Readonly<AppSidebarOptions>} */
@@ -160,10 +284,62 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     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[]} */
+    /**
+     * Returns a copy of the normalized items. A leaf has no `children` property, as it was written,
+     * rather than the empty list normalization gives it.
+     * @returns {AppNavItem[]}
+     */
     getItems(): AppNavItem[];
-    /** Sets the active id without routing. @param {string|number|null} id @returns {this} */
+    /**
+     * Sets the active id without routing. In the modules layout the panel follows the active route
+     * into its module.
+     * @param {string|number|null} id
+     * @returns {this}
+     */
     setActive(id: string | number | null): this;
+    /**
+     * Updates one badge — a module's, or any destination's — without rebuilding the navigation.
+     * @param {string|number} id Item id.
+     * @param {string|number|null} badge New badge; null removes it.
+     * @returns {this}
+     */
+    setBadge(id: string | number, badge: string | number | null): this;
+    /**
+     * Modules layout: shows a module's menu in the panel. Fires a preventable `modulechange` unless silent.
+     * @param {string|number} id Module id.
+     * @param {{silent?: boolean}} [options={}]
+     * @returns {this}
+     */
+    setModule(id: string | number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Modules layout: the module whose menu the panel shows. @returns {string|number|null} */
+    getModule(): string | number | null;
+    /**
+     * Modules layout: whether the strip prints module names — `'auto'` (beside the tiles while
+     * expanded, none while collapsed), `'beside'`, `'below'`, or `'hidden'`. A narrow drawer that
+     * has no room for a labelled strip beside the panel sets `'hidden'`.
+     * @param {'auto'|'beside'|'below'|'hidden'} labels
+     * @returns {this}
+     */
+    setModuleLabels(labels: 'auto' | 'beside' | 'below' | 'hidden'): this;
+    /**
+     * How much of the navigation shows: `'expanded'` (in the modules layout, both menus),
+     * `'compact'` (the module menu collapsed to icons beside the side menu), or `'collapsed'`.
+     * @returns {'expanded'|'compact'|'collapsed'}
+     */
+    getPresentation(): 'expanded' | 'compact' | 'collapsed';
+    /**
+     * Shows the navigation as `'expanded'`, `'compact'` (modules layout), or `'collapsed'`.
+     * @param {'expanded'|'compact'|'collapsed'} presentation
+     * @param {{silent?: boolean}} [options={}]
+     * @returns {this}
+     */
+    setPresentation(presentation: 'expanded' | 'compact' | 'collapsed', { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Moves to the next presentation the strip's switch offers, wrapping (Mod+B in an application). @returns {this} */
+    togglePresentation(): this;
     /** Replaces expanded branch ids. @param {Array<string|number>} ids @param {{silent?: boolean}} [options={}] @returns {this} */
     setExpanded(ids: Array<string | number>, { silent }?: {
         silent?: boolean;
@@ -186,6 +362,17 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     setCollapsed(collapsed: boolean, { silent }?: {
         silent?: boolean;
     }): this;
+    /**
+     * Applies a collapsed state and, in the modules layout, whether the module menu is collapsed
+     * beside an expanded side menu; reports what changed.
+     * @param {boolean} collapsed
+     * @param {boolean} compact
+     * @param {{silent?: boolean}} options
+     * @returns {this}
+     */
+    _present(collapsed: boolean, compact: boolean, { silent }: {
+        silent?: boolean;
+    }): this;
     /** Reports the effective presentation state; horizontal navigation is always minimized. @returns {boolean} */
     isCollapsed(): boolean;
     /**
@@ -210,7 +397,7 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     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} */
+    /** Focuses the first navigation action: the module strip's Tab stop in the modules layout. @returns {this} */
     focus(): this;
     /** Destroys flyouts and restores/removes the host. @returns {void} */
     destroy(): void;
@@ -218,8 +405,81 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     _renderMode(): void;
     /** @returns {void} */
     _renderExpanded(): void;
+    /** @returns {HTMLButtonElement} The minimize control of an expanded presentation. */
+    _collapseButton(): HTMLButtonElement;
+    /** @returns {HTMLButtonElement} The expand control at the head of a minimized vertical rail. */
+    _expandButton(): HTMLButtonElement;
+    /** @param {HTMLElement} list @returns {void} */
+    _listenTree(list: HTMLElement): void;
     /** @returns {void} */
     _renderRail(): void;
+    /**
+     * The modules layout. Expanded, the strip leaves module menus to the panel beside it; minimized
+     * or horizontal, the strip is the whole navigation and menus open as flyouts.
+     * @returns {void}
+     */
+    _renderModules(): void;
+    /**
+     * The modules layout's switch between its presentations: an APG radio group of one small
+     * pictogram per presentation — both menus, the side menu beside module icons, the icons alone.
+     * Its checked option is also the collapse control while expanded and the expand control while
+     * collapsed, so focus lands on the checked option of its successor across a re-render.
+     * @param {boolean} expanded Whether the side menu shows.
+     * @returns {HTMLElement}
+     */
+    _presentationSwitch(expanded: boolean): HTMLElement;
+    /**
+     * The choice between presentations as a menu entry, for an account or settings menu that holds
+     * it instead of the strip: `account.setItems([sidebar.presentationChoice(), …])`. It reads the
+     * current presentation when called, so rebuild it after `presentationchange`.
+     * @param {{label?: string}} [options={}] Row label; omitted resolves `appSidebar.presentation`.
+     * @returns {import('../../internal/menu-items.js').MenuChoice}
+     */
+    presentationChoice({ label }?: {
+        label?: string;
+    }): import('../../internal/menu-items.js').MenuChoice;
+    /** @returns {Record<'expanded'|'compact'|'collapsed', string>} */
+    _presentationLabels(): Record<'expanded' | 'compact' | 'collapsed', string>;
+    /** Arrow keys move through the presentations and choose as they go, as in any radio group. @param {KeyboardEvent} event @returns {void} */
+    _onPresentationKeydown(event: KeyboardEvent): void;
+    /** Checks the current presentation's option and makes it the group's one Tab stop. @returns {void} */
+    _syncPresentationSwitch(): void;
+    /** @returns {Array<'expanded'|'compact'|'collapsed'>} The presentations the switch offers, widest first. */
+    _presentationCycle(): Array<'expanded' | 'compact' | 'collapsed'>;
+    /** @returns {'expanded'|'compact'|'collapsed'} */
+    _nextPresentation(): 'expanded' | 'compact' | 'collapsed';
+    /**
+     * What the strip prints for the current state: `'auto'` names the modules beside their tiles
+     * while expanded and leaves the icons alone while collapsed.
+     * @returns {'hidden'|'below'|'beside'}
+     */
+    _stripLabels(): 'hidden' | 'below' | 'beside';
+    /** @returns {AppSidebarModule[]} The modules, read through any sections that group them. */
+    _moduleList(): AppSidebarModule[];
+    /** @param {string} panelId @returns {HTMLElement} */
+    _renderPanel(panelId: string): HTMLElement;
+    /** Puts the shown module's title, header, menu, and content into the panel. @returns {void} */
+    _renderPanelContent(): void;
+    /**
+     * Shows a module's panel. Returns false when there is no such panel module or a listener
+     * prevented the switch.
+     * @param {string|number} id Module id.
+     * @param {{silent?: boolean}} [options={}]
+     * @returns {boolean}
+     */
+    _showModule(id: string | number, { silent }?: {
+        silent?: boolean;
+    }): boolean;
+    /** @param {CustomEvent<AppNavSelectDetail>} event @param {boolean} expanded @returns {void} */
+    _onModuleSelect(event: CustomEvent<AppNavSelectDetail>, expanded: boolean): void;
+    /** The arrow toward the panel shows a module's menu and moves into it. @param {KeyboardEvent} event @returns {void} */
+    _onStripKeydown(event: KeyboardEvent): void;
+    /** @returns {AppSidebarModule|null} */
+    _shownModule(): AppSidebarModule | null;
+    /** @param {string|number|null|undefined} preferred @returns {string|number|null} */
+    _resolveShown(preferred: string | number | null | undefined): string | number | null;
+    /** @returns {AppNavItem[]} The items the tree draws: the shown module's menu in the modules layout. */
+    _treeItems(): AppNavItem[];
     /**
      * Keeps a minimized rail's counts readable and audible.
      *
@@ -236,6 +496,14 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     _renderTree(): void;
     /** @param {AppNavItem} item @param {number} level @returns {HTMLElement} */
     _treeRow(item: AppNavItem, level: number): HTMLElement;
+    /**
+     * A section: a heading over rows that stay at its own level. It names its list, so a screen
+     * reader hears "Records, list, 3 items" rather than a heading floating above unrelated rows.
+     * @param {AppNavItem} item Section.
+     * @param {number} level Level its rows take.
+     * @returns {HTMLElement}
+     */
+    _sectionRow(item: AppNavItem, level: number): HTMLElement;
     /** @param {Event} event @returns {void} */
     _onTreeClick(event: Event): void;
     /** @param {KeyboardEvent} event @returns {void} */
@@ -265,7 +533,15 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     /** @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>}>} */
+/**
+ * The pictogram of a presentation: a small window with its navigation drawn in it — the module
+ * strip, wide when it is named, and the side menu when it shows. Built from boxes in the text
+ * colour, so it follows the theme and forced colours and needs no icon set. Decorative.
+ * @param {'expanded'|'compact'|'collapsed'} presentation
+ * @returns {HTMLElement}
+ */
+export declare function presentationGlyph(presentation: 'expanded' | 'compact' | 'collapsed'): HTMLElement;
 /** 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}>} */
+/** Fired when how much of the navigation shows changes. @event AppSidebar#presentationchange @type {CustomEvent<{presentation: 'expanded'|'compact'|'collapsed', previous: 'expanded'|'compact'|'collapsed'}>} */
+/** Fired before the modules layout's panel switches to another module; preventable. @event AppSidebar#modulechange @type {CustomEvent<{item: AppNavItem, id: string|number, previous: string|number|null}>} */

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

@@ -1,11 +1,12 @@
 import { Component } from '../../core/component.js';
+export type AvatarTone = 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet' | 'slate';
 export type AvatarOptions = {
     /**
      * Image URL.
      */
     src?: string | null;
     /**
-     * Name used to derive fallback initials.
+     * Name used to derive the fallback initials and tone.
      */
     name?: string;
     /**
@@ -17,13 +18,20 @@ export type AvatarOptions = {
      */
     label?: string | null;
     /**
-     * Preset (`sm`, `md`, `lg`) or pixel size.
+     * Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
+     * spacing unit — or a pixel size. Below 24px the fallback shows a single initial.
      */
     size?: string | number;
     /**
      * Avatar shape.
      */
     shape?: 'circle' | 'rounded' | 'square';
+    /**
+     * Fallback colour from the tone palette. `null` derives a
+     * stable tone from the name (or the initials when there is no name), so the same person gets the
+     * same colour on every screen; see {@link avatarTone}.
+     */
+    tone?: AvatarTone | null;
     /**
      * Optional presence state.
      */
@@ -33,19 +41,35 @@ export type AvatarOptions = {
      */
     statusLabel?: string | null;
 };
+/**
+ * A categorical tone from the design system's tone palette (`--zx-color-tone-*`).
+ * @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AvatarTone
+ */
 /**
  * @typedef {Object} AvatarOptions
  * @property {string|null} [src=null] Image URL.
- * @property {string} [name=''] Name used to derive fallback initials.
+ * @property {string} [name=''] Name used to derive the fallback initials and tone.
  * @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 {string|number} [size='md'] Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
+ * spacing unit — or a pixel size. Below 24px the fallback shows a single initial.
  * @property {'circle'|'rounded'|'square'} [shape='circle'] Avatar shape.
+ * @property {AvatarTone|null} [tone=null] Fallback colour from the tone palette. `null` derives a
+ * stable tone from the name (or the initials when there is no name), so the same person gets the
+ * same colour on every screen; see {@link avatarTone}.
  * @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.
+ * The tone palette, in hash order. Every entry is a valid `tone`; the hash picks among the
+ * chromatic ones and keeps `slate`, the neutral, for a fallback with no name behind it. Order is
+ * part of the contract: changing it moves every derived avatar to a different colour.
+ * @type {ReadonlyArray<AvatarTone>}
+ */
+export declare const AVATAR_TONES: ReadonlyArray<AvatarTone>;
+/**
+ * Stable-size user image with a deterministic fallback — initials on a tone picked from the name —
+ * and an optional presence state.
  * @extends {Component<AvatarOptions>}
  */
 export declare class Avatar extends Component<AvatarOptions> {
@@ -61,6 +85,7 @@ export declare class Avatar extends Component<AvatarOptions> {
         label: string;
         size: string | number;
         shape: "circle" | "rounded" | "square";
+        tone: AvatarTone;
         status: "away" | "busy" | "offline" | "online";
         statusLabel: string;
     };
@@ -93,8 +118,22 @@ export declare class Avatar extends Component<AvatarOptions> {
     _syncStatus(): void;
 }
 /**
- * Derives at most two uppercase initials from the first and last words of a name.
+ * Derives uppercase initials from the first and last words of a name.
  * @param {unknown} name Name-like value.
+ * @param {1|2} [limit=2] How many initials to return: two by default, one for an avatar too small
+ * to hold two legibly.
  * @returns {string}
  */
-export declare function avatarInitials(name: unknown): string;
+export declare function avatarInitials(name: unknown, limit?: 1 | 2): string;
+/**
+ * Picks a stable fallback tone for a name.
+ *
+ * The name is trimmed, NFC-normalised and lower-cased, then hashed with 32-bit FNV-1a over its
+ * UTF-16 code units, and the hash picks one of the eight chromatic tones of {@link AVATAR_TONES}.
+ * The result depends on nothing but the name — not the locale, the page, or the order avatars
+ * render in — so a person keeps their colour everywhere. An empty name is `slate`, the neutral
+ * tone, which no name hashes to.
+ * @param {unknown} name Name-like value.
+ * @returns {AvatarTone}
+ */
+export declare function avatarTone(name: unknown): AvatarTone;