@zeyos/zx 5.0.0 → 5.2.0

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>} */
@@ -166,8 +290,56 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
      * @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;
@@ -190,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;
     /**
@@ -214,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;
@@ -222,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.
      *
@@ -240,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} */
@@ -269,5 +533,15 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     /** @returns {void} */
     _reconcileExpanded(): void;
 }
+/**
+ * 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/calendar/calendar.d.ts

@@ -132,7 +132,9 @@ export type CalendarOptions = {
      */
     dateUnit?: 'milliseconds' | 'seconds';
     /**
-     * Localized component messages.
+     * Per-instance messages, keyed `calendar.*` (`calendar.today`,
+     * `calendar.next`, …). The bare keys of earlier versions (`today`, `next`) are still read, after the
+     * namespaced key, until the next major version.
      */
     msg?: Record<string, string>;
     /**
@@ -248,6 +250,68 @@ export type CalendarEventChangeDetail = {
 export type CalendarSetOptions = {
     silent?: boolean;
 };
+/** @typedef {import('./calendar-model.js').CalendarEvent} CalendarEvent */
+/** @typedef {import('./calendar-model.js').CalendarView} CalendarView */
+/** @typedef {import('./calendar-model.js').CalendarReader} CalendarReader */
+/**
+ * @typedef {Object} CalendarOptions
+ * @property {Record<string, any>[]} [events=[]] Event records.
+ * @property {Date|string|number|null} [date=null] Initial local anchor date; null uses today.
+ * @property {CalendarView} [view='month'] Initial view.
+ * @property {CalendarView[]} [views=['agenda','day','week','month','year']] Allowed views.
+ * @property {string|string[]} [locale] Intl locale override.
+ * @property {number} [weekStart=1] First weekday, 0 (Sunday) through 6 (Saturday).
+ * @property {boolean} [weekNumbers=true] Show ISO week numbers in month view.
+ * @property {boolean} [workweek=false] Show Monday–Friday in the week time grid.
+ * @property {number} [agendaDays=14] Number of days in agenda view.
+ * @property {number} [slotDuration=30] Time-grid snap interval in minutes.
+ * @property {number} [slotMinTime=0] First visible minute of the day.
+ * @property {number} [slotMaxTime=1440] Exclusive last visible minute of the day.
+ * @property {number} [scrollTime=480] Minute initially scrolled into view.
+ * @property {number} [eventLimit=3] Maximum visible month lanes before a More button.
+ * @property {boolean} [selectable=false] Enable pointer time-range selection.
+ * @property {boolean} [editable=false] Enable event moving and resizing.
+ * @property {boolean|null} [eventStartEditable=null] Global move override; null inherits editable.
+ * @property {boolean|null} [eventDurationEditable=null] Global resize override; null inherits editable.
+ * @property {boolean} [optimistic=true] Apply event proposals locally before persistence confirms.
+ * @property {boolean} [nowIndicator=true] Show the current-time line in day/week views.
+ * @property {Date|(() => Date)|null} [now=null] Current-time override for deterministic rendering.
+ * @property {boolean} [disabled=false] Disable toolbar, date, selection, and editing controls.
+ * @property {CalendarReader} [eventId='id'] Event ID reader.
+ * @property {CalendarReader} [eventTitle='title'] Event title reader.
+ * @property {CalendarReader} [eventStart='start'] Event start reader.
+ * @property {CalendarReader} [eventEnd='end'] Event end reader.
+ * @property {CalendarReader} [eventAllDay='allDay'] Event all-day reader.
+ * @property {CalendarReader} [eventColor='color'] Event colour reader.
+ * @property {CalendarReader} [eventLocation='location'] Event location reader.
+ * @property {CalendarReader} [eventEditable='editable'] Per-event move reader.
+ * @property {CalendarReader} [eventDurationEditable='durationEditable'] Per-event resize reader.
+ * @property {'milliseconds'|'seconds'} [dateUnit='milliseconds'] Unit for numeric event dates.
+ * @property {Record<string, string>} [msg] Per-instance messages, keyed `calendar.*` (`calendar.today`,
+ *   `calendar.next`, …). The bare keys of earlier versions (`today`, `next`) are still read, after the
+ *   namespaced key, until the next major version.
+ * @property {(event: CalendarEvent) => Node|string|null} [renderEvent] Optional safe event-content renderer.
+ * @property {(event: CustomEvent<{events: CalendarEvent[]}>) => void} [oneventschange] Programmatic event-data listener.
+ * @property {(event: CustomEvent<{view: CalendarView, oldView: CalendarView}>) => void} [onviewchange] View listener.
+ * @property {(event: CustomEvent<{view: CalendarView, start: Date, end: Date}>) => void} [ondateschange] Visible-range listener.
+ * @property {(event: CustomEvent<{event: CalendarEvent, jsEvent: Event}>) => void} [oneventclick] Event activation listener.
+ * @property {(event: CustomEvent<{event: CalendarEvent, jsEvent: Event}>) => void} [oneventdblclick] Event double-activation listener.
+ * @property {(event: CustomEvent<{date: Date, allDay: boolean, view: CalendarView, jsEvent: Event}>) => void} [ondateclick] Date/time activation listener.
+ * @property {(event: CustomEvent<{start: Date, end: Date, allDay: boolean, view: CalendarView, jsEvent: Event}>) => void} [onselect] Range-selection listener.
+ * @property {(event: CustomEvent<CalendarEventChangeDetail>) => void} [oneventchange] Move/resize proposal listener.
+ * @property {(event: CustomEvent<{date: Date, view: CalendarView, jsEvent: Event}>) => void} [onnew] New-event command listener.
+ * @property {(event: CustomEvent<{date: Date, count: number, jsEvent: Event}>) => void} [onmoreclick] Month-overflow listener.
+ */
+/**
+ * @typedef {Object} CalendarEventChangeDetail
+ * @property {CalendarEvent} event Proposed event.
+ * @property {CalendarEvent} oldEvent Previous event.
+ * @property {'move'|'resize'} action Edit action.
+ * @property {{milliseconds: number, days: number, minutes: number, endMilliseconds: number}} delta Edit delta.
+ * @property {Event} jsEvent Originating pointer or keyboard event.
+ * @property {() => boolean} revert Idempotent optimistic revert callback.
+ */
+/** @typedef {{silent?: boolean}} CalendarSetOptions */
 /**
  * Accessible, dependency-free agenda/day/week/month/year scheduling surface.
  * @fires Calendar#viewchange
@@ -513,10 +577,8 @@ export declare class Calendar extends Component<CalendarOptions> {
      */
     _dayCountLabel(day: Date, count: number): string;
     /**
-     * Resolves a message through the host translator, falling back to the built-in English text.
-     *
-     * Distinct from `msg()`: the built-in `msg` option answers the calendar's own vocabulary, so a
-     * dotted key falls past it to the host translator, which is what these strings never had.
+     * Resolves a message through `msg()`, falling back to the built-in English text. Redundant now
+     * that `msg()` ends in the default catalogue; kept until the private copies are removed.
      * @param {string} key Message key.
      * @param {string} fallback Built-in text, with `%1`-style placeholders.
      * @param {...unknown} args Interpolation values.

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

@@ -109,9 +109,10 @@ export type CardViewOptions = {
      */
     headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
     /**
-     * Accessible collection label.
+     * Accessible collection label; null resolves message
+     * `cardView.label`, "Card view".
      */
-    label?: string;
+    label?: string | null;
     onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
 };
 export type CardViewState = {
@@ -203,7 +204,8 @@ export type CardRecordGroup = {
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Card surface treatment.
  * @property {number} [loadingCount=6] Skeleton cards shown while loading.
  * @property {1|2|3|4|5|6} [headingLevel=3] Per-card title heading level.
- * @property {string} [label='Card view'] Accessible collection label.
+ * @property {string|null} [label=null] Accessible collection label; null resolves message
+ *   `cardView.label`, "Card view".
  * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecordaction]
  */
 /**
@@ -304,8 +306,9 @@ export declare class CardView extends RecordView {
  * @param {CardViewOptions['groupBy']} groupBy Group field or resolver.
  * @param {unknown[]} [groupOrder=[]] Preferred group ids.
  * @param {ViewField[]} [fields=[]] Complete fields for accessor-aware grouping.
+ * @param {string} [ungroupedLabel='Ungrouped'] Label of the group collecting records without a value.
  * @returns {CardRecordGroup[]} Deterministic groups.
  */
-export declare function groupCardRecords(records: ViewRecord[], groupBy: CardViewOptions['groupBy'], groupOrder?: unknown[], fields?: ViewField[]): CardRecordGroup[];
+export declare function groupCardRecords(records: ViewRecord[], groupBy: CardViewOptions['groupBy'], groupOrder?: unknown[], fields?: ViewField[], ungroupedLabel?: string): CardRecordGroup[];
 /** @param {unknown} value @returns {string} */
 export declare function normalizeCardWidth(value: unknown): string;

package/dist/types/components/card-view/record-card.d.ts

@@ -139,6 +139,13 @@ export type RecordCardOptions = {
      * Listener-free, owner-created controls such as a move handle.
      */
     controls?: Node[];
+    /**
+     * Resolves the card's built-in strings
+     * (`recordCard.select`, `recordCard.actions`, `recordCard.untitled`, `recordCard.selected`,
+     * `recordCard.notSelected`). An owning component passes its own `msg()`; omitted, the host
+     * translator and then the default English catalogue answer.
+     */
+    message?: (key: string, ...args: unknown[]) => string;
 };
 export type ResolvedRecordPreview = {
     /**
@@ -218,6 +225,10 @@ export type ResolvedRecordPreview = {
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Surface treatment.
  * @property {1|2|3|4|5|6} [headingLevel=3] Card title heading level.
  * @property {Node[]} [controls=[]] Listener-free, owner-created controls such as a move handle.
+ * @property {(key: string, ...args: unknown[]) => string} [message] Resolves the card's built-in strings
+ *   (`recordCard.select`, `recordCard.actions`, `recordCard.untitled`, `recordCard.selected`,
+ *   `recordCard.notSelected`). An owning component passes its own `msg()`; omitted, the host
+ *   translator and then the default English catalogue answer.
  */
 /**
  * @typedef {Object} ResolvedRecordPreview

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

@@ -1,6 +1,6 @@
 import { Component } from '../../core/component.js';
 export type MenuItem = import('../../internal/menu-items.js').MenuItem;
-export type ContextMenuEntry = import('../../internal/menu-items.js').MenuEntry;
+export type ContextMenuEntry = import('../../internal/menu-items.js').MenuItem | import('../../internal/menu-items.js').MenuHeading | import('../../internal/menu-items.js').MenuSeparator | '-';
 export type ContextMenuOptions = {
     /**
      * Menu
@@ -35,7 +35,11 @@ export type ContextMenuOptions = {
     onclose?: (event: CustomEvent<Record<string, never>>) => void;
 };
 /** @typedef {import('../../internal/menu-items.js').MenuItem} MenuItem */
-/** @typedef {import('../../internal/menu-items.js').MenuEntry} ContextMenuEntry */
+/**
+ * A context menu's entries: the shared menu model without `choice` rows, which a menu that closes
+ * on every activation cannot hold.
+ * @typedef {import('../../internal/menu-items.js').MenuItem|import('../../internal/menu-items.js').MenuHeading|import('../../internal/menu-items.js').MenuSeparator|'-'} ContextMenuEntry
+ */
 /**
  * @typedef {Object} ContextMenuOptions
  * @property {ContextMenuEntry[]|((context: Element|null) => ContextMenuEntry[])} [items=[]] Menu

package/dist/types/components/data-filter/data-filter.d.ts

@@ -37,7 +37,7 @@ export type SelectFilterDefinition = {
      */
     options?: Array<unknown | DataFilterOption>;
     /**
-     * Empty option label.
+     * Empty option label; omitted resolves message `dataFilter.all`, "All".
      */
     emptyLabel?: string;
 };
@@ -94,7 +94,7 @@ export type DataFilterOptions = {
      */
     autoApply?: boolean;
     /**
-     * Clear button label; null resolves `dataFilter.clear`.
+     * Clear button label; null resolves message `dataFilter.clear`, "Clear".
      */
     clearLabel?: string | null;
     onfilter?: (event: CustomEvent<DataFilterEventDetail>) => void;
@@ -118,7 +118,7 @@ export type DataFilterEventDetail = {
  * @property {Array<string|((row: DataFilterRow) => unknown)>} [fields] Row fields combined with OR.
  * @property {(row: DataFilterRow) => unknown} [get] Custom value accessor.
  * @property {Array<unknown|DataFilterOption>} [options] Explicit options; omitted derives distinct values.
- * @property {string} [emptyLabel] Empty option label.
+ * @property {string} [emptyLabel] Empty option label; omitted resolves message `dataFilter.all`, "All".
  */
 /**
  * @typedef {Object} TextFilterDefinition
@@ -142,7 +142,7 @@ export type DataFilterEventDetail = {
  * @property {FilterDefinition[]} [filters=[]] Declarative filters.
  * @property {DataFilterRow[]} [data=[]] Rows to filter.
  * @property {boolean} [autoApply=true] Apply and emit whenever a control changes.
- * @property {string|null} [clearLabel=null] Clear button label; null resolves `dataFilter.clear`.
+ * @property {string|null} [clearLabel=null] Clear button label; null resolves message `dataFilter.clear`, "Clear".
  * @property {(event: CustomEvent<DataFilterEventDetail>) => void} [onfilter]
  */
 /** @typedef {{rows: DataFilterRow[], state: Record<string, unknown>}} DataFilterEventDetail */