@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/date-picker.md

@@ -0,0 +1,514 @@
+# DatePicker
+
+Shows the selected date and opens a calendar in a popup.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/DatePicker.tsx)
+
+## Overview
+
+A date picker is a button that shows the selected date and opens a calendar in a popup. It has no text entry.
+
+## Examples
+
+### Basic
+
+```tsx
+import { DatePicker } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <DatePicker.Root>
+      <DatePicker.Trigger />
+      <DatePicker.Popup>
+        <DatePicker.Calendar />
+      </DatePicker.Popup>
+    </DatePicker.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Basic.tsx)
+
+### Variant
+
+Set `variant` on `DatePicker.Trigger` to `filled` (default) or `outlined`.
+
+```tsx
+import { DatePicker, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['filled', 'outlined'] as const).map((variant) => (
+        <DatePicker.Root key={variant}>
+          <DatePicker.Trigger variant={variant} />
+          <DatePicker.Popup>
+            <DatePicker.Calendar />
+          </DatePicker.Popup>
+        </DatePicker.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '24',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Variant.tsx)
+
+### Mode
+
+Set `mode="range"` on `DatePicker.Root` to select a range. It defaults to `single`.
+
+```tsx
+import { DatePicker } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <DatePicker.Root mode="range">
+      <DatePicker.Trigger placeholder="Select range" />
+      <DatePicker.Popup>
+        <DatePicker.Calendar />
+      </DatePicker.Popup>
+    </DatePicker.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Mode.tsx)
+
+### Invalid
+
+Set `aria-invalid` on `DatePicker.Trigger` to mark it invalid.
+
+```tsx
+import { DatePicker } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <DatePicker.Root>
+      <DatePicker.Trigger aria-invalid />
+      <DatePicker.Popup>
+        <DatePicker.Calendar />
+      </DatePicker.Popup>
+    </DatePicker.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Invalid.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { DatePicker } from '@tempoxyz/ds'
+
+<DatePicker.Root>
+  <DatePicker.Trigger />
+  <DatePicker.Popup>
+    <DatePicker.Calendar />
+  </DatePicker.Popup>
+</DatePicker.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Enter a date as one field in a form, such as the expiry date of an API key.
+* Enter a range with `mode="range"`, such as the period of a statement export.
+
+### When Not to Use
+
+* Use [Calendar](/docs/components/calendar) when the grid stays visible, such as in a filter panel.
+* Use [TextInput](/docs/components/text-input) for memorable dates far from today, such as a date of birth.
+* Use [ChoiceGroup](/docs/components/choice-group) or [Select](/docs/components/select) for preset periods, such as 7D or Last 30 days.
+
+### Label the Trigger
+
+The trigger shows only the date or the placeholder, and `Field.Label` doesn't link to it. Point its `aria-labelledby` at a visible label and at the trigger's own `id`.
+
+**Do:** Put a visible label above the trigger and reference it with `aria-labelledby`.
+
+```tsx
+/**
+ * Do example for "Label the Trigger" on the DatePicker page.
+ * Put a visible label above the trigger and reference it with `aria-labelledby`.
+ * @module
+ */
+import { DatePicker, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span id="guideline-expiry-label" {...styles.label()}>
+        Key expires on
+      </span>
+      <DatePicker.Root defaultValue={new Date(2027, 0, 31)}>
+        <DatePicker.Trigger
+          aria-labelledby="guideline-expiry-label guideline-expiry"
+          id="guideline-expiry"
+        />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
+}
+```
+
+**Don't:** Leave the trigger to explain itself with Select date.
+
+```tsx
+/**
+ * Don't example for "Label the Trigger" on the DatePicker page.
+ * Don't leave the trigger to explain itself with Select date.
+ * @module
+ */
+import { DatePicker, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <DatePicker.Root>
+        <DatePicker.Trigger />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', width: '100% !custom' })
+}
+```
+
+### State Date Limits in Text
+
+Pass `min`, `max`, and `isDateDisabled` to `DatePicker.Root`, which passes them to `DatePicker.Calendar`. Describe the limit below the trigger, and point `aria-describedby` at it.
+
+**Do:** State the allowed range below the trigger, such as Choose a date within one year.
+
+```tsx
+/**
+ * Do example for "State Date Limits in Text" on the DatePicker page.
+ * State the allowed range below the trigger, such as Choose a date within one year.
+ * @module
+ */
+import { DatePicker, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span id="guideline-stated-limit-label" {...styles.label()}>
+        Key expires on
+      </span>
+      <DatePicker.Root max={new Date(2027, 9, 21)} min={new Date(2026, 9, 21)}>
+        <DatePicker.Trigger
+          aria-labelledby="guideline-stated-limit-label guideline-stated-limit"
+          aria-describedby="guideline-stated-limit-hint"
+          id="guideline-stated-limit"
+        />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+      <span id="guideline-stated-limit-hint" {...styles.hint()}>
+        Choose a date within one year.
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
+
+  export const hint = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+**Don't:** Leave people to find the limit by paging through the calendar.
+
+```tsx
+/**
+ * Don't example for "State Date Limits in Text" on the DatePicker page.
+ * Don't leave people to find the limit by paging through the calendar.
+ * @module
+ */
+import { DatePicker, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span id="guideline-unstated-limit-label" {...styles.label()}>
+        Key expires on
+      </span>
+      <DatePicker.Root max={new Date(2027, 9, 21)} min={new Date(2026, 9, 21)}>
+        <DatePicker.Trigger
+          aria-labelledby="guideline-unstated-limit-label guideline-unstated-limit"
+          id="guideline-unstated-limit"
+        />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
+}
+```
+
+### Show Errors in Text
+
+Set `aria-invalid` on `DatePicker.Trigger` to fill it red. Put the error text below the trigger and point `aria-describedby` at it. `Field.Error` doesn't link to the trigger.
+
+**Do:** Pair the red fill with error text that names the fix.
+
+```tsx
+/**
+ * Do example for "Show Errors in Text" on the DatePicker page.
+ * Pair the red fill with error text that names the fix.
+ * @module
+ */
+import { DatePicker, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span id="guideline-error-text-label" {...styles.label()}>
+        Key expires on
+      </span>
+      <DatePicker.Root defaultValue={new Date(2026, 9, 1)}>
+        <DatePicker.Trigger
+          aria-labelledby="guideline-error-text-label guideline-error-text"
+          aria-describedby="guideline-error-text-error"
+          aria-invalid
+          id="guideline-error-text"
+        />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+      <span id="guideline-error-text-error" {...styles.error()}>
+        Choose a date after today.
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
+
+  export const error = style({ color: 'content.negative', typography: 'body.b3' })
+}
+```
+
+**Don't:** Mark the trigger invalid without saying what is wrong.
+
+```tsx
+/**
+ * Don't example for "Show Errors in Text" on the DatePicker page.
+ * Don't mark the trigger invalid without saying what is wrong.
+ * @module
+ */
+import { DatePicker, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span id="guideline-error-ring-label" {...styles.label()}>
+        Key expires on
+      </span>
+      <DatePicker.Root defaultValue={new Date(2026, 9, 1)}>
+        <DatePicker.Trigger
+          aria-labelledby="guideline-error-ring-label guideline-error-ring"
+          aria-invalid
+          id="guideline-error-ring"
+        />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
+}
+```
+
+### Match the Fields Around It
+
+`DatePicker.Trigger` is as tall as a [TextInput](/docs/components/text-input), at 48px. Use the same variant as the fields beside it.
+
+**Do:** Give the trigger the variant of the inputs in the same row.
+
+```tsx
+/**
+ * Do example for "Match the Fields Around It" on the DatePicker page.
+ * Give the trigger the variant of the inputs in the same row.
+ * @module
+ */
+import { DatePicker, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <TextInput.Group {...styles.cell()}>
+        <TextInput.Control aria-label="Key name" defaultValue="Checkout server" />
+      </TextInput.Group>
+      <DatePicker.Root defaultValue={new Date(2027, 0, 31)}>
+        <DatePicker.Trigger aria-label="Key expires on" {...styles.cell()} />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const cell = style({ flex: '1 !custom', minWidth: '0 !custom' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '8',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Mix an `outlined` trigger with filled inputs.
+
+```tsx
+/**
+ * Don't example for "Match the Fields Around It" on the DatePicker page.
+ * Don't mix an `outlined` trigger with filled inputs.
+ * @module
+ */
+import { DatePicker, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <TextInput.Group {...styles.cell()}>
+        <TextInput.Control aria-label="Key name" defaultValue="Checkout server" />
+      </TextInput.Group>
+      <DatePicker.Root defaultValue={new Date(2027, 0, 31)}>
+        <DatePicker.Trigger aria-label="Key expires on" variant="outlined" {...styles.cell()} />
+        <DatePicker.Popup>
+          <DatePicker.Calendar />
+        </DatePicker.Popup>
+      </DatePicker.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const cell = style({ flex: '1 !custom', minWidth: '0 !custom' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '8',
+    width: '100% !custom',
+  })
+}
+```
+
+## Content
+
+* **Label:** Name the date, such as Key expires on or Start date.
+* **Placeholder:** Keep Select date in single mode. In range mode, use Select dates.
+* **Value:** The trigger formats it with `Intl.DateTimeFormat` in the medium date style for `locale`, such as Jan 31, 2027, and a range as one span.
+
+## Accessibility
+
+A date picker renders a button that opens a calendar in a popup dialog. It follows the [WAI-ARIA Authoring Practices date picker dialog example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/), except that the popup is not modal.
+
+### Semantics
+
+* **DatePicker.Trigger (button):** Announces that it opens a dialog, and whether the dialog is open.
+* **DatePicker.Popup (dialog):** Renders a `dialog` named "Choose date" unless you pass `aria-label`.
+* **DatePicker.Calendar (grid):** Uses the grid semantics described on [Calendar](/docs/components/calendar#accessibility).
+* **Target Size (48px):** The trigger is above the 24px WCAG 2.2 minimum.
+
+### Keyboard
+
+* **Move Focus to the Trigger (Tab):** Moves focus to the trigger.
+* **Open the Popup (Enter or Space):** On the trigger, opens the popup and focuses a day.
+* **Move Through Dates (Arrow keys):** Home, End, Page Up, and Page Down also move, as on [Calendar](/docs/components/calendar#keyboard).
+* **Select a Day (Enter or Space):** On a day, selects it and closes the popup. In `range` mode, the popup closes after the end date.
+* **Move Within the Popup (Tab and Shift+Tab):** Move between the month buttons and the day grid.
+* **Close the Popup (Escape):** Closes the popup without a change, and returns focus to the trigger.
+
+### Focus
+
+When the popup opens, focus moves to the selected day, or today. The popup doesn't trap focus, so Tab can leave it.
+
+### Your Responsibilities
+
+* **Name the Trigger (aria-labelledby):** Point it at the visible label and the trigger, so the name includes the date.
+* **Name Each Popup (aria-label):** If a page has several pickers, name each popup, such as "Choose start date".
+* **Link the Error Text (aria-describedby):** Point it at the error text below the trigger.
+
+## Related
+
+[Calendar](/docs/components/calendar)
+
+Use for an inline month grid.
+
+[TextInput](/docs/components/text-input)
+
+Use for typed and native dates.
+
+[Popover](/docs/components/popover)
+
+Use for other anchored popups.
+
+[Field](/docs/components/field)
+
+Use for labels and errors on other controls.
+
+[Forms](/docs/patterns/forms)
+
+Covers placing a date among other fields.