parent
65039c1c4c
commit
382446199a
@ -0,0 +1,104 @@
|
||||
# TimePicker
|
||||
|
||||
`TimeField` + `Popover` with slider controls for hour / minute / second and an optional AM/PM toggle. The segmented input and the popover controls share the same provider state, so keyboard editing and pointer dragging stay in sync.
|
||||
|
||||
## Anatomy
|
||||
|
||||
```svelte
|
||||
<TimePicker.Provider bind:value bind:open placeholder={new Time(9, 0)}>
|
||||
<TimePicker.Label>Start time</TimePicker.Label>
|
||||
<TimePicker.Input name="start_time" aria-label="Start time">
|
||||
{#snippet children({ segments })}
|
||||
{#each segments as { part, value } (part + value)}
|
||||
<TimePicker.Segment {part}>{value}</TimePicker.Segment>
|
||||
{/each}
|
||||
{/snippet}
|
||||
</TimePicker.Input>
|
||||
|
||||
<TimePicker.Trigger>Open</TimePicker.Trigger>
|
||||
|
||||
<TimePicker.Content side="bottom" align="end" sideOffset={8}>
|
||||
<TimePicker.DayPeriodToggle />
|
||||
<TimePicker.HourSlider>
|
||||
<TimePicker.Range />
|
||||
<TimePicker.Thumb index={0} />
|
||||
</TimePicker.HourSlider>
|
||||
<TimePicker.MinuteSlider>
|
||||
<TimePicker.Range />
|
||||
<TimePicker.Thumb index={0} />
|
||||
</TimePicker.MinuteSlider>
|
||||
<TimePicker.SecondSlider>
|
||||
<TimePicker.Range />
|
||||
<TimePicker.Thumb index={0} />
|
||||
</TimePicker.SecondSlider>
|
||||
</TimePicker.Content>
|
||||
</TimePicker.Provider>
|
||||
```
|
||||
|
||||
## Parts
|
||||
|
||||
| Part | Source | Description |
|
||||
| ----------------- | ---------- | --------------------------------------------------------------- |
|
||||
| `Provider` | picker | Shared value, placeholder, open state and composed providers. |
|
||||
| `Trigger` | picker | Popover trigger button. |
|
||||
| `HourSlider` | picker | Single-value slider for the hour segment. |
|
||||
| `MinuteSlider` | picker | Single-value slider for the minute segment. |
|
||||
| `SecondSlider` | picker | Single-value slider for the second segment. |
|
||||
| `DayPeriodToggle` | picker | AM/PM radio group, rendered only when the resolved cycle is 12. |
|
||||
| `Label` | TimeField | Re-export. Labels the segmented input. |
|
||||
| `Input` | TimeField | Re-export. Emits the editable time segments. |
|
||||
| `Segment` | TimeField | Re-export. Individual editable segment. |
|
||||
| `HiddenInput` | TimeField | Re-export. Form value when `name` is set. |
|
||||
| `Content` | Popover | Re-export. Floating surface for picker controls. |
|
||||
| `Arrow` | Popover | Re-export. |
|
||||
| `Close` | Popover | Re-export. |
|
||||
| `Overlay` | Popover | Re-export. |
|
||||
| `Anchor` | Popover | Re-export. |
|
||||
| `Thumb` | Slider | Re-export. Used inside picker sliders. |
|
||||
| `Range` | Slider | Re-export. Used inside picker sliders. |
|
||||
| `Tick` | Slider | Re-export. Optional tick marks. |
|
||||
|
||||
## ARIA
|
||||
|
||||
- `Trigger` inherits Popover trigger semantics and adds the component-owned translated label when no `aria-label` is supplied.
|
||||
- Sliders emit `role="slider"` through the composed Slider provider, with localized thumb labels for hour / minute / second.
|
||||
- `DayPeriodToggle` emits `role="radiogroup"` and disables itself when the picker or the `dayPeriod` segment is readonly.
|
||||
- Input and Segment inherit TimeField ARIA, validation, and hidden-description behavior.
|
||||
|
||||
## Data Attributes
|
||||
|
||||
| Part | Attribute | Values |
|
||||
| ----------------- | --------------------------------- | ---------------------------- |
|
||||
| Trigger | `data-time-picker-trigger` | Always present |
|
||||
| Trigger | `data-state` | `open` \| `closed` |
|
||||
| DayPeriodToggle | `data-time-picker-day-period-toggle` | Always present |
|
||||
| DayPeriodItem | `data-time-picker-day-period-item` | Always present |
|
||||
| DayPeriodItem | `data-checked` | Present for the active item |
|
||||
| Content / Arrow / Close / Overlay / Anchor | + all `data-popover-*` | Inherited from Popover |
|
||||
| Input / Segment / HiddenInput | + all `data-time-field-*` | Inherited from TimeField |
|
||||
| HourSlider / MinuteSlider / SecondSlider | + all `data-slider-*` | Inherited from Slider |
|
||||
|
||||
## Props
|
||||
|
||||
See `types.ts` for the full typed surface. Summary:
|
||||
|
||||
| Prop | Type | Notes |
|
||||
| ---------------------------------------- | -------------------------------- | --------------------------------------------------- |
|
||||
| `value` | `TimeValue \| undefined` | Bindable. |
|
||||
| `placeholder` | `TimeValue` | Bindable; defaults to the current clock time. |
|
||||
| `open` | `boolean` | Bindable popover state. |
|
||||
| `onOpenChangeComplete` | `(open) => void` | Called after open-state completion. |
|
||||
| `validate` / `onInvalid` | time validation callbacks | Same validation model as TimeField. |
|
||||
| `minValue` / `maxValue` | `TimeValue` | Bounds for valid values. |
|
||||
| `disabled` / `readonly` / `required` | `boolean` | Forwarded to the composed TimeField and sliders. |
|
||||
| `readonlySegments` | `EditableTimeSegmentPart[]` | Locks individual segments, including `dayPeriod`. |
|
||||
| `granularity` | `'hour' \| 'minute' \| 'second'` | Controls the field segment set. |
|
||||
| `hideTimeZone` | `boolean` | For ZonedDateTime placeholders. |
|
||||
| `hourCycle` | `12 \| 24` | Explicit cycle; otherwise resolved from Soma/locale.|
|
||||
| `hourStep` / `minuteStep` / `secondStep` | `number` | Slider step sizes. Default `1`. |
|
||||
| `locale` / `dir` | `string` / `'ltr' \| 'rtl'` | Override Soma defaults. |
|
||||
| `errorMessageId` | `string` | External error id for `aria-describedby`. |
|
||||
|
||||
## Notes
|
||||
|
||||
`TimePicker` is a composed component. Popover, TimeField and Slider own their own runtime parts; the picker only owns the coordinating provider, trigger and time-specific controls.
|
||||
Loading…
Reference in new issue