@agent-ui-kit/components 0.0.3

package/dist/controls/button/button.js

@@ -0,0 +1,115 @@
+// button.ts — UIButtonElement, the reference FACE control (goals.md §G5 / Phase-1). BEHAVIOUR + props +
+// role + self-define ONLY.
+//
+// Content model — host-as-grid (ADR-0006): the user's light-DOM children (an optional leading icon + the
+// label) are placed by button.css's `:has()` grid (s7). `render()` stays the inherited no-op — there is no
+// template, so the host render effect never commits anything of its own. ADR-0133 ADDS one adoption move
+// beyond that: the label region (the non-adornment children — anything without `slot="leading"`/
+// `slot="trailing"`) is wrapped in a real, persistent `<span data-part="label">` so button.css can carry
+// `text-overflow` on it (anonymous grid text has no selector surface for the clip — button.css:99-103's own
+// long-standing deferral comment). This is `ui-text`'s stamp/heal shape (ADR-0078 cl.4) adapted: nodes are
+// MOVED, never cloned, and a `childList` MutationObserver re-adopts any stray label child that lands
+// directly on the host later (parser streaming, or the A2UI `buttonFactory`'s `el.textContent = label`
+// write, `factories.ts:117-119` — the identical clobbering pattern ui-text's heal observer exists to
+// survive). The wrapper is UNCONDITIONAL — no opt-in prop — because the label is already forced to one line
+// (`white-space: nowrap`, unconditional); ellipsis-on-overflow completes that existing default rather than
+// adding a new axis. An `icon-only` button (no label content at all) never gets an empty wrapper — the heal
+// pass only builds one when there is a stray non-adornment node to hold, so the fifth (square) structure is
+// untouched. Geometry/colour otherwise live entirely in button.css.
+//
+// Keyboard activation is the `pressActivation` trait (Space/Enter → a native-parity `host.click()`),
+// invoked from `connected()` so its listeners ride the connection AbortSignal. Focusability is the
+// `tabbable` trait (ADR-0010): tabindex=0 while enabled, out of the tab order while disabled — the inert
+// half that lives in a trait. ARIA `role` is set through `ElementInternals`, never a host attribute, and so
+// is the disabled AX state (`ariaDisabled`) — a control-level effect because `internals` is protected and a
+// trait cannot reach it. `controls → dom + traits` is the allowed import direction.
+import { UIElement, prop } from "../../dom/index.js";
+import { pressActivation } from "../../traits/press-activation.js";
+import { tabbable } from "../../traits/tabbable.js";
+/** An adornment child sits in a POSITION slot (ADR-0006/ADR-0012) — everything else is label content. */
+const isAdornment = (node) => node instanceof Element && (node.getAttribute('slot') === 'leading' || node.getAttribute('slot') === 'trailing');
+const props = {
+    // variant/size REFLECT so the attribute-selector styling (`[variant]`/`[size]` in button.css repointing
+    // the colour roles + dimensional ramp) applies to JS-set values too, not only author-set attributes.
+    variant: { ...prop.enum(['solid', 'soft', 'ghost'], 'solid'), reflect: true },
+    size: { ...prop.enum(['sm', 'md', 'lg'], 'md'), reflect: true },
+    // `disabled` reflects to a `disabled` attribute so CSS can render the host pointer-inert (s7); the
+    // trait already guards keyboard activation off `() => this.disabled`.
+    disabled: { ...prop.boolean(false), reflect: true },
+    // icon-only ⇒ the geometry law's fifth structure (references/geometry.md "icon-only (no label) →
+    // square"): a real slotted adornment (leading/trailing) with NO label content at all. CSS alone
+    // cannot detect an empty/text-node label — `:has()` only matches ELEMENTS, so a bare text-node label
+    // (the common `<svg slot=leading>…Download</ui-button>` pattern) is invisible to it — so this is an
+    // explicit author opt-in (button.css's `:scope[icon-only]` structure). The accessible name must then
+    // come from `aria-label` (there is no label text to read), the toast.ts close-button precedent.
+    iconOnly: { ...prop.boolean(false), reflect: true, attribute: 'icon-only' },
+};
+export class UIButtonElement extends UIElement {
+    static props = props;
+    // The label wrapper (ADR-0133) — the one real element the label region is adopted into, so button.css
+    // can carry `text-overflow` on it. Null whenever there is no label content to hold (e.g. `icon-only`).
+    #label = null;
+    // The childList observer that heals the wrapper invariant — the SAME shape as ui-text's `#observer`
+    // (ADR-0078 cl.4): re-adopts a stray label child (parser streaming) and rebuilds the wrapper fresh after
+    // a `textContent` clobber (the A2UI `buttonFactory` `label` write). Disconnected in `disconnected()` —
+    // the "zero residue after removal" discipline a raw platform observer needs by hand.
+    #observer = null;
+    connected() {
+        this.internals.role = 'button'; // ARIA via internals — never a host role/aria-* attribute
+        tabbable(this, { disabled: () => this.disabled }); // tabindex=0 enabled / out of tab order disabled (ADR-0010)
+        pressActivation(this, { disabled: () => this.disabled }); // Space/Enter → click; auto-cleans on disconnect
+        // The disabled AX state — control-level (internals is protected, unreachable from a trait); scope-owned,
+        // so it re-runs on the disabled signal and is disposed on disconnect (zero residue).
+        this.effect(() => {
+            this.internals.ariaDisabled = this.disabled ? 'true' : null;
+        });
+        // The label wrapper (ADR-0133) — an initial heal pass adopts whatever label content already exists
+        // (parser-streamed or set before connect), then the observer heals every later mutation. Installed
+        // AFTER the initial pass so it never observes its own synchronous setup.
+        this.#heal();
+        this.#observer = new MutationObserver(() => this.#heal());
+        this.#observer.observe(this, { childList: true });
+        // Motion gate (interaction-states standard) — flip the `ready` custom state ONE FRAME PAST first paint, so
+        // the upgrade/first-paint styling SNAPS in and only subsequent state changes animate (the button.css
+        // transition is gated behind `:state(ready)`). requestAnimationFrame — NOT updateComplete (a microtask,
+        // before paint) — to clear the first paint; `states` is optional-chained because jsdom has no CustomStateSet
+        // (the real motion behaviour is the cross-engine smoke). Idempotent (a Set), so reconnect is safe.
+        requestAnimationFrame(() => this.internals.states?.add('ready'));
+    }
+    disconnected() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+    }
+    /**
+     * Restore the label-wrapper invariant (ADR-0133). A DETACHED wrapper (a `textContent`/`innerHTML`
+     * clobber that replaced every child, wrapper included) is forgotten; every stray non-adornment child
+     * currently on the host is then adopted into the wrapper, building one fresh only if there is at least
+     * one such child (an empty wrapper would pollute the `icon-only` single-column anatomy with a dead grid
+     * track). The wrapper's insert point is anchored on the TRAILING adornment element itself (never on
+     * `strays[0]`) — adornments are never moved, so inserting immediately before whatever trailing element
+     * currently exists (or appending, when there is none) places the wrapper after any leading adornment and
+     * before any trailing one regardless of interspersed whitespace text nodes (component-reviewer finding:
+     * an authored, pretty-printed `<ui-button>\n  <svg slot="leading">…</svg>Label\n</ui-button>` has a
+     * whitespace text node BEFORE the leading adornment — anchoring on `strays[0]` put the wrapper ahead of
+     * it, inverting the anatomy). Adopting a node re-fires this same observer, but the next delivery finds
+     * the invariant satisfied — a no-op — so this self-converges within ≤2 passes (the ui-text `#heal`
+     * precedent).
+     */
+    #heal() {
+        if (this.#label && this.#label.parentNode !== this)
+            this.#label = null; // detached — a full clobber
+        const strays = Array.from(this.childNodes).filter((node) => node !== this.#label && !isAdornment(node));
+        if (strays.length === 0)
+            return; // nothing to wrap — keep icon-only (and empty) buttons untouched
+        if (!this.#label) {
+            this.#label = document.createElement('span');
+            this.#label.setAttribute('data-part', 'label');
+            const trailing = Array.from(this.children).find((el) => el.getAttribute('slot') === 'trailing') ?? null;
+            this.insertBefore(this.#label, trailing); // before the trailing adornment, or appended when there is none
+        }
+        for (const node of strays)
+            this.#label.appendChild(node);
+    }
+}
+if (!customElements.get('ui-button'))
+    customElements.define('ui-button', UIButtonElement);

package/dist/controls/calendar/calendar.css

@@ -0,0 +1,495 @@
+/* calendar.css — ui-calendar, the standalone month-grid date picker control (ADR-0048 / Wave-5B-1;
+ * range mode ADR-0093; fluid tracks + two-layer cell ADR-0105).
+ *
+ * Two clearly-sectioned blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-calendar)` (specificity 0,0,0) DECLARES the `--ui-calendar-*`
+ *       chain from colour roles (`--md-sys-color-{family}-{role}`) and the dimensional ramp. Fallback values
+ *       are sensible until the tokens-specialist delivers the canonical token definitions. The
+ *       `[size]` repoint triples follow the button/select/text-field precedent; `[disabled]` mutes
+ *       the nav buttons. `--ui-calendar-range-fill`/`-range-ink` (ADR-0093 clause 4, ERRATUM
+ *       2026-07-07) alias `--md-sys-color-primary-surface-highest` / `-primary-on-surface` —
+ *       0.0655/0.0722 OKLCH-L separation from the panel bg in light/dark (was ~0.001, effectively
+ *       invisible — see the erratum on ADR-0093) and 12.70:1 / 12.16:1 ink-vs-fill contrast, well
+ *       past the AA 4.5:1 floor (verified against tokens.css's OKLCH primitives).
+ *
+ *   [2] STYLES BLOCK — `@scope (ui-calendar)` CONSUMES only `--ui-calendar-*` for its OWN selectors.
+ *       The panel (`[data-part=panel][data-box]`) adopts the shared container box-model (inset margins
+ *       + sticky header) from `_surface/container-box.css` at zero specificity. The grid is a CSS
+ *       grid of 7 FLUID columns (ADR-0105: `minmax(--ui-calendar-cell-size, 1fr)` — the cell-size ramp
+ *       is the track FLOOR, not a fixed track; shrink-wrapped it resolves to the floor exactly, given
+ *       surplus width the grid fills it); `[role=row]` divs use `display:contents` so cells participate
+ *       directly in the parent grid (a clean flat-grid layout; `[role=row]`'s ARIA role is set via
+ *       attribute, not CSS, so `display:contents` does not affect the accessibility tree). Day cells are
+ *       a TWO-LAYER cell (ADR-0105, CSS-only — the single `<button role=gridcell>` of calendar.ts is
+ *       unchanged): the BAND layer is the button box itself (stretches to its fluid track — the square
+ *       `[data-in-range]` wash, ink/disabled/outside colours, the enlarged hit target) and the POINT
+ *       layer is a fixed `--ui-calendar-cell-size` circle (`::before`, absolutely centred, negative
+ *       `z-index` under an `isolation:isolate` stacking context on the button so it paints ABOVE the
+ *       band wash and BELOW the numeral) carrying the aria-selected/hover/today-ring/focus-ring — the
+ *       things that are legitimately circular, at every track width. A second pseudo (`::after`) on
+ *       `[data-range-start]`/`[data-range-end]` (mutually exclusive with the OTHER endpoint attribute
+ *       via `:not()`, so a same-day range paints neither) bridges a half-track wash from the circle's
+ *       edge to the band interior — `calc(50% + cell-size/2)` to the far inline edge, which is exactly
+ *       0-width at the track floor (today's rendering, byte-for-byte) and only opens up under surplus
+ *       width. The [data-today] ring, [aria-selected]/[data-in-range] fills, and the half-wash are
+ *       load-bearing colour values protected under forced-colors via `forced-color-adjust:none`
+ *       (inherited by the pseudos from the button rules that already set it — it's an inherited
+ *       property).
+ *
+ * Standalone — NOT injected from calendar.ts (behaviour-only `.ts`, no runtime style injection
+ * per plan §2). Linked via component-styles.css; foundation roles FIRST in the load order.
+ */
+
+/* ══════════════════════ [1] TOKEN BLOCK — :where(ui-calendar) ══════════════════════════════ */
+
+:where(ui-calendar) {
+  /* ── Cell geometry (ADR-0105: re-stated as the track FLOOR + the point-layer diameter — the
+     value is unchanged, only its meaning widens). The day cell's block-size is always this; the
+     inline-size is this at the track floor (shrink-wrapped) and grows with surplus width (fluid
+     `minmax()` track) — the fixed circular POINT layer (::before) stays this diameter regardless.
+     Aliases --md-sys-height-md so the cell rides the explicit per-[scale] height ramp (ADR-0038),
+     tracking scale automatically without a multiplier. [size] repoints below.
+     --ui-calendar-gap is the inter-cell gap; aliases --md-sys-space-xs (4px × density). */
+  --ui-calendar-cell-size: var(--md-sys-height-md);
+  --ui-calendar-gap: var(--md-sys-space-xs);
+
+  /* ── Day-cell typography — font-size at a comfortable reading size inside the cell. */
+  --ui-calendar-font: var(--md-sys-font-md, 14px);
+
+  /* ── Selected-day fill (the committed value cell).
+     --md-sys-color-primary-selected is the AA primary-on-accent role (tokens-calendar); fall back to
+     --md-sys-color-primary so the build stays green if it lands a moment after this component. */
+  --ui-calendar-selected-fill: var(--md-sys-color-primary-selected, var(--md-sys-color-primary));
+  --ui-calendar-selected-ink:  var(--md-sys-color-primary-on-primary); /* white — the on-primary pair */
+
+  /* ── Today's ring (the current date, whether selected or not).
+     Aliases --md-sys-color-primary-outline; drawn as an INSET box-shadow so it sits inside the cell
+     and stays distinct from the offset-outside focus outline (see forced-colors note below). */
+  --ui-calendar-today-ring: var(--md-sys-color-primary-outline);
+
+  /* ── Disabled / out-of-range day ink (muted; WCAG exempts inactive controls). */
+  --ui-calendar-disabled-ink: var(--md-sys-color-neutral-on-surface-variant);
+
+  /* ── Adjacent-month day ink (prev/next month overflow cells — dimmed to neutral mid). */
+  --ui-calendar-outside-ink: var(--md-sys-color-neutral);
+
+  /* ── Nav button geometry — the ‹ and › inline affordances are sized = font (§4.6 law).
+     They are plain buttons; no fixed icon-cell needed (they're typography glyphs). */
+  --ui-calendar-nav-font: var(--md-sys-font-md, 14px);
+
+  /* ── Panel surface — inherits the container/surface tokens for bg/border/radius.
+     The panel is a Container/surface (NOT a Control-class surface), so it uses bg + outline. */
+  --ui-calendar-panel-bg:      var(--md-sys-color-neutral-surface, #fff);
+  --ui-calendar-panel-ink:     var(--md-sys-color-neutral-on-surface, #1c1c1e);
+  --ui-calendar-panel-outline: var(--md-sys-color-neutral-outline-variant, #c4c4c4);
+  --ui-calendar-panel-radius:  var(--md-sys-shape-corner-base, 0.375rem);
+
+  /* ── Weekday column-header ink (muted row above the cells). */
+  --ui-calendar-header-ink: var(--md-sys-color-neutral-on-surface-variant, #767676);
+
+  /* ── Cell hover background (non-selected, non-disabled). */
+  --ui-calendar-cell-hover-bg: var(--md-sys-color-neutral-surface-high, #f0f0f0);
+
+  /* ── Range interior wash (ADR-0093 clause 4, ERRATUM 2026-07-07) — the SQUARE fill for
+     [data-in-range] cells (endpoints reuse --ui-calendar-selected-fill/-ink above, unchanged).
+     ADR-0093 clause 4 originally aliased --md-sys-color-primary-surface / -primary-on-surface —
+     measured (gallery audit) to differ from the panel's --md-sys-color-neutral-surface by only
+     ~0.001 OKLCH L in BOTH schemes (light 0.9336 vs 0.9347; dark 0.2598 vs 0.2592): the band was
+     load-bearing colour with no real lightness separation, i.e. effectively invisible. Repointed
+     to --md-sys-color-primary-surface-highest, whose OKLCH L differs from the panel by 0.0655
+     (light) / 0.0722 (dark) — ~65×/~72× the old gap, a clearly-visible-but-soft wash (chroma
+     stays far below the solid endpoint fill's --md-sys-color-primary-550/600). Ink stays
+     --md-sys-color-primary-on-surface: ink-vs-fill contrast is 12.70:1 (light) / 12.16:1 (dark),
+     comfortably past the AA 4.5:1 floor a text/numeral pairing needs (see the erratum on
+     .claude/docs/adr/0093-calendar-range-selection.md for the full measurement). */
+  --ui-calendar-range-fill: var(--md-sys-color-primary-surface-highest, #dde6f4);
+  --ui-calendar-range-ink:  var(--md-sys-color-primary-on-surface, #1c1c1e);
+
+  /* ── user-invalid (ADR-0051) — the danger border repoint, the text-field precedent. Appears only
+     AFTER the first interaction (the trackUserInvalid controller owns that timing; calendar.ts
+     toggles :state(user-invalid)). */
+  --ui-calendar-border-invalid: var(--md-sys-color-danger);
+}
+
+/* [size] repoints cell size onto the §1-ramp height entries (ADR-0038: explicit per-[scale] table,
+   24/28/36px at the default ui-md scale). Pattern mirrors checkbox [size]→--md-sys-compact-* repoints. */
+:where(ui-calendar[size='sm']) {
+  --ui-calendar-cell-size: var(--md-sys-height-sm); /* 24px default; retables under [scale] */
+  --ui-calendar-font: var(--md-sys-font-sm, 13px);
+  --ui-calendar-nav-font: var(--md-sys-font-sm, 13px);
+}
+
+:where(ui-calendar[size='lg']) {
+  --ui-calendar-cell-size: var(--md-sys-height-lg); /* 36px default ≈ 2.25rem target; retables under [scale] */
+  --ui-calendar-font: var(--md-sys-font-lg, 16px);
+  --ui-calendar-nav-font: var(--md-sys-font-lg, 16px);
+}
+
+/* Disabled host — mute the nav-button ink (day cells carry their own aria-disabled state). */
+:where(ui-calendar[disabled]) {
+  --ui-calendar-panel-ink: var(--md-sys-color-neutral-on-surface-variant, #767676);
+}
+
+/* ══════════════════════ [2] STYLES BLOCK — @scope (ui-calendar) ════════════════════════════ */
+
+@scope (ui-calendar) {
+  /* Host: inline-block so ui-calendar shrink-wraps its panel by default (like a compact form
+     widget) when NOTHING gives it width. ADR-0105 — the grid's tracks are fluid (`minmax()`
+     below), so a caller that DOES grant width (a stretched flex/grid cell — blockification
+     turns this inline-block into the flex/grid item the cross-axis `stretch` default sizes,
+     ADR-0030) gets a grid that fills it, not a fixed-width grid stranded in a wide, half-empty
+     panel. The escape for a caller that wants the OLD always-compact behaviour even when
+     stretched: `max-inline-size: max-content` (one line, page-author override — ADR-0102). */
+  :scope {
+    display: inline-block;
+    vertical-align: top;
+  }
+
+  /* ── Panel ([data-part=panel][data-box]) ────────────────────────────────────────────────
+     The [data-box] attribute opts this element into container-box.css's box-model:
+       • display: flow-root (BFC; child margins collapse to one inset)
+       • <header> children: INSET (not full-bleed), sticky, flex-row, padding inline=12/block=6, gap=8
+       • other direct children: margin: 6px (the uniform inset)
+     We add paint: background + border + radius. No position/size overrides needed — the
+     grid sizes the panel naturally to 7×cell-size + gaps. */
+  :scope [data-part='panel'] {
+    display: flow-root;               /* BFC — child margins collapse; also set by container-box.css */
+    background-color: var(--ui-calendar-panel-bg);
+    color: var(--ui-calendar-panel-ink);
+    border: 1px solid var(--ui-calendar-panel-outline);
+    border-radius: var(--ui-calendar-panel-radius);
+    box-sizing: border-box;
+  }
+
+  /* user-invalid (ADR-0051) — the danger border, appearing only AFTER the first interaction (the
+     trackUserInvalid controller owns that timing; calendar.ts toggles :state(user-invalid) on the
+     host). The panel is the calendar's one bordered surface — the text-field precedent applied to
+     the Container/surface-class part instead of a Control-class frame. */
+  :scope:state(user-invalid) [data-part='panel'] {
+    border-color: var(--ui-calendar-border-invalid);
+  }
+
+  /* ── Nav header (<header data-part="nav">) ──────────────────────────────────────────────
+     container-box.css already gives the <header>: display:flex; align-items:center; gap=8px;
+     padding-inline=12px; padding-block=6px; margin=6px (INSET, not full-bleed); position:sticky;
+     inset-block-start=6px (the box's own inset — matches the at-rest margin, so nothing snaps
+     to 0 if the panel ever scrolls); z-index:1. We add: space-between so ‹ title › spreads,
+     and the title grows to fill. */
+  :scope [data-part='nav'] {
+    justify-content: space-between;
+  }
+
+  /* Month/year title: grows to fill the space between the two nav buttons. Centred text. */
+  :scope [data-part='title'] {
+    flex: 1;
+    text-align: center;
+    font-size: var(--ui-calendar-nav-font);
+    font-weight: 600;
+    line-height: 1;
+  }
+
+  /* Nav buttons (‹ ›): plain icon affordances — no background, no border, just the glyph. */
+  :scope [data-part='prev'],
+  :scope [data-part='next'] {
+    flex-shrink: 0;
+    padding: 0.25rem;
+    font-size: var(--ui-calendar-nav-font);
+    line-height: 1;
+    background: transparent;
+    border: none;
+    border-radius: var(--ui-calendar-panel-radius);
+    color: inherit;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  /* The injected Phosphor caret-left/caret-right (setIcon, @agent-ui-kit/icons): 1em tracks the
+     button's own font-size (--ui-calendar-nav-font above) at every [size] tier — the same
+     rendered size as the previous ‹ › text glyphs. Overrides the svg's own width/height="100%"
+     presentational attributes (resolve.ts). */
+  :scope [data-part='prev'] svg,
+  :scope [data-part='next'] svg {
+    display: block;
+    inline-size: 1em;
+    block-size: 1em;
+  }
+
+  :scope [data-part='prev']:hover,
+  :scope [data-part='next']:hover {
+    background-color: var(--ui-calendar-cell-hover-bg);
+  }
+
+  :scope [data-part='prev']:focus-visible,
+  :scope [data-part='next']:focus-visible {
+    outline: var(--md-sys-state-focus-ring-width, 2px) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset, 2px);
+  }
+
+  /* ── Grid container ([data-part="grid"]) ────────────────────────────────────────────────
+     A CSS grid of 7 FLUID columns (ADR-0105), one per day of the week. `minmax(cell-size, 1fr)`:
+     the cell-size ramp is the track FLOOR (shrink-wrapped/intrinsic sizing resolves `1fr` to its
+     base size when the grid's own inline-size is undetermined by an ancestor — today's exact
+     compact rendering, byte-identical); given a DEFINITE width from an ancestor (a stretched
+     flex/grid cell), the seven tracks share the surplus equally and the grid fills it. Row
+     heights are untouched — width adapts, the month never inflates vertically. The [role=row]
+     divs use display:contents so their children (columnheaders and gridcells) participate directly
+     in the flat 7-column grid — each week flows into the next row automatically. The
+     weekday header row and the 6 week rows are all part of the same flat grid, avoiding
+     a nested-flex layout that would need explicit sizing on every row. */
+  :scope [data-part='grid'] {
+    display: grid;
+    grid-template-columns: repeat(7, minmax(var(--ui-calendar-cell-size, 2rem), 1fr));
+    gap: var(--ui-calendar-gap, 0.125rem);
+    /* The direct-child margin from [data-box] applies here (6px all around, the box's uniform
+       inset). We keep the default inset margin — the grid sits slightly inside the panel. */
+  }
+
+  /* [role=row] is transparent to the parent CSS grid — cells participate directly.
+     The ARIA role is set via the HTML attribute, NOT by CSS, so display:contents does
+     NOT remove the row from the accessibility tree (the role attribute is authoritative). */
+  :scope [data-part='grid'] [role='row'] {
+    display: contents;
+  }
+
+  /* ── Weekday column headers ──────────────────────────────────────────────────────────────
+     Non-interactive; muted ink; centred. The <span role="columnheader"> elements sit in
+     the first grid row and establish the 7-column visual header. */
+  :scope [data-part='grid'] [role='columnheader'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    block-size: calc(var(--ui-calendar-cell-size, 2rem) * 0.75); /* slightly smaller than cells */
+    font-size: calc(var(--ui-calendar-font, 14px) * 0.85);
+    color: var(--ui-calendar-header-ink);
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  /* ── Day cells ([role=gridcell]) — the TWO-LAYER cell (ADR-0105) ─────────────────────────
+     The single button IS the BAND layer: it stretches to its (fluid) track, carrying the square
+     [data-in-range] wash, ink/disabled/outside colours, and the enlarged hit target (a strict
+     a11y win — the click-delegation commit path already resolves through
+     closest('[role="gridcell"]'), so a wider button changes nothing behaviourally). `position:
+     relative` gives its two pseudo layers a containing block; `isolation: isolate` establishes a
+     stacking context so a NEGATIVE z-index on the pseudos still paints ABOVE the button's own
+     background (paint-order step 1) and BELOW the day-number text (an in-flow inline descendant,
+     which paints ahead of z-index:auto/0 descendants but AFTER negative-z ones — negative z-index
+     is the only way under it, CSS2.1 Appendix E). line-height:1 (ADR-0036: single-line control
+     glyph centred by the frame). */
+  :scope [data-part='grid'] [role='gridcell'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    position: relative;
+    isolation: isolate;
+    block-size: var(--ui-calendar-cell-size, 2rem); /* rows never inflate — only inline-size is fluid */
+    border: none;
+    border-radius: 0;                  /* the BAND is square; circularity lives on the POINT layer below */
+    background: transparent;
+    color: inherit;
+    font-size: var(--ui-calendar-font, 14px);
+    line-height: var(--md-sys-control-line-height, 1);
+    cursor: pointer;
+    padding: 0;
+    -webkit-user-select: none;
+    user-select: none;
+    outline: none;                     /* the POINT layer's ::before carries the focus ring below — a
+                                           ring on the (now possibly wide) band itself would draw a
+                                           rectangle, not the circle ADR-0105 requires */
+  }
+
+  /* ── The POINT layer (::before) — a FIXED --ui-calendar-cell-size circle, always centred in the
+     button regardless of its (fluid) width. Carries: the aria-selected/single/endpoint fill, the
+     hover wash, the [data-today] inset ring, and the :focus-visible ring — the things that are
+     legitimately circular at every track width (ADR-0105 decision 3). `inset:0; margin:auto` +
+     a fixed inline/block-size is the "centre a fixed box inside an auto-sized positioned parent"
+     technique — it re-centres itself as the button's track grows, no JS/ResizeObserver needed. */
+  :scope [data-part='grid'] [role='gridcell']::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    margin: auto;
+    inline-size: var(--ui-calendar-cell-size, 2rem);
+    block-size: var(--ui-calendar-cell-size, 2rem);
+    border-radius: 50%;
+    z-index: -1;                        /* under the numeral, above the band background */
+    pointer-events: none;               /* decorative — the button itself owns hit-testing */
+  }
+
+  :scope [data-part='grid'] [role='gridcell']:hover::before {
+    background-color: var(--ui-calendar-cell-hover-bg);
+  }
+
+  :scope [data-part='grid'] [role='gridcell']:focus-visible::before {
+    outline: var(--md-sys-state-focus-ring-width, 2px) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset, 2px);
+  }
+
+  /* ── Today ring — an inset ring marking the current date (whether selected or not), on the
+     fixed-diameter POINT layer so it stays a true ring, never stretched into an oval. Uses
+     box-shadow so it stacks on top of the selected fill when the selected day = today (two
+     independent paint channels on the same pseudo — background-color + box-shadow never
+     conflict). `forced-color-adjust: none` ensures the ring survives WHCM (load-bearing colour). */
+  :scope [data-part='grid'] [role='gridcell'][data-today]::before {
+    box-shadow: inset 0 0 0 1.5px var(--ui-calendar-today-ring, currentcolor);
+    forced-color-adjust: none;
+  }
+
+  /* ── Selected fill — the committed value cell (single mode) OR a range endpoint (range mode:
+     [data-range-start]/[data-range-end] cells carry aria-selected="true" too — ADR-0093 clause 4
+     "endpoints reuse the existing circular fill"), painted on the fixed-diameter POINT layer so it
+     stays a circle at every width, never an ellipse (ADR-0105). `:not([data-in-range])` excludes
+     range mode's interior cells — they ALSO carry aria-selected="true" (clause 4's "the whole band
+     is selected") but must show the SQUARE band wash below, not an accent circle; endpoints never
+     carry [data-in-range] (rangeSelectionFor() computes them as mutually exclusive), so this
+     selector is a no-op narrowing for single mode and the real endpoint/interior split for range
+     mode. `color` stays on the BUTTON (inherited by the real day-number text, centred over the
+     circle) — `forced-color-adjust:none` keeps the fill in WHCM. */
+  :scope [data-part='grid'] [role='gridcell'][aria-selected='true']:not([data-in-range]) {
+    color: var(--ui-calendar-selected-ink, #fff);
+    forced-color-adjust: none;
+  }
+  :scope [data-part='grid'] [role='gridcell'][aria-selected='true']:not([data-in-range])::before {
+    background-color: var(--ui-calendar-selected-fill, #0057d8);
+    forced-color-adjust: none;
+  }
+
+  /* ── Range interior wash ([data-in-range], ADR-0093 clause 4) — SQUARE (radius:0), painted on
+     the BAND layer (the button itself) so it spans the FULL fluid track at any width — the wash
+     never opens holes between abutting interior cells (ADR-0105 decision 2). Never co-occurs with
+     [data-range-start]/[data-range-end] (rangeSelectionFor() computes them as mutually exclusive),
+     so this rule only ever touches true interior cells; under forced-colors the explicit override
+     below lands the SAME Highlight/HighlightText pair as the endpoints — the whole band is one
+     self-delimiting run (ADR-0093 clause 4) — with the circle-vs-square shape (POINT vs BAND
+     layer, untouched by forced-colors) left as the sole endpoint-vs-interior signifier (ADR-0057
+     non-colour-signifier rule). */
+  :scope [data-part='grid'] [role='gridcell'][data-in-range] {
+    background-color: var(--ui-calendar-range-fill, #dde6f4);
+    color: var(--ui-calendar-range-ink, #1c1c1e);
+    forced-color-adjust: none;
+  }
+
+  /* ── Range endpoint half-wash (::after, ADR-0105 decision 3) — bridges the fixed POINT circle to
+     the band interior on a [data-range-start]/[data-range-end] cell, so a wide track never opens a
+     gap between the endpoint circle and the neighbouring interior wash. Logical `inset-inline-*`
+     (no directional gradient) — RTL-safe by construction, the mirrored side follows for free. Spans
+     from the circle's OWN edge (`50% + cell-size/2` from centre) to the button's far inline edge —
+     at the track floor (button inline-size == cell-size) that span is exactly 0 (today's rendering,
+     byte-for-byte); it only opens under surplus width. `z-index:-2` (below the ::before circle,
+     which paints over its near portion, CSS2.1 Appendix E step 2 — most-negative-first) — only the
+     interior-facing half is ever visible. `:not([data-range-end])` / `:not([data-range-start])` on
+     the OTHER endpoint attribute excludes a same-day range (a cell that is BOTH start and end) —
+     with no interior cell on either side, no half-wash is drawn (nothing to bridge to). */
+  :scope [data-part='grid'] [role='gridcell'][data-range-start]:not([data-range-end])::after,
+  :scope [data-part='grid'] [role='gridcell'][data-range-end]:not([data-range-start])::after {
+    content: '';
+    position: absolute;
+    inset-block: 0;
+    background-color: var(--ui-calendar-range-fill, #dde6f4);
+    z-index: -2;
+    pointer-events: none;
+    forced-color-adjust: none;
+  }
+  :scope [data-part='grid'] [role='gridcell'][data-range-start]:not([data-range-end])::after {
+    inset-inline-start: calc(50% + var(--ui-calendar-cell-size, 2rem) / 2);
+    inset-inline-end: 0;
+  }
+  :scope [data-part='grid'] [role='gridcell'][data-range-end]:not([data-range-start])::after {
+    inset-inline-start: 0;
+    inset-inline-end: calc(50% + var(--ui-calendar-cell-size, 2rem) / 2);
+  }
+
+  /* ── Adjacent-month cells (data-outside) — muted ink; still clickable (navigates month). */
+  :scope [data-part='grid'] [role='gridcell'][data-outside] {
+    color: var(--ui-calendar-outside-ink, #767676);
+  }
+
+  /* ── Disabled / out-of-range cells (aria-disabled=true) — pointer-inert; muted. opacity applies
+     to the whole stacking context (button + both pseudo layers together), so a disabled endpoint's
+     circle/wash mute along with its numeral — no separate pseudo overrides needed. */
+  :scope [data-part='grid'] [role='gridcell'][aria-disabled='true'] {
+    color: var(--ui-calendar-disabled-ink, #767676);
+    cursor: default;
+    pointer-events: none;
+    opacity: 0.5;
+  }
+
+  /* ── forced-colors (WHCM) ────────────────────────────────────────────────────────────────
+     Four visually distinct states must survive system-colour flattening (ADR-0093 clause 4 —
+     the ADR-0048 three-state discipline, now four; ADR-0105 re-homes the paint per layer, the
+     mapping is unchanged):
+       focus    = Highlight ring on the POINT layer (::before) — free via --md-sys-color-focus-ring
+                  → Highlight; stays circular at every width because the ring lives on the fixed-
+                  diameter pseudo, never the (possibly wide) band
+       selected = Highlight fill + HighlightText numeral — explicit below; in range mode this is
+                  the WHOLE band (endpoints AND interior both carry aria-selected="true" — clause 4
+                  "the band is self-delimiting, so endpoint-vs-interior needs no third colour"); the
+                  half-wash (::after) carries the SAME Highlight so a bridged band reads as one
+                  contiguous run under WHCM too
+       today    = ButtonText INSET ring on the POINT layer (offset-inside, inside the circle)
+       (interior vs endpoint shape — circle (POINT layer) vs square (BAND layer) — survives
+        forced-colors unaided: border-radius is not a colour property, so it is never flattened)
+     today MUST NOT use Highlight here — it would merge with the selected/band fill AND with the
+     focus ring, collapsing every state into one indistinguishable Highlight blob.
+     The button rules above already carry `forced-color-adjust:none` per state, unconditionally
+     (not gated by this media query); it is an INHERITED property, so ::before/::after pick it up
+     from their originating button automatically — no separate declaration needed on the pseudos
+     (only the explicit system-colour paint below needs restating on the pseudo selectors, since
+     background-color/box-shadow are NOT inherited). */
+  @media (forced-colors: active) {
+    /* Panel surface: Canvas / CanvasText (standard surface mapping). */
+    :scope [data-part='panel'] {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+    }
+
+    /* Selected fill: Highlight / HighlightText (system selection pair — WCAG AA guaranteed by OS).
+       Matches range-mode endpoints too (they carry aria-selected="true"); the circle (::before) —
+       NOT the band — carries the fill, so the shape signifier survives forced-colors. */
+    :scope [data-part='grid'] [role='gridcell'][aria-selected='true']:not([data-in-range]) {
+      color: HighlightText;
+    }
+    :scope [data-part='grid'] [role='gridcell'][aria-selected='true']:not([data-in-range])::before {
+      background-color: Highlight;
+    }
+
+    /* Range interior (data-in-range): the SAME Highlight/HighlightText pair as the endpoints —
+       one self-delimiting band (ADR-0093 clause 4), painted on the BAND (button) so interior stays
+       square while endpoints (painted on the POINT layer above) stay circular. Written explicitly
+       (rather than relying on the [aria-selected='true'] rule above alone) so the four-state
+       contract stays true independent of any future reordering of this stylesheet. */
+    :scope [data-part='grid'] [role='gridcell'][data-in-range] {
+      background-color: Highlight;
+      color: HighlightText;
+    }
+
+    /* Half-wash bridge: the same Highlight as the band — one contiguous run under WHCM too. */
+    :scope [data-part='grid'] [role='gridcell'][data-range-start]:not([data-range-end])::after,
+    :scope [data-part='grid'] [role='gridcell'][data-range-end]:not([data-range-start])::after {
+      background-color: Highlight;
+    }
+
+    /* Today ring: ButtonText INSET border on the fixed-diameter POINT layer — deliberately NOT
+       Highlight so focus/selected/today remain visually distinct: focus=Highlight-outside,
+       selected=Highlight-fill, today=ButtonText-inset. */
+    :scope [data-part='grid'] [role='gridcell'][data-today]::before {
+      box-shadow: inset 0 0 0 2px ButtonText;
+    }
+
+    /* Disabled cells: GrayText (the system muted role). */
+    :scope [data-part='grid'] [role='gridcell'][aria-disabled='true'] {
+      color: GrayText;
+    }
+
+    /* Nav buttons: ButtonText. */
+    :scope [data-part='prev'],
+    :scope [data-part='next'] {
+      color: ButtonText;
+    }
+  }
+}