@adia-ai/web-components 0.6.34 → 0.6.35

package/components/alert/alert.d.ts

@@ -21,18 +21,31 @@ inline upgrade prompts.
 import { UIElement } from '../../core/element.js';
 
 export type AlertCloseEvent = CustomEvent<unknown>;
+export type AlertDunningActionEvent = CustomEvent<unknown>;
 
 export class UIAlert extends UIElement {
   /** Bold headline rendered as the first line of the alert content. Pair with [description] for the canonical "banner" pattern (headline + body). When [title] or [description] is set, the [text] prop is ignored. */
   title: string;
   /** Body text rendered as the second line of the alert content, below [title]. May be used alone (without [title]) for a single muted-body message. */
   description: string;
+  /** Dunning mode only — the unpaid amount as a decimal major-unit number (`24.50`, not minor units like `2450`). Formatted via `Intl.NumberFormat` using [currency] and [lang]. Ignored when [pattern] is not `dunning`. */
+  amount: number;
+  /** Dunning mode only — last 4 digits of the declined card. Rendered as "ending 4242". Ignored when [pattern] is not `dunning`. Attribute spelling: `card-last4`. */
+  cardLast4: string;
   /** Whether a close button is displayed. Alias [dismissible] is also accepted (same semantics, different spelling — the corpus and many libraries use both; both map to the same state). */
   closable: boolean;
+  /** Dunning mode only — ISO 4217 currency code driving the `Intl.NumberFormat` style="currency" rendering. Defaults to `USD`. */
+  currency: string;
   /** Public alias for [closable] — same semantics. Both attributes render the close button. Use whichever spelling matches your authoring style. */
   dismissible: boolean;
+  /** Dunning mode only — ISO 8601 due / failed-at timestamp. Formatted via `Intl.DateTimeFormat`. Ignored when [pattern] is not `dunning`. Attribute spelling: `due-at`. */
+  dueAt: string;
   /** Icon identifier displayed before the message content */
   icon: string;
+  /** Domain pattern mode. Default is empty (standard alert). Setting `pattern="dunning"` switches to billing dunning render mode — stamps a formatted amount + due-date + decline-reason from props and re-dispatches descendant `[data-dunning-action]` button clicks as a unified `dunning-action` event. Spec: SPEC-006. */
+  pattern: '' | 'dunning';
+  /** Dunning mode only — decline reason. Drives the leading icon (declined → `x-circle`, expired → `clock`, insufficient → `wallet`, network → `wifi-slash`). One of: `declined`, `expired`, `insufficient`, `network`, or empty. */
+  reason: '' | 'declined' | 'expired' | 'insufficient' | 'network';
   /** Single-line alert message. For two-line "headline + body" alerts, use [title] + [description] instead. For rich content (links, formatting), use the [slot="content"] slot. */
   text: string;
   /** Semantic color variant. */
@@ -44,4 +57,5 @@ export class UIAlert extends UIElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'close', listener: (ev: AlertCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'dunning-action', listener: (ev: AlertDunningActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/alert/alert.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAlert } from './class.js';
+import { UIAlert } from './alert.class.js';
 
 defineIfFree('alert-ui', UIAlert);
 

package/components/alert/alert.test.js

@@ -178,3 +178,187 @@ describe('alert-ui — full corpus shape (the §34 scenario)', () => {
     expect(content.querySelector('a').getAttribute('href')).toBe('/foo');
   });
 });
+
+describe('alert-ui — SPEC-006 dunning pattern', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('formats amount via Intl.NumberFormat with currency', async () => {
+    const a = mount(`<alert-ui pattern="dunning" amount="24.50" currency="USD"
+                               due-at="2026-05-20" card-last4="4242"
+                               reason="declined" variant="danger"></alert-ui>`);
+    await tick();
+    const amt = a.querySelector('[data-dunning-amount]');
+    expect(amt).not.toBeNull();
+    // en-US default formatting (jsdom): "$24.50"
+    expect(amt.textContent).toMatch(/\$24\.50|USD\s*24\.50/);
+  });
+
+  it('formats due date via Intl.DateTimeFormat', async () => {
+    const a = mount(`<alert-ui pattern="dunning" amount="24.50" currency="USD"
+                               due-at="2026-05-20T00:00:00Z"
+                               reason="declined" variant="danger"></alert-ui>`);
+    await tick();
+    const meta = a.querySelector('[data-dunning-meta]');
+    expect(meta).not.toBeNull();
+    // Expect month name + day + year somewhere in the meta
+    expect(meta.textContent).toMatch(/May/);
+    expect(meta.textContent).toMatch(/2026/);
+  });
+
+  it('stamps the cardLast4 metadata', async () => {
+    const a = mount(`<alert-ui pattern="dunning" amount="24.50" currency="USD"
+                               due-at="2026-05-20" card-last4="4242"
+                               reason="declined" variant="danger"></alert-ui>`);
+    await tick();
+    const meta = a.querySelector('[data-dunning-meta]');
+    expect(meta.textContent).toContain('ending 4242');
+  });
+
+  it('stamps x-circle icon for reason="declined"', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="declined" variant="danger"
+                               amount="10" currency="USD"></alert-ui>`);
+    await tick();
+    const icon = a.querySelector('[slot="leading"]');
+    expect(icon).not.toBeNull();
+    expect(icon.getAttribute('name')).toBe('x-circle');
+  });
+
+  it('stamps clock icon for reason="expired"', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="expired" variant="danger"
+                               amount="10" currency="USD"></alert-ui>`);
+    await tick();
+    const icon = a.querySelector('[slot="leading"]');
+    expect(icon.getAttribute('name')).toBe('clock');
+  });
+
+  it('dispatches dunning-action event on descendant [data-dunning-action] click', async () => {
+    const a = mount(`<alert-ui pattern="dunning" amount="24.50" currency="USD"
+                               due-at="2026-05-20" reason="declined" variant="danger">
+      <button-ui slot="actions" data-dunning-action="update" text="Update"></button-ui>
+      <button-ui slot="actions" data-dunning-action="retry" text="Retry"></button-ui>
+    </alert-ui>`);
+    await tick();
+
+    const received = [];
+    a.addEventListener('dunning-action', (e) => received.push(e.detail));
+
+    const updateBtn = a.querySelector('[data-dunning-action="update"]');
+    updateBtn.dispatchEvent(new Event('press', { bubbles: true }));
+    await tick();
+
+    expect(received.length).toBe(1);
+    expect(received[0].action).toBe('update');
+    expect(received[0].amount).toBe(24.5);
+    expect(received[0].currency).toBe('USD');
+    expect(received[0].dueAt).toBe('2026-05-20');
+  });
+
+  it('dispatches dunning-action with action="retry" when retry button is pressed', async () => {
+    const a = mount(`<alert-ui pattern="dunning" amount="10" currency="USD"
+                               due-at="2026-05-20" reason="declined" variant="danger">
+      <button-ui slot="actions" data-dunning-action="retry" text="Retry"></button-ui>
+    </alert-ui>`);
+    await tick();
+
+    const received = [];
+    a.addEventListener('dunning-action', (e) => received.push(e.detail));
+
+    const retryBtn = a.querySelector('[data-dunning-action="retry"]');
+    retryBtn.dispatchEvent(new Event('press', { bubbles: true }));
+    await tick();
+
+    expect(received.length).toBe(1);
+    expect(received[0].action).toBe('retry');
+  });
+
+  it('re-formats amount when the [amount] attribute changes', async () => {
+    const a = mount(`<alert-ui pattern="dunning" amount="10" currency="USD"
+                               due-at="2026-05-20" reason="declined" variant="danger"></alert-ui>`);
+    await tick();
+    let amt = a.querySelector('[data-dunning-amount]');
+    expect(amt.textContent).toMatch(/10/);
+
+    a.amount = 99.99;
+    await tick();
+    amt = a.querySelector('[data-dunning-amount]');
+    expect(amt.textContent).toMatch(/99\.99/);
+  });
+
+  it('inherits role="alert" for variant="danger" in dunning mode', async () => {
+    const a = mount(`<alert-ui pattern="dunning" variant="danger" amount="10" currency="USD"
+                               due-at="2026-05-20" reason="declined"></alert-ui>`);
+    await tick();
+    expect(a.getAttribute('role')).toBe('alert');
+  });
+
+  it('inherits role="alert" for variant="warning" (grace period)', async () => {
+    const a = mount(`<alert-ui pattern="dunning" variant="warning" amount="10" currency="USD"
+                               due-at="2026-06-01"></alert-ui>`);
+    await tick();
+    // warning maps to role=alert (same as danger via #updateRole)
+    expect(a.getAttribute('role')).toBe('alert');
+  });
+
+  it('grace-period (warning) uses "due" prefix in date meta, not "failed"', async () => {
+    const a = mount(`<alert-ui pattern="dunning" variant="warning" amount="10" currency="USD"
+                               due-at="2026-06-01"></alert-ui>`);
+    await tick();
+    const meta = a.querySelector('[data-dunning-meta]');
+    expect(meta.textContent).toContain('due');
+  });
+
+  it('default title for declined is "Payment failed"', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="declined" variant="danger"
+                               amount="10" currency="USD"></alert-ui>`);
+    await tick();
+    const titleEl = a.querySelector('[data-dunning-title]');
+    expect(titleEl.textContent).toBe('Payment failed');
+  });
+
+  it('default title for expired is "Card expired"', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="expired" variant="danger"
+                               amount="10" currency="USD"></alert-ui>`);
+    await tick();
+    const titleEl = a.querySelector('[data-dunning-title]');
+    expect(titleEl.textContent).toBe('Card expired');
+  });
+
+  it('explicit [title] overrides the per-reason default', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="declined" title="Custom message"
+                               amount="10" currency="USD" variant="danger"></alert-ui>`);
+    await tick();
+    const titleEl = a.querySelector('[data-dunning-title]');
+    expect(titleEl.textContent).toBe('Custom message');
+  });
+
+  it('explicit [icon] overrides the per-reason icon map', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="declined" icon="credit-card"
+                               amount="10" currency="USD" variant="danger"></alert-ui>`);
+    await tick();
+    const icon = a.querySelector('[slot="leading"]');
+    expect(icon.getAttribute('name')).toBe('credit-card');
+  });
+
+  it('composes aria-label from title + amount + meta', async () => {
+    const a = mount(`<alert-ui pattern="dunning" reason="declined" amount="24.50"
+                               currency="USD" due-at="2026-05-20" card-last4="4242"
+                               variant="danger"></alert-ui>`);
+    await tick();
+    const aria = a.getAttribute('aria-label');
+    expect(aria).toContain('Payment failed');
+    expect(aria).toMatch(/24\.50/);
+    expect(aria).toMatch(/4242/);
+  });
+
+  it('does not stamp dunning content when pattern is empty (standard mode)', async () => {
+    const a = mount(`<alert-ui variant="danger" amount="24.50" currency="USD"
+                               due-at="2026-05-20" reason="declined"
+                               text="standard message"></alert-ui>`);
+    await tick();
+    // No dunning markers — uses the standard text-only render path
+    expect(a.querySelector('[data-dunning-amount]')).toBeNull();
+    expect(a.querySelector('[data-dunning-title]')).toBeNull();
+    const content = a.querySelector(':scope > [slot="content"]');
+    expect(content.textContent.trim()).toBe('standard message');
+  });
+});

package/components/alert/alert.yaml

@@ -69,9 +69,73 @@ props:
       - danger
       - muted
       - neutral
+  pattern:
+    description: >-
+      Domain pattern mode. Default is empty (standard alert). Setting
+      `pattern="dunning"` switches to billing dunning render mode —
+      stamps a formatted amount + due-date + decline-reason from props
+      and re-dispatches descendant `[data-dunning-action]` button
+      clicks as a unified `dunning-action` event. Spec: SPEC-006.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - dunning
+  amount:
+    description: >-
+      Dunning mode only — the unpaid amount as a decimal major-unit
+      number (`24.50`, not minor units like `2450`). Formatted via
+      `Intl.NumberFormat` using [currency] and [lang]. Ignored when
+      [pattern] is not `dunning`.
+    type: number
+    default: 0
+  currency:
+    description: >-
+      Dunning mode only — ISO 4217 currency code driving the
+      `Intl.NumberFormat` style="currency" rendering. Defaults to
+      `USD`.
+    type: string
+    default: USD
+  dueAt:
+    description: >-
+      Dunning mode only — ISO 8601 due / failed-at timestamp.
+      Formatted via `Intl.DateTimeFormat`. Ignored when [pattern] is
+      not `dunning`. Attribute spelling: `due-at`.
+    type: string
+    default: ""
+    attribute: due-at
+  cardLast4:
+    description: >-
+      Dunning mode only — last 4 digits of the declined card.
+      Rendered as "ending 4242". Ignored when [pattern] is not
+      `dunning`. Attribute spelling: `card-last4`.
+    type: string
+    default: ""
+    attribute: card-last4
+  reason:
+    description: >-
+      Dunning mode only — decline reason. Drives the leading icon
+      (declined → `x-circle`, expired → `clock`, insufficient →
+      `wallet`, network → `wifi-slash`). One of: `declined`,
+      `expired`, `insufficient`, `network`, or empty.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - declined
+      - expired
+      - insufficient
+      - network
 events:
   close:
     description: Fired when the close button is clicked
+  dunning-action:
+    description: >-
+      Dunning pattern only — fired when a descendant button with
+      `[data-dunning-action]` is clicked. Detail shape `{ action,
+      amount, currency, dueAt }`; the action string is the value of
+      the `data-dunning-action` attribute (typically `"update"` or
+      `"retry"`).
 slots:
   content:
     description: >-
@@ -94,6 +158,12 @@ slots:
       Optional trailing action button (e.g. "Refresh", "Status page").
       Right-aligned in the flex layout. See system-banners pattern for
       examples.
+  actions:
+    description: >-
+      Dunning pattern only — action button stack (typically two
+      `<button-ui>` with `data-dunning-action="update"` and
+      `data-dunning-action="retry"`). Sits below the formatted message
+      in the col layout when `pattern="dunning"`.
 states:
   - name: idle
     description: Default, ready for interaction.
@@ -107,7 +177,19 @@ a2ui:
       reason: 'Ephemeral vs persistent boundary.'
     - rule: 'For modal-style critical alerts use <modal-ui> with alert content.'
       reason: 'Inline vs modal.'
-anti_patterns: []
+    - rule: 'Billing dunning / payment-failed notices use pattern="dunning" + amount + currency + dueAt props, NOT inlined into title/description strings.'
+      reason: 'Intl-formatting + unified telemetry via dunning-action event.'
+    - rule: 'pattern="dunning" SHOULD use variant="danger" (default) or variant="warning" (grace period); never variant="info" or "success".'
+      reason: 'Dunning is always a failure surface.'
+    - rule: 'When pattern="dunning", slot at least one button-ui in slot="actions" with data-dunning-action ("update" or "retry").'
+      reason: 'No actions = no resolution path.'
+anti_patterns:
+  - wrong: '<alert-ui pattern="dunning" variant="info">'
+    why: 'Dunning is always a failure surface; info mis-signals severity.'
+    fix: '<alert-ui pattern="dunning" variant="danger">'
+  - wrong: '<alert-ui pattern="dunning" title="Payment failed $24.50">'
+    why: 'Amount baked into title defeats Intl formatting + telemetry.'
+    fix: '<alert-ui pattern="dunning" amount="24.50" currency="USD" due-at="2026-05-20">'
 examples:
   - name: alert-banner
     description: Single alert component with icon and dismiss action.
@@ -164,6 +246,37 @@ examples:
           "variant": "primary"
         }
       ]
+  - name: dunning-payment-failed
+    description: Billing dunning banner — declined card with retry + update-card actions (SPEC-006).
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Alert",
+          "pattern": "dunning",
+          "variant": "danger",
+          "amount": 24.5,
+          "currency": "USD",
+          "dueAt": "2026-05-20T00:00:00Z",
+          "cardLast4": "4242",
+          "reason": "declined",
+          "children": ["btn-update", "btn-retry"]
+        },
+        {
+          "id": "btn-update",
+          "component": "Button",
+          "text": "Update payment method",
+          "variant": "primary",
+          "slot": "actions"
+        },
+        {
+          "id": "btn-retry",
+          "component": "Button",
+          "text": "Retry charge",
+          "variant": "outline",
+          "slot": "actions"
+        }
+      ]
 keywords:
   - alert
   - inbox

package/components/avatar/avatar-group.yaml

@@ -1,9 +1,9 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
-# component already existed as a sibling class in the parent's class.js
+# component already existed as a sibling class in the parent's avatar.class.js
 # + was registered alongside the parent (e.g. UIList + UIListItem both
-# from list/class.js). The catalog just lacked its own entry. With the
+# from list/list.class.js). The catalog just lacked its own entry. With the
 # §172 sibling-yaml scanner, this file gets picked up next to the parent
 # yaml.
 

package/components/avatar/avatar.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIAvatar, UIAvatarGroup } from './class.js';
+import { UIAvatar, UIAvatarGroup } from './avatar.class.js';
 
 defineIfFree('avatar-ui', UIAvatar);
 defineIfFree('avatar-group-ui', UIAvatarGroup);

package/components/badge/badge.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIBadge } from './class.js';
+import { UIBadge } from './badge.class.js';
 
 defineIfFree('badge-ui', UIBadge);
 

package/components/block/block.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIBlock } from './class.js';
+import { UIBlock } from './block.class.js';
 
 defineIfFree('block-ui', UIBlock);
 

package/components/breadcrumb/breadcrumb.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIBreadcrumb } from './class.js';
+import { UIBreadcrumb } from './breadcrumb.class.js';
 
 defineIfFree('breadcrumb-ui', UIBreadcrumb);
 

package/components/button/button.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIButton } from './class.js';
+import { UIButton } from './button.class.js';
 
 defineIfFree('button-ui', UIButton);
 

package/components/calendar-grid/calendar-grid.a2ui.json

@@ -31,6 +31,16 @@
       "type": "string",
       "default": ""
     },
+    "rangeEnd": {
+      "description": "End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the full contract.",
+      "type": "string",
+      "default": ""
+    },
+    "rangeStart": {
+      "description": "Start of a date range (ISO YYYY-MM-DD). When both rangeStart and rangeEnd are set + ordered, day cells strictly between the endpoints get `[data-in-range]` stamped for visual continuity. Used by `<date-range-picker-ui>` which pushes the same from/to onto both calendar panes. Endpoints themselves render via the `value` prop's `[data-selected]` state.",
+      "type": "string",
+      "default": ""
+    },
     "readonly": {
       "description": "Blocks selection but allows month navigation.",
       "type": "boolean",

package/components/calendar-grid/{class.js → calendar-grid.class.js}

@@ -65,6 +65,14 @@ export class UICalendarGrid extends UIElement {
     max:      { type: String,  default: '', reflect: true },
     disabled: { type: Boolean, default: false, reflect: true },
     readonly: { type: Boolean, default: false, reflect: true },
+    // Range-aware highlighting — when both rangeStart and rangeEnd are
+    // set, day cells whose date falls strictly between them get
+    // `[data-in-range]` stamped on them (the endpoints themselves get
+    // `[data-selected]` via the `value` prop). Consumers like
+    // <date-range-picker-ui> push the same from/to onto both panes so
+    // each independently lights up its in-range cells.
+    rangeStart: { type: String, default: '', reflect: true, attribute: 'range-start' },
+    rangeEnd:   { type: String, default: '', reflect: true, attribute: 'range-end' },
   };
 
   // No html`` template — we render imperatively via #renderCalendar so we can
@@ -142,6 +150,11 @@ export class UICalendarGrid extends UIElement {
     const selected = parseISO(this.value);
     const minDate  = parseISO(this.min);
     const maxDate  = parseISO(this.max);
+    // Range endpoints — only honor when BOTH are set + valid + ordered.
+    const rs = parseISO(this.rangeStart);
+    const re = parseISO(this.rangeEnd);
+    const rangeFrom = (rs && re && rs <= re) ? rs : null;
+    const rangeTo   = (rs && re && rs <= re) ? re : null;
 
     // Header — Prev / Title / Next
     let h = `<div data-cal-header>
@@ -174,15 +187,28 @@ export class UICalendarGrid extends UIElement {
       const isSelected = selected && sameDay(date, selected);
       const isDisabled = (minDate && date < minDate) || (maxDate && date > maxDate);
       const isFocused  = this.#focusedDay === d;
+      // In-range: strictly between rangeStart and rangeEnd (endpoints
+      // themselves render as `[data-selected]` via the `value` prop;
+      // marking them in-range too would double-up the styling).
+      const isInRange = !!(rangeFrom && rangeTo
+        && date > rangeFrom && date < rangeTo);
+      // Range endpoint flags — let CSS render the start/end cell with
+      // half-pill caps so the in-range strip reads as a continuous
+      // band when displayed next to the in-range cells.
+      const isRangeStart = !!(rangeFrom && sameDay(date, rangeFrom));
+      const isRangeEnd   = !!(rangeTo   && sameDay(date, rangeTo));
 
       const attrs = [
         'type="button"',
         'data-cal-day',
         `data-date="${iso}"`,
-        isToday    ? 'data-today' : '',
-        isSelected ? 'data-selected' : '',
-        isDisabled ? 'disabled' : '',
-        isFocused  ? 'data-focused' : '',
+        isToday      ? 'data-today' : '',
+        isSelected   ? 'data-selected' : '',
+        isInRange    ? 'data-in-range' : '',
+        isRangeStart ? 'data-range-start' : '',
+        isRangeEnd   ? 'data-range-end' : '',
+        isDisabled   ? 'disabled' : '',
+        isFocused    ? 'data-focused' : '',
         `tabindex="${isFocused ? '0' : '-1'}"`,
       ].filter(Boolean).join(' ');
 

package/components/calendar-grid/calendar-grid.css

@@ -52,6 +52,12 @@
     --calendar-grid-day-fg-hover-default:       var(--a-fg);
     --calendar-grid-day-bg-selected-default:    var(--a-accent);
     --calendar-grid-day-fg-selected-default:    var(--a-accent-fg);
+    /* In-range cells (strictly between rangeStart and rangeEnd) — muted
+       accent strip so the endpoints (full --a-accent fill) read as the
+       primary selection while the in-range band reads as secondary
+       context. Stylable independently of `selected`. */
+    --calendar-grid-day-bg-in-range-default:    var(--a-accent-muted);
+    --calendar-grid-day-fg-in-range-default:    var(--a-fg);
     --calendar-grid-day-fg-outside-default:     var(--a-fg-muted);
     --calendar-grid-day-fg-disabled-default:    var(--a-ui-text-disabled);
     --calendar-grid-day-today-color-default:    var(--a-accent);
@@ -193,6 +199,20 @@
     color: var(--calendar-grid-day-fg-selected, var(--calendar-grid-day-fg-selected-default));
   }
 
+  /* ── State: in-range ──
+     Cells strictly between rangeStart and rangeEnd get the muted accent
+     strip. Endpoints themselves render as `[data-selected]` (full accent
+     fill); the in-range middle is visually subordinate. `:not([data-selected])`
+     guard prevents the muted fill from overriding the endpoint cells in
+     consumer code that sets both `value` AND `range-start`/`range-end`. */
+  [data-cal-day][data-in-range]:not([data-selected]) {
+    background: var(--calendar-grid-day-bg-in-range, var(--calendar-grid-day-bg-in-range-default));
+    color: var(--calendar-grid-day-fg-in-range, var(--calendar-grid-day-fg-in-range-default));
+  }
+  [data-cal-day][data-in-range]:not([data-selected]):not([disabled]):hover {
+    background: var(--calendar-grid-day-bg-in-range, var(--calendar-grid-day-bg-in-range-default));
+  }
+
   /* ── State: today (unselected) ── */
   [data-cal-day][data-today]:not([data-selected]) {
     position: relative;

package/components/calendar-grid/calendar-grid.d.ts

@@ -22,6 +22,10 @@ export class UICalendarGrid extends UIElement {
   max: string;
   /** Minimum selectable date in ISO format (YYYY-MM-DD). */
   min: string;
+  /** End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the full contract. */
+  rangeEnd: string;
+  /** Start of a date range (ISO YYYY-MM-DD). When both rangeStart and rangeEnd are set + ordered, day cells strictly between the endpoints get `[data-in-range]` stamped for visual continuity. Used by `<date-range-picker-ui>` which pushes the same from/to onto both calendar panes. Endpoints themselves render via the `value` prop's `[data-selected]` state. */
+  rangeStart: string;
   /** Blocks selection but allows month navigation. */
   readonly: boolean;
   /** Selected date in ISO format (YYYY-MM-DD). */

package/components/calendar-grid/calendar-grid.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UICalendarGrid } from './class.js';
+import { UICalendarGrid } from './calendar-grid.class.js';
 
 defineIfFree('calendar-grid-ui', UICalendarGrid);
 

package/components/calendar-grid/calendar-grid.yaml

@@ -42,6 +42,26 @@ props:
     type: boolean
     default: false
     reflect: true
+  rangeStart:
+    description: >-
+      Start of a date range (ISO YYYY-MM-DD). When both rangeStart and
+      rangeEnd are set + ordered, day cells strictly between the
+      endpoints get `[data-in-range]` stamped for visual continuity.
+      Used by `<date-range-picker-ui>` which pushes the same from/to
+      onto both calendar panes. Endpoints themselves render via the
+      `value` prop's `[data-selected]` state.
+    type: string
+    default: ''
+    reflect: true
+    attribute: range-start
+  rangeEnd:
+    description: >-
+      End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the
+      full contract.
+    type: string
+    default: ''
+    reflect: true
+    attribute: range-end
 events:
   change:
     description: User selected a date. detail.value is the ISO string.

package/components/calendar-picker/calendar-picker.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UICalendarPicker } from './class.js';
+import { UICalendarPicker } from './calendar-picker.class.js';
 
 defineIfFree('calendar-picker-ui', UICalendarPicker);
 

package/components/card/card.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UICard } from './class.js';
+import { UICard } from './card.class.js';
 
 defineIfFree('card-ui', UICard);
 

package/components/chart/chart.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIChart } from './class.js';
+import { UIChart } from './chart.class.js';
 
 defineIfFree('chart-ui', UIChart);
 

package/components/chart-legend/chart-legend.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIChartLegend } from './class.js';
+import { UIChartLegend } from './chart-legend.class.js';
 
 defineIfFree('chart-legend-ui', UIChartLegend);