@zeyos/zx 4.3.0 → 4.4.0

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

@@ -0,0 +1,351 @@
+import { Component } from '../../core/component.js';
+import { Avatar } from '../avatar/avatar.js';
+export type ActivityContent = string | number | Node | Component | null;
+export type AvatarOptions = import('../avatar/avatar.js').AvatarOptions;
+export type ActivityAvatar = AvatarOptions | Element | null;
+export type ActivityAction = {
+    /**
+     * Stable action identifier.
+     */
+    id: string | number;
+    /**
+     * Visible label.
+     */
+    label?: string;
+    /**
+     * Icon name.
+     */
+    icon?: string | null;
+    /**
+     * Optional safe native-link destination.
+     */
+    href?: string | null;
+    /**
+     * Native browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+    /**
+     * Native title and icon-only accessible label.
+     */
+    title?: string;
+    /**
+     * Whether the action is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Host-owned activation callback.
+     */
+    onselect?: (event: MouseEvent) => void;
+};
+export type ActivityActionSlot = Element | ActivityAction;
+export type NormalizedActivityAction = {
+    /**
+     * Stable action identifier.
+     */
+    id: string;
+    /**
+     * Visible label.
+     */
+    label: string;
+    /**
+     * Icon name.
+     */
+    icon: string | null;
+    /**
+     * Safe native-link destination.
+     */
+    href: string | null;
+    /**
+     * Native browsing context.
+     */
+    target: string | undefined;
+    /**
+     * Native link relationship.
+     */
+    rel: string | undefined;
+    /**
+     * Native title.
+     */
+    title: string | undefined;
+    /**
+     * Whether the action is unavailable.
+     */
+    disabled: boolean;
+    /**
+     * Visual intent.
+     */
+    kind: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Host callback.
+     */
+    onselect: ((event: MouseEvent) => void) | undefined;
+};
+export type ActivityTime = {
+    /**
+     * Machine-readable ISO timestamp when valid.
+     */
+    dateTime: string | null;
+    /**
+     * Human-readable timestamp.
+     */
+    label: string;
+};
+export type ActivityState = 'default' | 'pending' | 'failed';
+export type ActivityStateDescriptor = {
+    /**
+     * Resolved state.
+     */
+    state: ActivityState;
+    /**
+     * Whether the entry is still waiting on its request.
+     */
+    busy: boolean;
+    /**
+     * Message key for the built-in word, or null when no badge is shown.
+     */
+    key: string | null;
+    /**
+     * Built-in English word, or null when no badge is shown.
+     */
+    fallback: string | null;
+    /**
+     * Badge intent.
+     */
+    kind: 'neutral' | 'danger';
+    /**
+     * Host-supplied word replacing the built-in one.
+     */
+    label: string | null;
+};
+export type ActivityItemOptions = {
+    /**
+     * Host-owned activity identifier.
+     */
+    id?: unknown;
+    /**
+     * Actor identity text or presentation slot.
+     */
+    actor?: ActivityContent;
+    /**
+     * Avatar descriptor or host-owned avatar element.
+     */
+    avatar?: ActivityAvatar;
+    /**
+     * Activity summary.
+     */
+    title?: ActivityContent;
+    /**
+     * Optional body slot.
+     */
+    content?: ActivityContent;
+    /**
+     * Date, parseable date string, or epoch milliseconds.
+     */
+    timestamp?: Date | string | number | null;
+    /**
+     * Explicit human-readable timestamp.
+     */
+    timeLabel?: string | null;
+    /**
+     * Compact metadata slots.
+     */
+    metadata?: ActivityContent[];
+    /**
+     * Attachment presentation slots, commonly FileItem elements.
+     */
+    attachments?: ActivityContent[];
+    /**
+     * Native action descriptors or host-owned controls.
+     */
+    actions?: ActivityActionSlot[];
+    /**
+     * Product-neutral activity kind exposed as `data-kind`.
+     */
+    kind?: string;
+    /**
+     * Delivery state exposed as `data-state`.
+     */
+    state?: ActivityState;
+    /**
+     * Word shown in the state badge instead of the built-in one.
+     */
+    stateLabel?: string | null;
+    /**
+     * Semantic heading level for the activity summary.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    onaction?: (event: CustomEvent<{
+        id: string;
+        action: NormalizedActivityAction;
+        event: MouseEvent;
+    }>) => void;
+};
+/** @typedef {string|number|Node|Component|null} ActivityContent */
+/** @typedef {import('../avatar/avatar.js').AvatarOptions} AvatarOptions */
+/** @typedef {AvatarOptions|Element|null} ActivityAvatar */
+/**
+ * @typedef {Object} ActivityAction
+ * @property {string|number} id Stable action identifier.
+ * @property {string} [label=''] Visible label.
+ * @property {string|null} [icon=null] Icon name.
+ * @property {string|null} [href=null] Optional safe native-link destination.
+ * @property {string} [target] Native browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {string} [title] Native title and icon-only accessible label.
+ * @property {boolean} [disabled=false] Whether the action is unavailable.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='ghost'] Visual intent.
+ * @property {(event:MouseEvent)=>void} [onselect] Host-owned activation callback.
+ */
+/** @typedef {Element|ActivityAction} ActivityActionSlot */
+/**
+ * @typedef {Object} NormalizedActivityAction
+ * @property {string} id Stable action identifier.
+ * @property {string} label Visible label.
+ * @property {string|null} icon Icon name.
+ * @property {string|null} href Safe native-link destination.
+ * @property {string|undefined} target Native browsing context.
+ * @property {string|undefined} rel Native link relationship.
+ * @property {string|undefined} title Native title.
+ * @property {boolean} disabled Whether the action is unavailable.
+ * @property {'default'|'primary'|'danger'|'ghost'} kind Visual intent.
+ * @property {((event:MouseEvent)=>void)|undefined} onselect Host callback.
+ */
+/**
+ * @typedef {Object} ActivityTime
+ * @property {string|null} dateTime Machine-readable ISO timestamp when valid.
+ * @property {string} label Human-readable timestamp.
+ */
+/** @typedef {'default'|'pending'|'failed'} ActivityState Delivery state of one entry. */
+/**
+ * @typedef {Object} ActivityStateDescriptor
+ * @property {ActivityState} state Resolved state.
+ * @property {boolean} busy Whether the entry is still waiting on its request.
+ * @property {string|null} key Message key for the built-in word, or null when no badge is shown.
+ * @property {string|null} fallback Built-in English word, or null when no badge is shown.
+ * @property {'neutral'|'danger'} kind Badge intent.
+ * @property {string|null} label Host-supplied word replacing the built-in one.
+ */
+/**
+ * @typedef {Object} ActivityItemOptions
+ * @property {unknown} [id=null] Host-owned activity identifier.
+ * @property {ActivityContent} [actor=''] Actor identity text or presentation slot.
+ * @property {ActivityAvatar} [avatar=null] Avatar descriptor or host-owned avatar element.
+ * @property {ActivityContent} [title=''] Activity summary.
+ * @property {ActivityContent} [content=null] Optional body slot.
+ * @property {Date|string|number|null} [timestamp=null] Date, parseable date string, or epoch milliseconds.
+ * @property {string|null} [timeLabel=null] Explicit human-readable timestamp.
+ * @property {ActivityContent[]} [metadata=[]] Compact metadata slots.
+ * @property {ActivityContent[]} [attachments=[]] Attachment presentation slots, commonly FileItem elements.
+ * @property {ActivityActionSlot[]} [actions=[]] Native action descriptors or host-owned controls.
+ * @property {string} [kind='default'] Product-neutral activity kind exposed as `data-kind`.
+ * @property {ActivityState} [state='default'] Delivery state exposed as `data-state`.
+ * @property {string|null} [stateLabel=null] Word shown in the state badge instead of the built-in one.
+ * @property {1|2|3|4|5|6} [headingLevel=3] Semantic heading level for the activity summary.
+ * @property {(event:CustomEvent<{id:string,action:NormalizedActivityAction,event:MouseEvent}>)=>void} [onaction]
+ */
+/**
+ * One chronological activity entry with safe content slots, timestamp semantics, and native
+ * actions. Posting, reactions, routing, permissions, persistence, and content sanitization remain
+ * host responsibilities; server HTML is never interpreted by this component.
+ *
+ * @fires ActivityItem#action
+ * @extends {Component<ActivityItemOptions>}
+ */
+export declare class ActivityItem extends Component<ActivityItemOptions> {
+    _createdRoot: boolean;
+    _original: import("../../core/dom.js").TargetSnapshot;
+    _cleaned: boolean;
+    _headingId: string;
+    _avatarComponent: Avatar;
+    _actionsByKey: Map<any, any>;
+    _activity: ActivityItemOptions;
+    static cssName: string;
+    /** @type {Readonly<ActivityItemOptions>} */
+    static defaults: Readonly<ActivityItemOptions>;
+    /**
+     * Creates or enhances an activity item.
+     * @param {Element|string|null} [target=null] Existing list item/container, selector, or null.
+     * @param {ActivityItemOptions} [options={}] Activity presentation options.
+     */
+    constructor(target?: Element | string | null, options?: ActivityItemOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces any subset of the activity presentation.
+     * @param {Partial<ActivityItemOptions>} values New values.
+     * @returns {this}
+     */
+    setActivity(values?: Partial<ActivityItemOptions>): this;
+    /** Returns a shallow, host-safe copy of the current descriptor. @returns {ActivityItemOptions} */
+    getActivity(): ActivityItemOptions;
+    /** Restores an enhanced target exactly, or removes an owned item. @returns {void} */
+    destroy(): void;
+    /** @private @returns {void} */
+    private _renderActivity;
+    /**
+     * Builds the delivery badge, or nothing for an ordinary entry.
+     * @private
+     * @param {ActivityStateDescriptor} state Resolved state.
+     * @returns {HTMLElement|null}
+     */
+    private _createStateBadge;
+    /** @private @param {ActivityAvatar} value @param {ActivityContent} actor @returns {Element|null} */
+    private _createAvatar;
+    /** @private @param {ActivityActionSlot[]} value @returns {HTMLElement|null} */
+    private _createActions;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
+    /** @private @param {MouseEvent} event @returns {void} */
+    private _onClick;
+}
+/**
+ * Normalizes action descriptors without mutating the caller's array or objects. Invalid entries
+ * and duplicate descriptor IDs are discarded; host-owned Elements pass through unchanged.
+ * @param {unknown} value Candidate action array.
+ * @returns {Array<Element|NormalizedActivityAction>}
+ */
+export declare function resolveActivityActions(value: unknown): Array<Element | NormalizedActivityAction>;
+/**
+ * Normalizes one action descriptor and rejects unsafe native destinations.
+ * @param {unknown} value Candidate action.
+ * @returns {NormalizedActivityAction|null}
+ */
+export declare function normalizeActivityAction(value: unknown): NormalizedActivityAction | null;
+/**
+ * Resolves the delivery state of one entry.
+ *
+ * `failed` is a first-class state and not the absence of `pending`: an optimistic entry that
+ * simply disappears when its request fails tells the customer their message was sent when nobody
+ * was told, so the component keeps the entry and says what happened to it.
+ * @param {unknown} state Requested state.
+ * @param {unknown} stateLabel Host-supplied word replacing the built-in one.
+ * @returns {ActivityStateDescriptor}
+ */
+export declare function resolveActivityState(state: unknown, stateLabel: unknown): ActivityStateDescriptor;
+/**
+ * Resolves a timestamp for native `<time>` markup without treating invalid input as a real date.
+ * @param {Date|string|number|null|undefined} timestamp Date-like value.
+ * @param {string|null|undefined} timeLabel Explicit display label.
+ * @returns {ActivityTime|null}
+ */
+export declare function normalizeActivityTimestamp(timestamp: Date | string | number | null | undefined, timeLabel: string | null | undefined): ActivityTime | null;
+/**
+ * Activity action selected before the host callback or native navigation runs. Cancellation from
+ * either the component event or bubbling `zx-action` event prevents both callback and navigation.
+ * @event ActivityItem#action
+ * @type {CustomEvent<{id:string,action:NormalizedActivityAction,event:MouseEvent}>}
+ */

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

@@ -0,0 +1,195 @@
+import { Component } from '../../core/component.js';
+export type ActivityItemOptions = import('../activity-item/activity-item.js').ActivityItemOptions;
+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 ActivityGroup = {
+    /**
+     * Group identity returned by the configured reader.
+     */
+    id: unknown;
+    /**
+     * Activities in stable source order.
+     */
+    items: ActivityItemOptions[];
+};
+export type ActivityListOptions = {
+    /**
+     * Initial activities in host-supplied chronological order.
+     */
+    items?: ActivityItemOptions[];
+    /**
+     * Property or resolver used for stable grouping.
+     */
+    groupBy?: ActivityGroupReader;
+    /**
+     * Group-heading renderer.
+     */
+    groupLabel?: ActivityGroupLabel | null;
+    /**
+     * Accessible collection name.
+     */
+    label?: string;
+    /**
+     * Whether initial or incremental activity is loading.
+     */
+    loading?: boolean;
+    /**
+     * Placeholder rows shown for an empty loading list.
+     */
+    loadingCount?: number;
+    /**
+     * Loading status text.
+     */
+    loadingText?: string;
+    /**
+     * Empty-state content.
+     */
+    emptyText?: ActivityListContent;
+    /**
+     * Semantic group-heading level.
+     */
+    groupHeadingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Default item-heading level.
+     */
+    itemHeadingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    ondatachange?: (event: CustomEvent<{
+        items: ActivityItemOptions[];
+    }>) => void;
+};
+/** @typedef {import('../activity-item/activity-item.js').ActivityItemOptions} ActivityItemOptions */
+/** @typedef {string|number|Node|Component|null} ActivityListContent */
+/** @typedef {string|((item:ActivityItemOptions,index:number)=>unknown)|null} ActivityGroupReader */
+/** @typedef {(group:unknown,items:ActivityItemOptions[])=>ActivityListContent} ActivityGroupLabel */
+/**
+ * @typedef {Object} ActivityGroup
+ * @property {unknown} id Group identity returned by the configured reader.
+ * @property {ActivityItemOptions[]} items Activities in stable source order.
+ */
+/**
+ * @typedef {Object} ActivityListOptions
+ * @property {ActivityItemOptions[]} [items=[]] Initial activities in host-supplied chronological order.
+ * @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 {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.
+ * @property {ActivityListContent} [emptyText='No activity yet'] Empty-state content.
+ * @property {1|2|3|4|5|6} [groupHeadingLevel=2] Semantic group-heading level.
+ * @property {1|2|3|4|5|6} [itemHeadingLevel=3] Default item-heading level.
+ * @property {(event:CustomEvent<{items:ActivityItemOptions[]}>)=>void} [ondatachange]
+ */
+/**
+ * Accessible chronological activity collection with stable grouping, loading/empty states, and
+ * incremental update methods. Ordering stays host-controlled so paginated and live server results
+ * are never silently re-sorted. Item `zx-action` events bubble through the list naturally.
+ *
+ * @fires ActivityList#datachange
+ * @extends {Component<ActivityListOptions>}
+ */
+export declare class ActivityList extends Component<ActivityListOptions> {
+    _createdRoot: boolean;
+    _original: import("../../core/dom.js").TargetSnapshot;
+    _cleaned: boolean;
+    _items: any;
+    _loading: any;
+    _itemComponents: any[];
+    _groupSequence: number;
+    static cssName: string;
+    /** @type {Readonly<ActivityListOptions>} */
+    static defaults: Readonly<ActivityListOptions>;
+    /**
+     * Creates or enhances an activity collection.
+     * @param {Element|string|null} [target=null] Existing container, selector, or null.
+     * @param {ActivityListOptions} [options={}] Collection options.
+     */
+    constructor(target?: Element | string | null, options?: ActivityListOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces all activities.
+     * @param {ActivityItemOptions[]} items Activities in desired chronological order.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setItems(items: ActivityItemOptions[], options?: {
+        silent?: boolean;
+    }): this;
+    /** Returns shallow descriptor copies in current display order. @returns {ActivityItemOptions[]} */
+    getItems(): ActivityItemOptions[];
+    /** Returns a shallow descriptor copy by stable host ID. @param {unknown} id @returns {ActivityItemOptions|null} */
+    getItem(id: unknown): ActivityItemOptions | null;
+    /**
+     * Adds activities after the current source order for older-page or forward-stream updates.
+     * @param {ActivityItemOptions|ActivityItemOptions[]} items New activities.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    appendItems(items: ActivityItemOptions | ActivityItemOptions[], options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Adds activities before the current source order for newest-first live updates.
+     * @param {ActivityItemOptions|ActivityItemOptions[]} items New activities.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    prependItems(items: ActivityItemOptions | ActivityItemOptions[], options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Patches the first activity whose ID is `Object.is`-equal to the requested ID.
+     * @param {unknown} id Stable host identifier.
+     * @param {Partial<ActivityItemOptions>} values Replacement fields.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    updateItem(id: unknown, values: Partial<ActivityItemOptions>, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Removes the first activity whose ID is `Object.is`-equal to the requested ID.
+     * @param {unknown} id Stable host identifier.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    removeItem(id: unknown, options?: {
+        silent?: boolean;
+    }): this;
+    /** Sets initial/incremental loading presentation. @param {boolean} loading @returns {this} */
+    setLoading(loading: boolean): this;
+    /** Restores an enhanced target exactly, or removes an owned list. @returns {void} */
+    destroy(): void;
+    /** @private @returns {void} */
+    private _renderList;
+    /** @private @param {ActivityGroup} group @param {boolean} grouped @returns {HTMLElement} */
+    private _createGroup;
+    /** @private @param {boolean} placeholders @returns {HTMLElement} */
+    private _createLoading;
+    /** @private @returns {void} */
+    private _destroyItems;
+    /** @private @returns {void} */
+    private _emitDataChange;
+}
+/**
+ * Groups descriptors in first-seen group order while preserving source order within every group.
+ * A null reader returns one ungrouped collection. Neither descriptors nor the input array mutate.
+ * @param {ActivityItemOptions[]} items Activity descriptors.
+ * @param {ActivityGroupReader} groupBy Group reader.
+ * @returns {ActivityGroup[]}
+ */
+export declare function groupActivityItems(items: ActivityItemOptions[], groupBy?: ActivityGroupReader): ActivityGroup[];
+/**
+ * Validates and shallow-clones activity descriptors, including each slot array. Explicit
+ * duplicate IDs are rejected while id-less entries remain valid.
+ * @param {unknown} value Candidate descriptor array.
+ * @returns {ActivityItemOptions[]}
+ */
+export declare function normalizeActivityItems(value: unknown): ActivityItemOptions[];
+/**
+ * Activity descriptors changed through a list mutation method.
+ * @event ActivityList#datachange
+ * @type {CustomEvent<{items:ActivityItemOptions[]}>}
+ */

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

@@ -220,6 +220,16 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     _renderExpanded(): void;
     /** @returns {void} */
     _renderRail(): void;
+    /**
+     * Keeps a minimized rail's counts readable and audible.
+     *
+     * A rail destination is icon-only, so its accessible name is the label alone and the badge the
+     * expanded tree showed as text is announced by nothing. Here the figure is folded back into the
+     * name, and `data-zx-badge` tells the stylesheet whether the count still fits the target or has
+     * to be drawn as a dot. Presentation only: no item, option, event, or listener is touched.
+     * @returns {void}
+     */
+    _decorateRail(): void;
     /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
     _listenMode(target: EventTarget, type: string, listener: EventListener): void;
     /** @returns {void} */
@@ -234,6 +244,24 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
     _select(item: AppNavItem, event: Event): void;
     /** @returns {void} */
     _syncActive(): void;
+    /**
+     * Flags the sublist a branch toggle just opened so the stylesheet can animate that one branch.
+     *
+     * `_renderTree()` rebuilds every row on every toggle, so a transition declared on the sublist
+     * alone would replay on branches that never moved. The attribute is written after the rebuild
+     * and disappears with the element on the next one, which is why it needs no teardown.
+     * @param {string} key Branch id as a string.
+     * @returns {void}
+     */
+    _markBranchMotion(key: string): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
     /** @returns {void} */
     _reconcileExpanded(): void;
 }

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

@@ -1,3 +1,7 @@
+export type ButtonShortcut = {
+    label: string;
+    keys: string;
+};
 export type ButtonOptions = {
     /**
      * Visible button label.
@@ -23,6 +27,10 @@ export type ButtonOptions = {
      * Native title text.
      */
     title?: string;
+    /**
+     * Keyboard hint; does not register a keyboard handler.
+     */
+    shortcut?: ButtonShortcut;
     /**
      * Click callback.
      */

package/dist/types/components/calendar/calendar-model.d.ts

@@ -128,6 +128,28 @@ export declare function calendarRange(view: CalendarView, anchor: Date, options?
     start: Date;
     end: Date;
 };
+/**
+ * Returns the anchor date one visible period away from `anchor`.
+ *
+ * Month and year steps clamp the day of month into the target month instead of letting it
+ * overflow: `setMonth()` alone turns 31 January into 3 March, which makes February unreachable
+ * from a month-end anchor and leaves `prev()` on 31 March landing back inside March.
+ * @param {CalendarView} view Current view.
+ * @param {Date} anchor Current anchor date.
+ * @param {number} direction -1 for the previous period, 1 for the next.
+ * @param {{agendaDays?: number}} [options={}] Paging options.
+ * @returns {Date}
+ */
+export declare function calendarPageDate(view: CalendarView, anchor: Date, direction: number, options?: {
+    agendaDays?: number;
+}): Date;
+/**
+ * Adds whole months, clamping the day of month to the last day the target month actually has.
+ * @param {Date} value Local date.
+ * @param {number} months Months to add.
+ * @returns {Date}
+ */
+export declare function addCalendarMonths(value: Date, months: number): Date;
 /**
  * Normalizes caller records atomically into the Calendar event contract.
  * @param {Record<string, any>[]} records Source records.

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

@@ -504,6 +504,25 @@ export declare class Calendar extends Component<CalendarOptions> {
     _refreshNowIndicator(): void;
     /** @param {string} message @returns {void} */
     _announce(message: string): void;
+    /**
+     * Names a month or year cell by its date and how many events it holds. Singular and plural are
+     * separate keys because a language that inflects the noun cannot reach it from one template.
+     * @param {Date} day Day the cell stands for.
+     * @param {number} count Events on that day.
+     * @returns {string}
+     */
+    _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.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
 }
 /** @event Calendar#viewchange @type {CustomEvent<{view: CalendarView, oldView: CalendarView}>} */
 /** @event Calendar#dateschange @type {CustomEvent<{view: CalendarView, start: Date, end: Date}>} */

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

@@ -125,4 +125,11 @@ export declare class Card extends Component<CardOptions> {
     _renderHeading(): void;
     /** @returns {void} */
     _syncHeader(): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }