# ren-date-range-picker Component Contract

Two-date selection composite for ranges.

Load this file after `ren-design.md` and before generating, editing, or reviewing `ren-date-range-picker` UI.

## Purpose

- Provide the agent-facing public contract for the `ren-date-range-picker` composite.
- Keep generated markup aligned with the colocated CSS/JS source.
- Route theming through semantic tokens and the component token API instead of ad hoc styles.

## Use When

- You need the Date Range Picker composite behavior or visual role.
- The UI should stay inside RenDS' vanilla HTML/CSS/JS conventions.
- The implementation can use the public selectors, states, and imports listed here.

## Do Not Use When

- Native HTML plus `base/primitive-zero.md` is enough.
- A simpler primitive can express the UI without this composite.
- You would need to invent undocumented selectors, states, or JavaScript APIs.

## aiHints

```yaml
selectionCriteria:
  useWhen:
    - "User needs to pick a contiguous date range (start + end) confirmed by an explicit Apply action."
    - "UI needs dual side-by-side calendars (left = start month, right = next month) inside a CSS-anchor-positioned popover."
    - "Preset shortcuts like Last 7 / Last 30 / This Month / Last Month should be selectable as a sidebar listbox."
    - "Form submission needs two ISO-string fields named `<name>-start` and `<name>-end` via injected hidden inputs."
    - "Selection has Apply/Cancel semantics — draft state on outside-click or Cancel must revert to the previously confirmed range."
  avoidWhen:
    - "Only a single date is needed — use ren-date-picker (mode=\"single\")."
    - "User picks two unrelated dates (start-of-trip, end-of-warranty) that are not a contiguous range — use two ren-date-picker instances."
    - "Range needs commit-on-click without Apply/Cancel — use ren-date-picker with mode=\"range\"."
    - "No calendar UI is needed; a quick \"last N days\" preset is enough — render ren-select / ren-menu of presets only."

canonicalImports:
  css:
    - "rends/components/composites/ren-date-range-picker/ren-date-range-picker.css"
  js:
    - "rends/components/composites/ren-date-range-picker/ren-date-range-picker.js"
  notes:
    - "Also requires ren-calendar to be registered — the component instantiates two <ren-calendar mode=\"range\"> children inside the dropdown."
    - "If the page already imports rends/components/index.css, do not import the CSS again."
    - "UI strings (placeholder, dropdown/preset aria-labels, preset labels, Cancel/Apply, footer summary) come from utils/i18n.js and are resolved with t() while the DOM is built, so call setLocale() before the host upgrades — a locale switched after upgrade leaves the already-rendered labels in the previous language."

requiredMarkup:
  - "Use <ren-date-range-picker> as the host so the upgrade lifecycle builds the trigger, dropdown, dual calendars, presets, and hidden inputs."
  - "The trigger is a real <button class=\"ren-date-range-trigger\"> with aria-haspopup=\"dialog\" and aria-expanded; do not replace it with a div."
  - "The dropdown root carries role=\"dialog\", aria-label, and popover=\"manual\"; presets render inside role=\"listbox\" with each preset as role=\"option\" + data-preset=\"<key>\"."
  - "Footer must contain .ren-date-range-summary (aria-live=\"polite\"), .ren-date-range-cancel, and .ren-date-range-apply — Apply is disabled until both endpoints are set."
  - "Use `name=\"…\"` on the host so the component injects <input type=\"hidden\" name=\"<name>-start\"> and `…-end` for form submission."
  - "Use placement=\"bottom\" by default; the host and .ren-date-range-dropdown mirror the preferred side to data-side."
  - "Let the component own the anchor wiring: on upgrade it generates a name unique to that instance and writes it inline as `anchor-name` on its own .ren-date-range-trigger plus the matching `position-anchor` on its own .ren-date-range-dropdown. Nothing in the stylesheet names the anchor, so several pickers can share a page without their dropdowns colliding."

forbiddenPatterns:
  - "Wiring presets to a single ren-calendar instead of using both calendarLeft/calendarRight — the host depends on having two ren-calendar children to call setRange on."
  - "Skipping the Apply button and writing directly to the trigger — Cancel/outside-click revert depends on a draft vs confirmed split."
  - "Hardcoding dropdown placement offsets or breakpoints — use placement/data-side for side preference, and keep the container-type: inline-size @container ren-date-range layout under 500px."
  - "Adding extra inline color tokens to .ren-date-range-preset[aria-selected=\"true\"] — the highlighted preset already styles via --color-accent-subtle / --color-accent."
  - "Calling showPopover() directly from outside — use the host's open() / close() / handleApply() / handleCancel() so draft/confirmed state stays consistent."
  - "Declaring one shared `anchor-name` for .ren-date-range-trigger in stylesheet rules — anchor names are document-wide identifiers, so a name matched by more than one trigger resolves to the last one in tree order and every dropdown on the page then positions itself against that single trigger. To pin one picker to a custom anchor, set `anchor-name` inline on that instance's trigger; the component detects it, reuses it, and leaves it untouched on teardown."

tokenPolicy:
  allowed:
    - "Component tokens: --ren-calendar-bg, --ren-calendar-border, --ren-calendar-day-size, --ren-calendar-radius, --ren-calendar-range-bg, --ren-calendar-selected-bg, --ren-calendar-selected-color, --ren-calendar-today-bg, --ren-calendar-width."
    - "Semantic surface / text / accent tokens: --color-surface, --color-surface-raised, --color-border, --color-border-strong, --color-text, --color-text-secondary, --color-text-muted, --color-accent, --color-accent-hover, --color-accent-subtle, --color-on-accent, --color-fill, --color-fill-active, --color-danger, --color-success."
    - "Layout/motion tokens: --space-*, --radius-md, --radius-lg, --shadow-lg, --duration-enter, --ease-enter, --transition-tactile, --touch-min, --body-size, --label-size, --weight-semibold."
  forbidden:
    - "Primitive palette tokens (--blue-*, --gray-*, --red-*, --green-*, --orange-*, --yellow-*, --teal-*, --purple-*, --pink-*) in consumer code."
    - "Hardcoded hex / rgba colors for any of the trigger, dropdown, presets, or actions — theme via the semantic and --ren-calendar-* tokens."
    - "Custom transition durations; reuse --duration-enter / --ease-enter so reduced-motion handling continues to apply."

accessibility:
  required:
    - "Trigger is a real <button type=\"button\"> with aria-haspopup=\"dialog\" and aria-expanded synced to the dropdown state."
    - "Dropdown is role=\"dialog\" with aria-label=\"Date range selection\" (the default-locale value of dateRangePicker.label) and focuses the first preset (or first calendar day) on open."
    - "Preset listbox uses role=\"listbox\" with each .ren-date-range-preset as role=\"option\"; the active preset sets aria-selected=\"true\"."
    - ".ren-date-range-summary uses aria-live=\"polite\" so changes to the draft range are announced."
    - "Escape closes via Cancel semantics (reverts draft to confirmed); outside-click does the same — do not silently apply."
    - "Apply button is disabled (real disabled attribute) until both draftStart and draftEnd are present; do not bypass via aria-disabled alone."
```

## Required Imports

```html
<link rel="stylesheet" href="rends/components/composites/ren-date-range-picker/ren-date-range-picker.css">
<script type="module" src="rends/components/composites/ren-date-range-picker/ren-date-range-picker.js"></script>
```

If the page already imports `rends/components/index.css`, do not import the CSS twice.

## Canonical Markup

```html
<ren-date-range-picker name="stay" placement="bottom"><button class="ren-date-range-trigger" type="button" aria-haspopup="dialog" aria-expanded="false">Choose dates</button><div class="ren-date-range-dropdown" role="dialog" aria-label="Choose date range" popover="manual"><div class="ren-date-range-summary" aria-live="polite">No dates selected</div><button class="ren-date-range-cancel" type="button">Cancel</button><button class="ren-date-range-apply" type="button" disabled>Apply</button></div></ren-date-range-picker>

```

Use the docs page and source files listed below for full examples before adding production markup.

## Variants And Public Selectors

- `.ren-calendar`
- `.ren-date-range-actions`
- `.ren-date-range-apply`
- `.ren-date-range-calendars`
- `.ren-date-range-cancel`
- `.ren-date-range-divider`
- `.ren-date-range-dropdown`
- `.ren-date-range-empty`
- `.ren-date-range-end`
- `.ren-date-range-error`
- `.ren-date-range-footer`
- `.ren-date-range-inner`
- `.ren-date-range-picker`
- `.ren-date-range-preset`
- `.ren-date-range-presets`
- `.ren-date-range-separator`
- `.ren-date-range-start`
- `.ren-date-range-success`
- `.ren-date-range-summary`
- `.ren-date-range-trigger`
- `.ren-date-range-value`

## Anchor Positioning

The dropdown is placed with CSS anchor positioning, but the anchor identifier
never appears in the stylesheet. `anchor-name` is a document-wide identifier:
if the CSS declared one name for every trigger, the spec would resolve it to
the last matching trigger in tree order and each picker's dropdown would jump
to that trigger. Instead the JavaScript mints a name unique to each upgraded
instance and writes it inline — `anchor-name` on that instance's trigger,
`position-anchor` on that instance's dropdown — so any number of pickers can
coexist on one page. Removing a picker from the DOM removes only the inline
values it injected. Setting `anchor-name` inline on the trigger yourself wins:
the component points the dropdown at your name and leaves it in place. Browsers
without anchor positioning fall back to the fixed-position rules already in the
stylesheet.

## States And Attributes

- `[aria-selected]`
- `[data-side]`
- `placement`
- `:active`
- `:focus-visible`
- `:hover`

## Public Token API

- `--ren-calendar-bg`
- `--ren-calendar-border`
- `--ren-calendar-day-size`
- `--ren-calendar-radius`
- `--ren-calendar-range-bg`
- `--ren-calendar-selected-bg`
- `--ren-calendar-selected-color`
- `--ren-calendar-today-bg`
- `--ren-calendar-width`

Theme through these public custom properties before reaching for selectors.

## Accessibility Contract

- Preserve native semantics first; add ARIA only when semantic HTML is insufficient.
- Keep visible keyboard focus via RenDS focus tokens and `:focus-visible`.
- Keep interactive hit areas at 44px minimum unless this file's source clearly defines a smaller non-touch target.
- Respect reduced motion by using RenDS duration/easing tokens only.
- Do not communicate state through color alone.
- Keep JS behavior progressive: the visual structure should remain understandable before enhancement.

## Related Files

- `components/composites/ren-date-range-picker/ren-date-range-picker.css`
- `components/composites/ren-date-range-picker/ren-date-range-picker.js`
- `docs/components/ren-date-range-picker.html`
- `ren-design.md`
- `tokens/tokens.md`
- `base/layouts.md`

## Test Expectations

- Run component or docs a11y coverage when markup, states, or ARIA change.
- Run CSS lint when selectors, tokens, or visual states change.
- Manually verify light/dark themes when color, surface, border, or shadow behavior changes.

## Attribute lifecycle

`value`, `min`, `max`, `locale` are read when the component connects. Changing those attributes after mount is not a supported update mechanism; use only the documented methods for runtime changes. For a new initialization configuration, create a new component instance. `placement`, where documented, is reactive. Existing event names remain stable; see the [event reference](../../../docs/foundations/events.html).
