@adia-ai/web-components 0.6.33 → 0.6.34

package/components/date-range-picker/date-range-picker.test.js

@@ -0,0 +1,387 @@
+/**
+ * date-range-picker-ui — unit tests covering the SPEC-037 contract.
+ *
+ * Run under happy-dom (per vitest.config.js). showPopover/hidePopover are
+ * stubbed to no-ops by `packages/web-components/test-setup.js`, so popover
+ * state is tracked via the `open` reflected attribute and the `<popover>`
+ * div's presence, not via `:popover-open` selector matching.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import '../button/button.js';
+import '../popover/popover.js';
+import '../calendar-picker/calendar-picker.js';
+import '../divider/divider.js';
+import './date-range-picker.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html.trim();
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('date-range-picker-ui — structure + defaults', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('registers the custom element', () => {
+    expect(customElements.get('date-range-picker-ui')).toBeTruthy();
+  });
+
+  it('stamps a default <button-ui slot="trigger"> when no slot="trigger" is authored', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    expect(trigger).not.toBeNull();
+    expect(trigger.localName).toBe('button-ui');
+  });
+
+  it('stamps a popover container with role=dialog', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    const popover = el.querySelector(':scope > [slot="popover"]');
+    expect(popover).not.toBeNull();
+    expect(popover.getAttribute('role')).toBe('dialog');
+  });
+
+  it('stamps TWO <calendar-grid-ui> instances inside the popover', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    const calArea = el.querySelector(':scope > [slot="popover"] > [data-calendar-area]');
+    expect(calArea).not.toBeNull();
+    const cals = calArea.querySelectorAll(':scope > calendar-grid-ui');
+    expect(cals.length).toBe(2);
+    expect(cals[0].hasAttribute('data-cal-from')).toBe(true);
+    expect(cals[1].hasAttribute('data-cal-to')).toBe(true);
+  });
+
+  it('stamps a preset rail with the default 5 presets', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    const rail = el.querySelector(':scope > [slot="popover"] > [data-preset-rail]');
+    expect(rail).not.toBeNull();
+    const buttons = rail.querySelectorAll('button-ui[data-preset-label]');
+    expect(buttons.length).toBe(5);
+    expect(buttons[0].dataset.presetLabel).toBe('Today');
+  });
+
+  it('host carries role=combobox + aria-haspopup=dialog', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    expect(el.getAttribute('role')).toBe('combobox');
+    expect(el.getAttribute('aria-haspopup')).toBe('dialog');
+    expect(el.getAttribute('aria-expanded')).toBe('false');
+  });
+});
+
+describe('date-range-picker-ui — props + reflection', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('reflects [min] and [max] onto both calendar panes', async () => {
+    const el = mount('<date-range-picker-ui min="2026-01-01" max="2026-12-31"></date-range-picker-ui>');
+    await tick();
+    const cals = el.querySelectorAll('calendar-grid-ui');
+    expect(cals[0].getAttribute('min')).toBe('2026-01-01');
+    expect(cals[0].getAttribute('max')).toBe('2026-12-31');
+    expect(cals[1].getAttribute('min')).toBe('2026-01-01');
+    expect(cals[1].getAttribute('max')).toBe('2026-12-31');
+  });
+
+  it('parses JSON `value` into rangeValue', async () => {
+    const el = mount('<date-range-picker-ui value=\'{"from":"2026-01-01","to":"2026-01-07"}\'></date-range-picker-ui>');
+    await tick();
+    expect(el.rangeValue).toEqual({ from: '2026-01-01', to: '2026-01-07' });
+  });
+
+  it('renders formatted-range text in the trigger when value is set', async () => {
+    const el = mount('<date-range-picker-ui value=\'{"from":"2026-01-01","to":"2026-01-07"}\'></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    expect(trigger.getAttribute('text')).toContain('Jan 1, 2026');
+    expect(trigger.getAttribute('text')).toContain('Jan 7, 2026');
+  });
+
+  it('uses [placeholder] in the trigger when value is empty', async () => {
+    const el = mount('<date-range-picker-ui placeholder="Choose range"></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    expect(trigger.getAttribute('text')).toBe('Choose range');
+  });
+
+  it('reflects [comparison] as an attribute', async () => {
+    const el = mount('<date-range-picker-ui comparison></date-range-picker-ui>');
+    await tick();
+    expect(el.hasAttribute('comparison')).toBe(true);
+    expect(el.comparison).toBe(true);
+  });
+
+  it('[no-presets] removes the preset rail', async () => {
+    const el = mount('<date-range-picker-ui no-presets></date-range-picker-ui>');
+    await tick();
+    expect(el.querySelector(':scope > [slot="popover"] > [data-preset-rail]')).toBeNull();
+  });
+
+  it('custom `presets` property overrides the default list', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    el.presets = [
+      { label: 'Q1', range: { from: '2026-01-01', to: '2026-03-31' } },
+      { label: 'Q2', range: { from: '2026-04-01', to: '2026-06-30' } },
+    ];
+    await tick();
+    const rail = el.querySelector(':scope > [slot="popover"] > [data-preset-rail]');
+    const buttons = rail.querySelectorAll('button-ui[data-preset-label]');
+    expect(buttons.length).toBe(2);
+    expect(buttons[0].dataset.presetLabel).toBe('Q1');
+    expect(buttons[1].dataset.presetLabel).toBe('Q2');
+  });
+});
+
+describe('date-range-picker-ui — open/close behavior', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('opens on trigger click + emits `open` event', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    let openDetail = null;
+    el.addEventListener('open', (e) => { openDetail = e.detail; });
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    trigger.click();
+    await tick();
+    expect(el.open).toBe(true);
+    expect(el.hasAttribute('open')).toBe(true);
+    expect(el.getAttribute('aria-expanded')).toBe('true');
+    expect(openDetail?.trigger).toBe('click');
+  });
+
+  it('closes on second trigger click + emits `close`', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    let closeDetail = null;
+    el.addEventListener('close', (e) => { closeDetail = e.detail; });
+    trigger.click();
+    await tick();
+    trigger.click();
+    await tick();
+    expect(el.open).toBe(false);
+    expect(closeDetail).not.toBeNull();
+  });
+
+  it('Escape closes the popover + emits close with reason "escape"', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    el.open = true;
+    await tick();
+    let reason = null;
+    el.addEventListener('close', (e) => { reason = e.detail?.reason; });
+    const popover = el.querySelector(':scope > [slot="popover"]');
+    const ev = new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true });
+    popover.dispatchEvent(ev);
+    await tick();
+    expect(el.open).toBe(false);
+    expect(reason).toBe('escape');
+  });
+
+  it('Enter on the trigger opens the popover with trigger=keyboard', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    let openDetail = null;
+    el.addEventListener('open', (e) => { openDetail = e.detail; });
+    trigger.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+    await tick();
+    expect(el.open).toBe(true);
+    expect(openDetail?.trigger).toBe('keyboard');
+  });
+
+  it('[disabled] blocks the trigger from opening', async () => {
+    const el = mount('<date-range-picker-ui disabled></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    trigger.click();
+    await tick();
+    expect(el.open).toBe(false);
+  });
+
+  it('[readonly] blocks the popover from opening', async () => {
+    const el = mount('<date-range-picker-ui readonly></date-range-picker-ui>');
+    await tick();
+    const trigger = el.querySelector(':scope > [slot="trigger"]');
+    trigger.click();
+    await tick();
+    expect(el.open).toBe(false);
+  });
+});
+
+describe('date-range-picker-ui — selection + commit', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('clicking a preset commits value + closes popover + fires `change` with presetLabel', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    el.open = true;
+    await tick();
+    let detail = null;
+    el.addEventListener('change', (e) => { detail = e.detail; });
+    const rail = el.querySelector(':scope > [slot="popover"] > [data-preset-rail]');
+    const todayBtn = rail.querySelector('button-ui[data-preset-label="Today"]');
+    todayBtn.click();
+    await tick();
+    expect(detail).not.toBeNull();
+    expect(detail.presetLabel).toBe('Today');
+    expect(detail.value.from).toBe(detail.value.to);
+    expect(el.open).toBe(false);
+    expect(el.rangeValue).not.toBeNull();
+  });
+
+  it('applyPreset(label) commits the matching preset', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    let detail = null;
+    el.addEventListener('change', (e) => { detail = e.detail; });
+    const result = el.applyPreset('Last 7 days');
+    expect(result).toBe(true);
+    await tick();
+    expect(detail).not.toBeNull();
+    expect(detail.presetLabel).toBe('Last 7 days');
+    expect(detail.value.from < detail.value.to).toBe(true);
+  });
+
+  it('applyPreset(unknown) returns false and does not commit', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    let fired = false;
+    el.addEventListener('change', () => { fired = true; });
+    expect(el.applyPreset('NonExistent')).toBe(false);
+    expect(fired).toBe(false);
+  });
+
+  it('emits `input` (partial state) when only `from` is selected', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    let inputDetail = null;
+    let changeFired = false;
+    el.addEventListener('input', (e) => { inputDetail = e.detail; });
+    el.addEventListener('change', () => { changeFired = true; });
+    const calFrom = el.querySelector('calendar-grid-ui[data-cal-from]');
+    calFrom.value = '2026-03-15';
+    calFrom.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-03-15' } }));
+    await tick();
+    expect(inputDetail).not.toBeNull();
+    expect(inputDetail.value.from).toBe('2026-03-15');
+    expect(inputDetail.value.to).toBeNull();
+    expect(changeFired).toBe(false);
+  });
+
+  it('commits `change` when both panes have selections in order', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    let detail = null;
+    el.addEventListener('change', (e) => { detail = e.detail; });
+    const calFrom = el.querySelector('calendar-grid-ui[data-cal-from]');
+    const calTo = el.querySelector('calendar-grid-ui[data-cal-to]');
+    calFrom.value = '2026-03-01';
+    calFrom.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-03-01' } }));
+    await tick();
+    calTo.value = '2026-03-15';
+    calTo.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-03-15' } }));
+    await tick();
+    expect(detail).not.toBeNull();
+    expect(detail.value).toEqual({ from: '2026-03-01', to: '2026-03-15' });
+  });
+
+  it('reversed range fires `invalid`, not `change`', async () => {
+    const el = mount('<date-range-picker-ui></date-range-picker-ui>');
+    await tick();
+    let invalidDetail = null;
+    let changeFired = false;
+    el.addEventListener('invalid', (e) => { invalidDetail = e.detail; });
+    el.addEventListener('change', () => { changeFired = true; });
+    const calFrom = el.querySelector('calendar-grid-ui[data-cal-from]');
+    const calTo = el.querySelector('calendar-grid-ui[data-cal-to]');
+    // Click `to` first (with a date), then `from` AFTER it (reversed).
+    calTo.value = '2026-03-01';
+    calTo.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-03-01' } }));
+    await tick();
+    calFrom.value = '2026-03-15';
+    calFrom.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-03-15' } }));
+    await tick();
+    expect(invalidDetail).not.toBeNull();
+    expect(invalidDetail.reason).toBe('reversed');
+    expect(changeFired).toBe(false);
+  });
+
+  it('clear() resets the value', async () => {
+    const el = mount('<date-range-picker-ui value=\'{"from":"2026-01-01","to":"2026-01-07"}\'></date-range-picker-ui>');
+    await tick();
+    el.clear();
+    await tick();
+    expect(el.value).toBe('');
+    expect(el.rangeValue).toBeNull();
+  });
+});
+
+describe('date-range-picker-ui — comparison mode', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('adds a comparison preset cluster when [comparison] is set', async () => {
+    const el = mount('<date-range-picker-ui comparison></date-range-picker-ui>');
+    await tick();
+    const rail = el.querySelector(':scope > [slot="popover"] > [data-preset-rail]');
+    const cmpButtons = rail.querySelectorAll('button-ui[data-comparison-preset-label]');
+    expect(cmpButtons.length).toBe(3);
+    expect(cmpButtons[0].dataset.comparisonPresetLabel).toBe('Previous period');
+  });
+
+  it('parses compare-value into rangeCompareValue', async () => {
+    const el = mount('<date-range-picker-ui comparison compare-value=\'{"from":"2026-04-01","to":"2026-04-30"}\'></date-range-picker-ui>');
+    await tick();
+    expect(el.rangeCompareValue).toEqual({ from: '2026-04-01', to: '2026-04-30' });
+  });
+
+  it('change detail carries compareValue when comparison is set', async () => {
+    const el = mount('<date-range-picker-ui comparison compare-value=\'{"from":"2026-04-01","to":"2026-04-30"}\'></date-range-picker-ui>');
+    await tick();
+    let detail = null;
+    el.addEventListener('change', (e) => { detail = e.detail; });
+    const calFrom = el.querySelector('calendar-grid-ui[data-cal-from]');
+    const calTo = el.querySelector('calendar-grid-ui[data-cal-to]');
+    calFrom.value = '2026-05-01';
+    calFrom.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-05-01' } }));
+    await tick();
+    calTo.value = '2026-05-31';
+    calTo.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '2026-05-31' } }));
+    await tick();
+    expect(detail).not.toBeNull();
+    expect(detail.value).toEqual({ from: '2026-05-01', to: '2026-05-31' });
+    expect(detail.compareValue).toEqual({ from: '2026-04-01', to: '2026-04-30' });
+  });
+});
+
+describe('date-range-picker-ui — form participation', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('is form-associated', () => {
+    expect(customElements.get('date-range-picker-ui').formAssociated).toBe(true);
+  });
+
+  it('exposes ElementInternals via the host', async () => {
+    const el = mount('<date-range-picker-ui name="period"></date-range-picker-ui>');
+    await tick();
+    expect(el.internals).toBeDefined();
+    expect(typeof el.internals.setFormValue).toBe('function');
+  });
+
+  it('runs constraint validation on a reversed range (post-commit attempt is rejected)', async () => {
+    const el = mount('<date-range-picker-ui name="period" value=\'{"from":"2026-01-01","to":"2026-01-07"}\'></date-range-picker-ui>');
+    await tick();
+    // Apply a reversed range programmatically via direct value write,
+    // then sync — happy-dom's setValidity is a no-op, so we just confirm
+    // syncValue doesn't throw.
+    expect(() => el.syncValue('{"from":"2026-12-31","to":"2026-01-01"}')).not.toThrow();
+  });
+});

package/components/date-range-picker/date-range-picker.yaml

@@ -0,0 +1,285 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIDateRangePicker
+tag: date-range-picker-ui
+status: experimental
+component: DateRangePicker
+category: input
+version: 1
+description: >-
+  Compound form primitive for selecting a start + end date pair with
+  optional named preset shortcuts ("Today", "Last 7 days", "This month",
+  ...). Default presentation is a trigger button showing the formatted
+  range; on activation a popover opens with two synchronized calendar
+  panes + a preset side rail. Composes <calendar-picker-ui> twice;
+  emits {from, to} ISO 8601 dates. Optional comparison-range mode
+  emits a secondary range for analytics surfaces.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - calendar-grid-ui     # two grids (start + end) — substrate primitive
+  - button-ui            # trigger + preset rail + footer actions
+  - popover-ui           # the floating panel
+  - text-ui              # trigger label + preset labels
+  - divider-ui           # separator between preset rail and calendars
+props:
+  name:
+    description: Form field name for form data submission. The selected range serializes as JSON `{"from":"...","to":"..."}` under this key.
+    type: string
+    default: ''
+    reflect: true
+  value:
+    description: 'Selected range as `{from, to}` ISO 8601 dates. Null when empty. Emitted on commit.'
+    type: string
+    default: ''
+    dynamic: true
+  compareValue:
+    description: 'Comparison range when `[comparison]` is set. Same `{from, to}` shape as `value`.'
+    type: string
+    default: ''
+    attribute: compare-value
+    dynamic: true
+  comparison:
+    description: Enable comparison-range mode. Renders a second preset cluster and emits a secondary range under `<name>-compare`.
+    type: boolean
+    default: false
+    reflect: true
+  min:
+    description: Earliest selectable ISO date (inclusive). Days before are disabled in both panes.
+    type: string
+    default: ''
+    reflect: true
+  max:
+    description: Latest selectable ISO date (inclusive). Days after are disabled in both panes.
+    type: string
+    default: ''
+    reflect: true
+  disabled:
+    description: Block all interaction. Trigger remains rendered but does not open the popover.
+    type: boolean
+    default: false
+    reflect: true
+  readonly:
+    description: Block edits; allow keyboard navigation for screen-reader inspection.
+    type: boolean
+    default: false
+    reflect: true
+  required:
+    description: Required for validation when inside a `<form>`.
+    type: boolean
+    default: false
+    reflect: true
+  open:
+    description: Whether the popover is currently open.
+    type: boolean
+    default: false
+    reflect: true
+  placeholder:
+    description: Text shown in the trigger when the value is empty.
+    type: string
+    default: Select range
+  format:
+    description: 'Trigger button date format. `short`: `Jan 1, 2026`; `long`: `January 1, 2026`; `iso`: `2026-01-01`.'
+    type: string
+    default: short
+    enum:
+      - short
+      - long
+      - iso
+  noPresets:
+    description: Hide the preset side rail.
+    type: boolean
+    default: false
+    attribute: no-presets
+    reflect: true
+events:
+  change:
+    description: Fired when the range commits (both `from` AND `to` selected, OR a preset clicked).
+    detail:
+      value: object
+      compareValue: object
+      presetLabel: string
+  input:
+    description: Fired during selection — e.g. user clicked `from` but has not yet picked `to`.
+    detail:
+      value: object
+  open:
+    description: Popover opened (user clicked the trigger or pressed Enter / Space).
+    detail:
+      trigger: string
+  close:
+    description: Popover closed (without commit, or after commit).
+    detail:
+      reason: string
+  invalid:
+    description: A constraint failed (out of range, end < start).
+    detail:
+      value: object
+      reason: string
+slots:
+  trigger:
+    description: Custom trigger replacement. When omitted, a default `<button-ui>` is stamped.
+  presets:
+    description: Custom preset content replacing the default preset rail.
+  footer:
+    description: Optional footer area below the calendars (e.g., "Apply" / "Cancel" buttons for explicit-commit flows).
+states:
+  - name: idle
+    description: Closed, no pending selection.
+  - name: open-pending-from
+    description: Popover open, user has not yet clicked a start date.
+    attribute: open
+  - name: open-pending-to
+    description: Start clicked, awaiting end click; hover preview active.
+    attribute: open
+  - name: open-committed
+    description: Both ends clicked, awaiting Apply (only in explicit-commit mode with `footer` slot).
+    attribute: open
+  - name: disabled
+    description: Non-interactive; dimmed.
+    attribute: disabled
+  - name: readonly
+    description: Read-only; trigger keyboard-focusable but popover does not open.
+    attribute: readonly
+traits: []
+tokens:
+  --date-range-picker-bg:
+    description: Host background.
+    default: var(--a-bg)
+  --date-range-picker-popover-bg:
+    description: Popover background.
+    default: var(--a-bg-subtle)
+  --date-range-picker-popover-border:
+    description: Popover border color.
+    default: var(--a-border-subtle)
+  --date-range-picker-popover-radius:
+    description: Popover border radius.
+    default: var(--a-radius-lg)
+  --date-range-picker-popover-shadow:
+    description: Popover box shadow.
+    default: var(--a-shadow-lg)
+  --date-range-picker-preset-bg:
+    description: Preset row background (idle).
+    default: transparent
+  --date-range-picker-preset-bg-hover:
+    description: Preset row background on hover.
+    default: var(--a-bg-hover)
+  --date-range-picker-selected-bg:
+    description: Selected day-cell background (cascaded into the inner calendar via --calendar-picker-day-bg-selected).
+    default: var(--a-accent)
+  --date-range-picker-selected-fg:
+    description: Selected day-cell foreground.
+    default: var(--a-accent-fg)
+  --date-range-picker-preview-bg:
+    description: In-range preview background (between from and pending to).
+    default: var(--a-accent-muted)
+  --date-range-picker-px:
+    description: Horizontal popover padding.
+    default: var(--a-space-3)
+  --date-range-picker-py:
+    description: Vertical popover padding.
+    default: var(--a-space-2)
+requiredIcons:
+  - calendar
+  - caret-down
+  - arrow-right
+a2ui:
+  rules:
+    - rule: 'DateRangePicker.value MUST be `{from, to}` with both ISO 8601 dates, OR null. Either side null is invalid mid-state and the validator should reject it (use `input` event for partial state).'
+      reason: 'Range integrity contract.'
+    - rule: 'DateRangePicker.value.to MUST be `>=` value.from lexicographically. Reversed ranges trigger `invalid` and do NOT commit.'
+      reason: 'Range ordering constraint.'
+    - rule: 'When `comparison: true`, both `value` AND `compareValue` MUST be set on commit. If only one is set, the form participation emits the set one and omits the other.'
+      reason: 'Comparison-mode pairing.'
+    - rule: 'presets array entries each require both `label` (string) and `range` (`{from, to}`). Empty preset arrays are valid (rail renders empty).'
+      reason: 'Preset shape contract.'
+    - rule: 'Use DateRangePicker for date ranges. Do NOT compose two adjacent `<calendar-picker-ui>` instances + JS synchronization — that is the pattern this primitive replaces.'
+      reason: 'Adoption signal: prefer the canonical primitive over two-calendar composition.'
+anti_patterns:
+  - wrong: |
+      {"component": "DateRangePicker", "value": "2026-01-01 to 2026-01-31"}
+    why: |
+      `value` is a string, not an object. The contract is `{from, to}` ISO 8601 dates.
+    fix: |
+      {"component": "DateRangePicker", "value": {"from": "2026-01-01", "to": "2026-01-31"}}
+  - wrong: |
+      {"component": "DateRangePicker", "value": {"from": "2026-12-31", "to": "2026-01-01"}}
+    why: |
+      Reversed range — `to < from`. This fires `invalid` and never commits.
+    fix: |
+      {"component": "DateRangePicker", "value": {"from": "2026-01-01", "to": "2026-12-31"}}
+  - wrong: |
+      Two adjacent <calendar-picker-ui> instances + JS synchronization.
+    why: |
+      This is the pattern the primitive replaces. Reinvents linked-pane behavior,
+      misses preset rail, has no a11y range-announcement.
+    fix: |
+      Use <date-range-picker-ui>.
+examples:
+  - name: canonical
+    description: Form-field-wrapped picker with default presets.
+    a2ui: |
+      [
+        {
+          "id": "field",
+          "component": "Field",
+          "label": "Report period",
+          "children": ["dr"]
+        },
+        {
+          "id": "dr",
+          "component": "DateRangePicker",
+          "name": "report-period",
+          "min": "2026-01-01",
+          "max": "2026-12-31"
+        }
+      ]
+  - name: comparison
+    description: Analytics-surface picker with comparison range enabled.
+    a2ui: |
+      [
+        {
+          "id": "dr",
+          "component": "DateRangePicker",
+          "name": "period",
+          "comparison": true,
+          "value": {"from": "2026-05-01", "to": "2026-05-31"},
+          "compareValue": {"from": "2026-04-01", "to": "2026-04-30"}
+        }
+      ]
+  - name: no-presets
+    description: Custom-only picker with the preset rail hidden.
+    a2ui: |
+      [
+        {
+          "id": "dr",
+          "component": "DateRangePicker",
+          "name": "period",
+          "noPresets": true
+        }
+      ]
+keywords:
+  - daterangepicker
+  - date-range-picker
+  - date-range
+  - range
+  - daterange
+  - period
+  - reporting-period
+synonyms:
+  tags:
+    - DateRangePicker
+    - DateRange
+    - DateRangeInput
+  range:
+    - date-range
+    - period
+    - report-period
+  period:
+    - date-range
+    - range
+    - reporting-period
+related:
+  - calendar-picker
+  - popover
+  - field
+  - button