@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/conversation-item/conversation-item.js

@@ -0,0 +1,331 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing, svg } from 'lit';
+import { property, state, query } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { styles } from './conversation-item.styles.js';
+// Mirrors the shared icon set's viewBox/stroke conventions
+// (internal/icons.ts's chevronIcon()/closeIcon()/etc.) without adding a
+// pencil/edit glyph to that module -- it's off limits here -- so this
+// one-off icon still reads as part of the same visual language as the rest
+// of the library's inline icons. Same approach lyra-checkbox's own local
+// checkmark/indeterminate glyphs and lyra-chat-message's local retryIcon()
+// take for the identical reason.
+const ICON_VIEW_BOX = '0 0 24 24';
+const ICON_STROKE_WIDTH = '1.75';
+function pencilIcon() {
+    return svg `
+    <svg
+      width="1em"
+      height="1em"
+      viewBox=${ICON_VIEW_BOX}
+      fill="none"
+      stroke="currentColor"
+      stroke-width=${ICON_STROKE_WIDTH}
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    ><path d="M12 20h9"></path><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4Z"></path></svg>
+  `;
+}
+/** `Intl.DateTimeFormat`-based absolute formatter -- clock time ("3:45 PM")
+ *  for a timestamp that falls on the same calendar day as `now`, otherwise a
+ *  calendar date ("Jul 10", or "Jul 10, 2024" once it's not the current
+ *  year). Deliberately not a fuzzy "2 hours ago" relative string -- bucketed
+ *  relative time (grouping a whole history list into "Today"/"Yesterday"/
+ *  "Last 7 days" sections) is a separate, later-phase concern at the list
+ *  level, not this single row's job. `formatTimestamp` overrides this
+ *  entirely, mirroring `<lyra-chat-message>`'s identical override hook. */
+function defaultFormatTimestamp(date, now = new Date()) {
+    const sameDay = date.toDateString() === now.toDateString();
+    if (sameDay) {
+        return new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit' }).format(date);
+    }
+    const sameYear = date.getFullYear() === now.getFullYear();
+    return new Intl.DateTimeFormat(undefined, sameYear ? { month: 'short', day: 'numeric' } : { month: 'short', day: 'numeric', year: 'numeric' }).format(date);
+}
+/**
+ * `<lyra-conversation-item>` — a selectable row representing one chat
+ * session in a history sidebar list. Usable standalone or as the
+ * `renderItem()` payload of a sibling virtualized-list component; this
+ * module has no dependency on that (or any) other component.
+ *
+ * Takes `title`/`excerpt`/`timestamp` as individual primitive props rather
+ * than one opaque bound object, deliberately consistent with how
+ * `<lyra-chat-message>` takes individual props instead of a single
+ * `.message` blob -- every other component in this family follows that
+ * shape, so this one does too even though a single bound `.session` object
+ * would also have been a reasonable design.
+ *
+ * Identifying *which* session a `lyra-select` click/keypress was about: this
+ * reuses the platform's own `id` attribute (every element already has one)
+ * rather than inventing a second, differently-named id-carrying prop --
+ * consumers already have the event's `target`/`currentTarget` (and thus
+ * `.id`), the same reasoning `<lyra-attachment-chip>` documents for its own
+ * identically-shaped choice. `lyra-select` therefore carries no detail
+ * payload at all.
+ *
+ * `role="button"` on `[part="option"]` so the item has valid semantics both
+ * standalone and when placed in a larger history-list layout. A conversation
+ * row activates one current session; it is not itself a listbox option and
+ * therefore does not require a particular owner role.
+ *
+ * `role="button"` forbids focusable
+ * descendants -- verified against axe-core's `nested-interactive` rule,
+ * which flags it. That's why the rename button and the `actions` slot are
+ * rendered as DOM *siblings* of `[part="option"]` (both inside
+ * `[part="base"]`) rather than nested inside it: `[part="option"]` only ever
+ * contains plain text/`<time>` content. The in-place rename `<input>` is the
+ * same problem one level deeper -- it replaces the title *inside*
+ * `[part="option"]` while renaming -- so `[part="option"]` sheds its
+ * `role`/`tabindex`/`aria-current`/`aria-label` entirely for the duration
+ * of an edit. A row mid-edit is a text field, so suspending the button
+ * semantics is also the more accurate
+ * description of what's on screen.
+ *
+ * Inline rename is a dedicated pencil/edit icon button (not a double-click
+ * on the title) -- double-click has no keyboard/screen-reader equivalent
+ * and would silently swallow the row's own single-click `lyra-select`,
+ * whereas a button is independently focusable, has its own accessible name,
+ * and composes cleanly with click-to-select.
+ *
+ * @customElement lyra-conversation-item
+ * @slot actions - Overflow/icon-button controls (e.g. a future pin/delete
+ * button) rendered at the trailing edge of the row. `lyra-menu` doesn't
+ * exist yet in this phase, so this is a plain slot for whatever a consumer
+ * wants to put there today.
+ * @event lyra-select - The row was activated: a click on `[part="option"]`
+ * (i.e. outside the rename button and the `actions` slot), or Enter/Space
+ * while it's focused -- in both cases only while not currently renaming. No
+ * detail payload -- see the class doc's "Identifying which session" note.
+ * @event lyra-rename - An in-place rename was committed (Enter, or blur
+ * while editing). `detail: { title }`. Does not mutate `title` itself --
+ * this is a controlled component, the same convention
+ * `<lyra-chat-message>` follows by not clearing its own state on retry; the
+ * consumer applies the new title once it's actually persisted. Not fired
+ * when the trimmed draft is empty or unchanged from the original `title`
+ * (that's treated as an implicit cancel).
+ * @csspart base - The outer row wrapper (plain, no ARIA role) laying out `[part="option"]`, the rename button, and `actions`.
+ * @csspart option - The selectable region (`role="button"`, removed while renaming -- see the class doc). Wraps `content` and `timestamp`.
+ * @csspart content - Wrapper around the title and excerpt.
+ * @csspart title - The title text, shown while not renaming.
+ * @csspart title-input - The in-place rename `<input>`, shown only while renaming.
+ * @csspart rename-button - The pencil/edit affordance that starts a rename (only rendered while `editable` and not already renaming).
+ * @csspart excerpt - The last-message preview snippet. Only rendered when `excerpt` is non-empty.
+ * @csspart timestamp - The formatted `timestamp`, rendered in a `<time>` element. Only rendered when `timestamp` is set and valid.
+ * @csspart actions - The wrapper around the `actions` slot.
+ */
+export class LyraConversationItem extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The session's display title. */
+        this.title = '';
+        /** A short preview snippet of the last message. Omit for no excerpt line. */
+        this.excerpt = '';
+        /** Whether this is the currently-selected/open session. Drives the
+         *  brand-quiet background treatment. */
+        this.active = false;
+        /** Whether inline-rename is available at all. When `false`, the rename
+         *  button never renders and the row can never enter its editing state. If
+         *  flipped to `false` while a rename is already open, the in-progress edit
+         *  is cancelled (discarded, like Escape) rather than left committable. */
+        this.editable = true;
+        this.renaming = false;
+        this.draftTitle = '';
+        this.hasActionsSlot = false;
+        this.onOptionClick = () => {
+            // While renaming, `[part="option"]` has no role/selection semantics
+            // (see the class doc) -- a click inside it (e.g. to place the caret in
+            // the input) must not also select the row.
+            if (this.renaming)
+                return;
+            this.select();
+        };
+        this.onOptionKeyDown = (e) => {
+            if (this.renaming)
+                return;
+            if (e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar') {
+                // Space would otherwise scroll the page, same as lyra-checkbox/lyra-switch.
+                e.preventDefault();
+                this.select();
+            }
+        };
+        this.onRenameButtonClick = () => {
+            // No stopPropagation() needed here: the rename button is a DOM sibling
+            // of `[part="option"]` (see the class doc), not a descendant of it, so
+            // this click was never going to reach onOptionClick's listener anyway.
+            this.startRename();
+        };
+        this.onTitleInputChange = (e) => {
+            this.draftTitle = e.target.value;
+        };
+        this.onTitleInputKeyDown = (e) => {
+            // The input is a descendant of `[part="option"]` (unlike the rename
+            // button/actions slot, which are siblings of it) -- its keydown would
+            // otherwise bubble into onOptionKeyDown above. Stopping it here avoids a
+            // race where commitRename() (called below) has already flipped
+            // `renaming` back to `false` by the time that bubbled event reaches
+            // onOptionKeyDown's own `if (this.renaming) return;` guard, which would
+            // otherwise wrongly let the same Enter keystroke also fire lyra-select.
+            e.stopPropagation();
+            if (e.key === 'Enter') {
+                e.preventDefault();
+                this.commitRename();
+            }
+            else if (e.key === 'Escape') {
+                e.preventDefault();
+                this.cancelRename();
+            }
+        };
+        this.onTitleInputBlur = () => {
+            // If Escape already ended the edit synchronously (cancelRename() runs
+            // before this fires), `renaming` is already false by the time the
+            // now-removed input's blur event reaches here -- skip so Escape can't
+            // also commit.
+            if (!this.renaming)
+                return;
+            this.commitRename();
+        };
+        this.onActionsSlotChange = (e) => {
+            this.hasActionsSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate(changed) {
+        if (!this.hasUpdated) {
+            this.hasActionsSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'actions');
+        }
+        // `editable` documents that flipping it false can never leave a rename
+        // committable -- without this, toggling it mid-edit would strand the
+        // input mounted (and still submittable via Enter/blur) since nothing
+        // else observes `editable` while `renaming` is already true.
+        if (changed.has('editable') && !this.editable && this.renaming) {
+            this.cancelRename();
+        }
+    }
+    updated(changed) {
+        if (changed.has('renaming') && this.renaming) {
+            // Runs after render, so the input already exists in the DOM.
+            this.titleInput?.focus();
+            this.titleInput?.select();
+        }
+    }
+    get normalizedTimestamp() {
+        if (this.timestamp === undefined)
+            return undefined;
+        const date = this.timestamp instanceof Date ? this.timestamp : new Date(this.timestamp);
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
+    select() {
+        this.emit('lyra-select');
+    }
+    startRename() {
+        if (!this.editable || this.renaming)
+            return;
+        this.draftTitle = this.title;
+        this.renaming = true;
+    }
+    commitRename() {
+        this.renaming = false;
+        const next = this.draftTitle.trim();
+        // An empty or unchanged draft has nothing meaningful to commit -- treat
+        // it the same as Escape rather than firing a no-op (or blanking) rename
+        // for the consumer to deal with.
+        if (!next || next === this.title)
+            return;
+        this.emit('lyra-rename', { title: next });
+    }
+    cancelRename() {
+        this.renaming = false;
+    }
+    render() {
+        const ts = this.normalizedTimestamp;
+        const formatter = this.formatTimestamp ?? defaultFormatTimestamp;
+        const displayTitle = this.title || 'Untitled conversation';
+        const showRenameButton = this.editable && !this.renaming;
+        // Shared between the rename button and the input it opens: the input is
+        // where focus actually lands, so it needs the same row-specific
+        // accessible name (not a generic one) to disambiguate which row a
+        // screen-reader user is editing.
+        const renameLabel = `Rename ${displayTitle}`;
+        return html `
+      <div part="base">
+        <div
+          part="option"
+          role=${this.renaming ? nothing : 'button'}
+          tabindex=${this.renaming ? nothing : '0'}
+          aria-current=${this.renaming || !this.active ? nothing : 'true'}
+          aria-label=${this.renaming ? nothing : this.getAttribute('aria-label') || displayTitle}
+          @click=${this.onOptionClick}
+          @keydown=${this.onOptionKeyDown}
+        >
+          <div part="content">
+            ${this.renaming
+            ? html `<input
+                  part="title-input"
+                  type="text"
+                  .value=${this.draftTitle}
+                  aria-label=${renameLabel}
+                  @input=${this.onTitleInputChange}
+                  @keydown=${this.onTitleInputKeyDown}
+                  @blur=${this.onTitleInputBlur}
+                />`
+            : html `<span part="title" title=${displayTitle}>${displayTitle}</span>`}
+            ${this.excerpt ? html `<span part="excerpt">${this.excerpt}</span>` : nothing}
+          </div>
+          ${ts ? html `<time part="timestamp" datetime=${ts.toISOString()}>${formatter(ts)}</time>` : nothing}
+        </div>
+        ${showRenameButton
+            ? html `<button
+              part="rename-button"
+              type="button"
+              aria-label=${renameLabel}
+              @click=${this.onRenameButtonClick}
+            >
+              ${pencilIcon()}
+            </button>`
+            : nothing}
+        <span part="actions" ?hidden=${!this.hasActionsSlot}>
+          <slot name="actions" @slotchange=${this.onActionsSlotChange}></slot>
+        </span>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraConversationItem.prototype, "title", void 0);
+__decorate([
+    property()
+], LyraConversationItem.prototype, "excerpt", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraConversationItem.prototype, "timestamp", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraConversationItem.prototype, "formatTimestamp", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraConversationItem.prototype, "active", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraConversationItem.prototype, "editable", void 0);
+__decorate([
+    state()
+], LyraConversationItem.prototype, "renaming", void 0);
+__decorate([
+    state()
+], LyraConversationItem.prototype, "draftTitle", void 0);
+__decorate([
+    state()
+], LyraConversationItem.prototype, "hasActionsSlot", void 0);
+__decorate([
+    query('[part="title-input"]')
+], LyraConversationItem.prototype, "titleInput", void 0);
+defineElement('conversation-item', LyraConversationItem);

package/dist/components/conversation-item/conversation-item.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/conversation-item/conversation-item.styles.js

@@ -0,0 +1,155 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    font-size: 0.875rem;
+    line-height: 1.4;
+  }
+
+  /* [part='base'] is a plain layout wrapper (no ARIA role of its own) --
+     the interactive/selectable region is [part='option'] alone, kept free
+     of focusable descendants (see the class doc's nested-interactive note).
+     The row-level hover/active background treatments still live here so
+     hovering anywhere across the row -- including over the trailing
+     rename/actions controls -- highlights the whole thing as one row. */
+  [part='base'] {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--lyra-space-xs);
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    border-radius: var(--lyra-radius);
+    transition: background-color var(--lyra-transition-fast);
+  }
+  :host(:hover) [part='base'] {
+    background: color-mix(in srgb, var(--lyra-color-text) 6%, transparent);
+  }
+  /* Placed after the :hover rule (equal selector specificity) so an
+     active-and-hovered row keeps the stronger active tint instead of the
+     two backgrounds visually competing. */
+  :host([active]) [part='base'] {
+    background: var(--lyra-color-brand-quiet);
+  }
+
+  /* text-quiet's contrast ratio against brand-quiet lands at ~4.25:1 --
+     just under the WCAG AA 4.5:1 floor for normal-size text -- even though
+     it comfortably passes against the plain (non-active) background used
+     the rest of the time. Same class of bug already hit and fixed in
+     lyra-attachment-chip's [part='size'] and lyra-chat-message's
+     [part='footer']; same fix, full-strength text color once active. */
+  :host([active]) [part='excerpt'],
+  :host([active]) [part='timestamp'] {
+    color: var(--lyra-color-text);
+  }
+
+  [part='option'] {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--lyra-space-s);
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    cursor: pointer;
+    outline: none; /* the visible ring below targets [part='option'] directly */
+    -webkit-tap-highlight-color: transparent;
+  }
+  [part='option']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+
+  [part='content'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+  }
+
+  [part='title'] {
+    display: block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-weight: 600;
+    color: var(--lyra-color-text);
+  }
+
+  [part='title-input'] {
+    display: block;
+    inline-size: 100%;
+    box-sizing: border-box;
+    padding: 0.125rem var(--lyra-space-xs);
+    border: 1px solid var(--lyra-color-brand);
+    border-radius: calc(var(--lyra-radius) * 0.6);
+    background: var(--lyra-color-surface);
+    color: var(--lyra-color-text);
+    font: inherit;
+    font-weight: 600;
+  }
+  [part='title-input']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+
+  [part='excerpt'] {
+    display: block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.8125rem;
+  }
+
+  [part='timestamp'] {
+    flex: 0 0 auto;
+    align-self: flex-start;
+    white-space: nowrap;
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.75rem;
+    font-variant-numeric: tabular-nums;
+  }
+
+  [part='rename-button'] {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: min(var(--lyra-icon-button-size), 1.75rem);
+    min-block-size: min(var(--lyra-icon-button-size), 1.75rem);
+    padding: 0;
+    border: none;
+    border-radius: calc(var(--lyra-radius) * 0.6);
+    background: transparent;
+    color: var(--lyra-color-text-quiet);
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    transition: background-color var(--lyra-transition-fast);
+  }
+  [part='rename-button']:hover {
+    background: color-mix(in srgb, var(--lyra-color-text) 8%, transparent);
+    color: var(--lyra-color-text);
+  }
+  [part='rename-button']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='rename-button'] svg {
+    display: block;
+  }
+
+  [part='actions'] {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+  }
+  [part='actions'][hidden] {
+    display: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [part='base'],
+    [part='rename-button'] {
+      transition: none !important;
+    }
+  }
+`;

package/dist/components/date-picker/calendar-core.d.ts

@@ -1,4 +1,18 @@
 export type WeekdayFormat = 'narrow' | 'short' | 'long';
+export type CalendarMode = 'single' | 'range';
+/** Normalize an untyped calendar count to the supported one- or two-month range. */
+export declare function normalizeCalendarMonths(value: unknown): 1 | 2;
+/** Normalize an untyped weekday format before passing it to `Intl.DateTimeFormat`. */
+export declare function normalizeWeekdayFormat(value: unknown): WeekdayFormat;
+/** Normalize an untyped picker mode to the single-date default. */
+export declare function normalizeCalendarMode(value: unknown): CalendarMode;
+/**
+ * Construct a date formatter while treating a malformed runtime locale as
+ * the platform default. Attribute values and JavaScript property writes are
+ * not constrained by TypeScript's declarations, so they must not be allowed
+ * to turn a calendar render into a `RangeError`.
+ */
+export declare function dateTimeFormat(locale: unknown, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
 /** Parse `YYYY-MM-DD` into a local Date, or null if invalid. */
 export declare function parseISO(s: string): Date | null;
 /** Format a Date as local `YYYY-MM-DD`. */
@@ -6,6 +20,16 @@ export declare function formatISO(d: Date): string;
 export declare function isSameDay(a: Date, b: Date): boolean;
 /** First day of the month `n` months from `d`. */
 export declare function addMonths(d: Date, n: number): Date;
+/**
+ * `d` shifted by `n` months, keeping the same day-of-month unless the target
+ * month is shorter, in which case the day is clamped to that month's last
+ * day. Plain `new Date(year, month + n, d.getDate())` construction instead
+ * overflows a too-large day-of-month into the *following* month (e.g. Jan 31
+ * + 1 month rolls into March, skipping February entirely) because the Date
+ * constructor normalizes out-of-range day components rather than clamping
+ * them.
+ */
+export declare function addMonthsClampingDay(d: Date, n: number): Date;
 export declare function clampDate(d: Date, min: Date | null, max: Date | null): Date;
 /**
  * A 6×7 grid of Dates covering the given month, week-aligned to `firstDayOfWeek`

package/dist/components/date-picker/calendar-core.js

@@ -1,3 +1,32 @@
+/** Normalize an untyped calendar count to the supported one- or two-month range. */
+export function normalizeCalendarMonths(value) {
+    const numeric = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(numeric))
+        return 1;
+    return Math.min(2, Math.max(1, Math.trunc(numeric)));
+}
+/** Normalize an untyped weekday format before passing it to `Intl.DateTimeFormat`. */
+export function normalizeWeekdayFormat(value) {
+    return value === 'narrow' || value === 'long' ? value : 'short';
+}
+/** Normalize an untyped picker mode to the single-date default. */
+export function normalizeCalendarMode(value) {
+    return value === 'range' ? 'range' : 'single';
+}
+/**
+ * Construct a date formatter while treating a malformed runtime locale as
+ * the platform default. Attribute values and JavaScript property writes are
+ * not constrained by TypeScript's declarations, so they must not be allowed
+ * to turn a calendar render into a `RangeError`.
+ */
+export function dateTimeFormat(locale, options) {
+    try {
+        return new Intl.DateTimeFormat(typeof locale === 'string' && locale ? locale : undefined, options);
+    }
+    catch {
+        return new Intl.DateTimeFormat(undefined, options);
+    }
+}
 /** Parse `YYYY-MM-DD` into a local Date, or null if invalid. */
 export function parseISO(s) {
     if (!s)
@@ -32,6 +61,20 @@ export function isSameDay(a, b) {
 export function addMonths(d, n) {
     return new Date(d.getFullYear(), d.getMonth() + n, 1);
 }
+/**
+ * `d` shifted by `n` months, keeping the same day-of-month unless the target
+ * month is shorter, in which case the day is clamped to that month's last
+ * day. Plain `new Date(year, month + n, d.getDate())` construction instead
+ * overflows a too-large day-of-month into the *following* month (e.g. Jan 31
+ * + 1 month rolls into March, skipping February entirely) because the Date
+ * constructor normalizes out-of-range day components rather than clamping
+ * them.
+ */
+export function addMonthsClampingDay(d, n) {
+    const targetMonth = d.getMonth() + n;
+    const lastDayOfTargetMonth = new Date(d.getFullYear(), targetMonth + 1, 0).getDate();
+    return new Date(d.getFullYear(), targetMonth, Math.min(d.getDate(), lastDayOfTargetMonth));
+}
 export function clampDate(d, min, max) {
     if (min && d < min)
         return min;
@@ -60,18 +103,22 @@ export function monthMatrix(year, month, firstDayOfWeek = 0) {
 }
 /** Localized weekday header labels, ordered from `firstDayOfWeek`. */
 export function weekdayLabels(firstDayOfWeek = 0, format = 'short', locale) {
-    const fmt = new Intl.DateTimeFormat(locale || undefined, { weekday: format });
+    const numericFirstDay = Number(firstDayOfWeek);
+    const start = Number.isFinite(numericFirstDay)
+        ? ((Math.trunc(numericFirstDay) % 7) + 7) % 7
+        : 0;
+    const fmt = dateTimeFormat(locale, { weekday: normalizeWeekdayFormat(format) });
     const labels = [];
     // 2021-08-01 is a Sunday, so index i maps cleanly to a weekday.
     for (let i = 0; i < 7; i++) {
-        const day = (firstDayOfWeek + i) % 7;
+        const day = (start + i) % 7;
         labels.push(fmt.format(new Date(2021, 7, 1 + day)));
     }
     return labels;
 }
 /** Localized "Month YYYY" title. */
 export function monthTitle(year, month, locale) {
-    return new Intl.DateTimeFormat(locale || undefined, { month: 'long', year: 'numeric' }).format(new Date(year, month, 1));
+    return dateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(new Date(year, month, 1));
 }
 const FDOW = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
 /** Locale-derived first day of week (0=Sunday … 6=Saturday), or null if unsupported. */
@@ -97,5 +144,5 @@ export function resolveFirstDayOfWeek(value, locale) {
         const derived = locale ? localeFirstDayOfWeek(locale) : null;
         return derived ?? 0;
     }
-    return FDOW[value.toLowerCase()] ?? 0;
+    return typeof value === 'string' ? (FDOW[value.toLowerCase()] ?? 0) : 0;
 }