@scattered-light/loomiere-base-ui 0.6.0 → 0.7.0

package/dist/design-system/components/DatePicker/README.md

@@ -0,0 +1,55 @@
+# DatePicker
+
+Loomiere component, not part of Base UI. DatePicker: a field that opens a calendar for one date or a period. Not a Base UI part. The popup is Popover on a wide viewport and Drawer below the md breakpoint. Calendar is the grid on its own; DatePresets is the quick-selection list. Both are usable without the field. Concepts: calendar (day cell, range band, today ring), item (preset rows), field (the trigger), emphasis bold (the selected day, via the default emphasis level, so it follows data-color). Text styles, one whole style each: day numbers are trigger-condense and selected days are selected-condense, weekday initials are eyebrow-minimize, the month title is subtitle-base, a preset label is trigger-condense with its hint in body-minimize, and the footer summary is body-condense. The trigger text is text-body-base, the same style as Input. How many months are on screen is measured on the panel (40rem two months, 32rem one, and one month in a drawer or for a coarse pointer under 48rem). Those lengths are layout, not tokens. CSS only switches the preset row and the sticky footer, from data-layout and data-compact. Keyboard (WAI-ARIA APG date picker dialog): Left/Right one day (they swap in RTL), Up/Down one week, Home/End the week, PageUp/PageDown one month, Shift+PageUp/PageDown one year, Enter/Space pick. With two months showing, paging forward lands the focused day in the last column, so the view shifts by one month. Delete or Backspace clears the draft. Escape drops a half-picked range first, then closes. Escape in the month or year chooser returns to the days. A range is a start click, then an end click; an end before the start swaps. Hover or focus previews the band until the end is chosen. Direction is read when the picker opens; a dir change while it is open is not picked up. Day state: data-selected, data-range-start, data-range-end, data-in-range, data-preview, data-today, data-outside-month, data-disabled, data-focused. aria-selected is only the real value (the day, or the start and end).
+
+Use `Loomiere.DatePicker`, this package's component: it puts the class names on for you (`import { DatePicker } from '@scattered-light/loomiere-base-ui'`, or from `@scattered-light/loomiere-base-ui/custom`).
+
+Not a Base UI part, so there is no base-ui.com page for it.
+
+## Classes
+
+| Class | Data attributes it answers to |
+|---|---|
+| `Calendar` |   |
+| `DatePickerMonths` |   |
+| `DatePickerNav` |   |
+| `DatePickerMonthTitle` |   |
+| `DatePickerMonth` |   |
+| `DatePickerMonthBar` |   |
+| `DatePickerMonthSpacer` |   |
+| `CalendarGrid` |   |
+| `DatePickerPanel` | `data-touch`; `data-layout`: `row`; `data-compact` |
+| `CalendarWeek` |   |
+| `CalendarWeekday` |   |
+| `CalendarWeekNumber` |   |
+| `CalendarDay` | `data-disabled`; `data-selected`; `data-outside-month`; `data-range-start`; `data-range-end`; `data-in-range`; `data-preview`; `data-focused`; `data-today` |
+| `CalendarDayNumber` |   |
+| `CalendarChooser` |   |
+| `CalendarChooserGrid` |   |
+| `CalendarChoice` |   |
+| `DatePickerPresets` | `data-layout`: `row` |
+| `DatePickerPreset` | `data-disabled`; `data-checked` |
+| `DatePickerPresetHint` |   |
+| `DatePickerField` |   |
+| `DatePickerTrigger` |   |
+| `DatePickerValue` | `data-placeholder` |
+| `DatePickerClear` |   |
+| `DatePickerPopup` | `data-months`: `3` |
+| `DatePickerFooter` |   |
+| `DatePickerSummary` |   |
+| `DatePickerActions` |   |
+| `DatePickerApply` |   |
+
+Base UI sets the state attributes (`data-checked`, `data-open`, `data-disabled`...) itself. Set `data-size`, `data-emphasis`, `data-variant` and `data-color` yourself; `data-color` takes any palette name (`primary`, `secondary`, `error`...) and repaints the part in it.
+
+## Example
+
+From the DatePicker stories (`Default`):
+
+```tsx
+export const Default: Story = {
+  args: { mode: 'range', label: 'Trip dates', placeholder: 'Choose dates' },
+};
+```
+
+The preview also shows `Single`, `ThreeMonths`, `CustomPresets`.