@invoiceonline/ui-react 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +4 -3
- package/CHANGELOG.md +18 -0
- package/dist/components/date-picker/DatePicker.js +1 -1
- package/dist/components/field/Field.d.ts +2 -1
- package/dist/components/field/Field.js +13 -8
- package/dist/components/field-pair/FieldPair.d.ts +29 -13
- package/dist/components/field-pair/FieldPair.js +20 -6
- package/dist/components/text-field/TextField.d.ts +97 -2
- package/dist/components/text-field/TextField.js +76 -5
- package/dist/components/text-field/index.d.ts +2 -2
- package/dist/components/textarea/Textarea.js +1 -1
- package/dist/components/unit-field/UnitField.js +1 -1
- package/dist/index.d.ts +3 -5
- package/dist/index.js +2 -3
- package/dist/internal/useDateFieldTrigger.d.ts +60 -0
- package/dist/internal/useDateFieldTrigger.js +68 -16
- package/dist/internal/useFormReset.js +10 -3
- package/docs/Consuming.mdx +20 -3
- package/llms.txt +7 -13
- package/package.json +1 -5
- package/src/components/date-picker/DatePicker.mdx +18 -14
- package/src/components/date-picker/DatePicker.stories.tsx +1 -1
- package/src/components/field/Field.tsx +40 -18
- package/src/components/field-pair/FieldPair.mdx +13 -9
- package/src/components/field-pair/FieldPair.stories.tsx +11 -2
- package/src/components/field-pair/FieldPair.tsx +76 -27
- package/src/components/filter-facet/FilterFacet.tsx +1 -1
- package/src/components/subject-lookup-field/SubjectLookupField.tsx +3 -3
- package/src/components/text-field/TextField.mdx +258 -38
- package/src/components/text-field/TextField.stories.tsx +311 -3
- package/src/components/text-field/TextField.tsx +259 -5
- package/src/components/text-field/index.ts +3 -0
- package/src/components/textarea/Textarea.mdx +2 -2
- package/src/components/textarea/Textarea.tsx +1 -1
- package/src/components/unit-field/UnitField.mdx +1 -1
- package/src/components/unit-field/UnitField.tsx +1 -1
- package/src/index.ts +0 -1
- package/src/internal/useDateFieldTrigger.tsx +178 -38
- package/src/internal/useFormReset.ts +13 -3
- package/src/recipes/Form.stories.tsx +5 -0
- package/dist/components/date-field/DateField.d.ts +0 -52
- package/dist/components/date-field/DateField.js +0 -45
- package/dist/components/date-field/index.d.ts +0 -2
- package/dist/components/date-field/index.js +0 -1
- package/src/components/date-field/DateField.mdx +0 -340
- package/src/components/date-field/DateField.stories.tsx +0 -221
- package/src/components/date-field/DateField.tsx +0 -176
- package/src/components/date-field/index.ts +0 -1
|
@@ -1,340 +0,0 @@
|
|
|
1
|
-
import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
|
|
2
|
-
import * as DateFieldStories from './DateField.stories';
|
|
3
|
-
|
|
4
|
-
<Meta of={DateFieldStories} tags={['autodocs']} />
|
|
5
|
-
|
|
6
|
-
# DateField
|
|
7
|
-
|
|
8
|
-
## Metadata
|
|
9
|
-
|
|
10
|
-
- **Layer:** molecule
|
|
11
|
-
- **Status:** stable
|
|
12
|
-
- **Tokens used:** `--bg-primary`, `--bg-readonly`, `--border-width-100`, `--border-width-200`, `--disabled-background`, `--disabled-foreground`, `--font-body`, `--font-size-base`, `--font-weight-normal`, `--icon-muted`, `--leading-relaxed`, `--outline-default`, `--outline-focus`, `--radius-200`, `--radius-400`, `--space-1000`, `--space-1100`, `--space-400`, `--space-500`, `--status-danger`, `--status-success-solid`, `--text-placeholder`, `--text-primary`, `--text-secondary`
|
|
13
|
-
- **Manifest version:** `1.2.1` (`spec/04-molecules/date-picker.manifest.json` — the panel's manifest; DateField has no manifest of its own)
|
|
14
|
-
|
|
15
|
-
## Overview
|
|
16
|
-
|
|
17
|
-
DateField is the field a Date Picker opens from — a Text Field shell with a calendar glyph in the
|
|
18
|
-
leading slot. Because it is a real editable `<input>`, a date can be **typed as well as picked**;
|
|
19
|
-
the typed draft is parsed against `dateFormat` on blur. Use it for any single date in a form: expense
|
|
20
|
-
date, invoice issue date, taxable date, due date. **Do not** use it for a date *range* — reach for the
|
|
21
|
-
dual-month [`DatePicker`](?path=/docs/design-system-molecules-datepicker--docs) directly, this field
|
|
22
|
-
holds one date. Do not use it for a free-form "period" or "month" selector either; the panel is a day
|
|
23
|
-
grid.
|
|
24
|
-
|
|
25
|
-
**Typing is bounded exactly like picking.** A draft that does not parse is discarded rather than
|
|
26
|
-
coerced — and so is one that parses but lands outside `minDate` / `maxDate`, since the panel disables
|
|
27
|
-
those days outright. In both cases `onValueChange` is not called at all and the field falls back to the
|
|
28
|
-
value it still holds, so a controlled value can never leave the bounds by the keyboard route.
|
|
29
|
-
|
|
30
|
-
**One user action reports one value.** Clicking a day over a half-typed draft does not commit the draft
|
|
31
|
-
first: the panel is a non-modal portal, so the click blurs the input before it selects, and that blur is
|
|
32
|
-
recognised as focus moving *into* the panel rather than the end of editing. Only the picked day reaches
|
|
33
|
-
`onValueChange`, so validation or autosave hung off it runs once — never on an intermediate the user
|
|
34
|
-
never meant to submit. The draft survives paging the calendar and returning to the input.
|
|
35
|
-
|
|
36
|
-
## Rationale
|
|
37
|
-
|
|
38
|
-
Upstream is explicit that a date field is a **sibling of Text Field, not a Select**:
|
|
39
|
-
|
|
40
|
-
- `_text-field-inventory.md` lists *"Date — issue date, taxable date"* as a **Text Field row**, while
|
|
41
|
-
Selects sit in a separate section titled *"Adjacent — not a Text Field"*.
|
|
42
|
-
- `_text-field-planning.md`, decision 2: *"**Textarea** and **Date Picker** are **separate siblings**
|
|
43
|
-
that reuse `_inputShell`."*
|
|
44
|
-
|
|
45
|
-
That is why the `SelectField` pattern (a read-only `<button role="combobox">`) is **deliberately not
|
|
46
|
-
reused** here: it would take typing away. For a keyboard user filling a long invoice form, keying a
|
|
47
|
-
date is faster than paging through a calendar.
|
|
48
|
-
|
|
49
|
-
**The whole field is the trigger, and the glyph is decoration.** No spec file states which side the
|
|
50
|
-
glyph sits on: `text-field.md` describes the leading slot as a *"contextual glyph (search)"* and the
|
|
51
|
-
trailing slot as *"clear / password-reveal"*, and neither names a calendar — so the position follows the
|
|
52
|
-
design. `field-readonly.md:69` is the single place the glyph is mentioned at all, and it agrees with
|
|
53
|
-
this model: the icon is *"a quiet affordance, **not an active control**"* and it is *"**the trigger**"*
|
|
54
|
-
— i.e. the field — that opens the calendar. Hence `role="combobox"` on the input (the APG *Date Picker
|
|
55
|
-
Combobox* pattern) rather than `aria-haspopup` on a button, because there is no button.
|
|
56
|
-
|
|
57
|
-
> Superseded: an earlier build put the calendar in the trailing slot as an interactive icon button and
|
|
58
|
-
> justified it from the *"busy slot"* wording of the grill documents. That wording is about Select
|
|
59
|
-
> carets and password-reveals, not about a date field, and the grill documents are working notes rather
|
|
60
|
-
> than canonical spec.
|
|
61
|
-
|
|
62
|
-
## Anatomy
|
|
63
|
-
|
|
64
|
-
- **Shell** — the Text Field shell: border, fill, `--radius-400`, height tier. Owns the floating-label
|
|
65
|
-
notch and the focus border swap.
|
|
66
|
-
- **Value input** — a native, editable `<input type="text">` showing either the value formatted with
|
|
67
|
-
`dateFormat`, or the placeholder pattern.
|
|
68
|
-
- **Leading calendar glyph** — the `calendar-dots` icon, **decorative** (`aria-hidden`): it marks what the
|
|
69
|
-
field holds and is not focusable. In read-only it steps down from `--text-secondary` to `--icon-muted`
|
|
70
|
-
(`field-readonly.md`).
|
|
71
|
-
- **The input carries the ARIA** — `role="combobox"`, `aria-haspopup="dialog"`, `aria-expanded` and
|
|
72
|
-
`aria-controls`.
|
|
73
|
-
- **The wrapper carries the click** — "the whole field is the trigger" is literal: the open handler
|
|
74
|
-
sits on the wrapper, not on the `<input>`, because the glyph and the shell padding are the input's
|
|
75
|
-
*siblings* and would otherwise be dead area. A press that did not land in the input is handled on
|
|
76
|
-
mouse-down so focus never leaves the input — a half-typed draft survives and the label does not
|
|
77
|
-
flicker — and the field stays typeable. It opens but does **not** toggle, so clicking into the text to
|
|
78
|
-
place the caret while the calendar is up keeps it up. `ArrowDown` opens it too — and, when it is
|
|
79
|
-
already open, moves focus into the day grid.
|
|
80
|
-
- **Panel** — the [`DatePicker`](?path=/docs/design-system-molecules-datepicker--docs) rendered in a
|
|
81
|
-
portal, anchored via `useAnchoredPanel` (`role: 'dialog'`, `focusModel: 'roving'`,
|
|
82
|
-
`navigation: 'none'` — the day grid owns the arrow keys, `widthPolicy: 'content'` — the calendar hugs
|
|
83
|
-
its own grid instead of the trigger width). Since date-picker 1.0.0 the calendar paints no surface,
|
|
84
|
-
so the panel wraps it in the Popover surface recipe (`popoverSurfaceVariants`, padless — the month
|
|
85
|
-
columns pad themselves): same `--bg-primary` fill, 1px `--outline-default` border, `--radius-500`
|
|
86
|
-
corners and `--shadow-overlay` as before, now owned by the host.
|
|
87
|
-
- **Label / helper / error line** — live in [`Field`](?path=/docs/design-system-atoms-field--docs), not
|
|
88
|
-
here. DateField is the shell + value only.
|
|
89
|
-
|
|
90
|
-
<Canvas of={DateFieldStories.WithField} />
|
|
91
|
-
|
|
92
|
-
## Variants
|
|
93
|
-
|
|
94
|
-
**No variant axis.** DateField is one field with one job — pick or type a single date. Everything that
|
|
95
|
-
would otherwise be a variant is either a **size** (height tier) or a **state**. The display pattern is
|
|
96
|
-
data (`dateFormat`), not a variant. There is therefore no `Variants` story.
|
|
97
|
-
|
|
98
|
-
## Matrix
|
|
99
|
-
|
|
100
|
-
<Canvas of={DateFieldStories.Matrix} />
|
|
101
|
-
|
|
102
|
-
The full state × size grid, mirroring the Figma labelled grid — rows are states, columns are sizes.
|
|
103
|
-
|
|
104
|
-
## Sizes
|
|
105
|
-
|
|
106
|
-
<Canvas of={DateFieldStories.Sizes} />
|
|
107
|
-
|
|
108
|
-
<table>
|
|
109
|
-
<thead>
|
|
110
|
-
<tr>
|
|
111
|
-
<th>Size</th>
|
|
112
|
-
<th>Height</th>
|
|
113
|
-
<th>Icon</th>
|
|
114
|
-
<th>When</th>
|
|
115
|
-
</tr>
|
|
116
|
-
</thead>
|
|
117
|
-
<tbody>
|
|
118
|
-
<tr>
|
|
119
|
-
<td><code>md</code> (default)</td>
|
|
120
|
-
<td>48 px (<code>h-1100</code>)</td>
|
|
121
|
-
<td>24 px</td>
|
|
122
|
-
<td>Standalone field in a form</td>
|
|
123
|
-
</tr>
|
|
124
|
-
<tr>
|
|
125
|
-
<td><code>sm</code></td>
|
|
126
|
-
<td>40 px (<code>h-1000</code>)</td>
|
|
127
|
-
<td>20 px</td>
|
|
128
|
-
<td>Dense rows (invoice item rows, list filters)</td>
|
|
129
|
-
</tr>
|
|
130
|
-
</tbody>
|
|
131
|
-
</table>
|
|
132
|
-
|
|
133
|
-
Padding and font are the Text Field tiers: `px-500` / `gap-400`, value always Body/M/Regular.
|
|
134
|
-
|
|
135
|
-
## States
|
|
136
|
-
|
|
137
|
-
<Canvas of={DateFieldStories.States} />
|
|
138
|
-
|
|
139
|
-
<table>
|
|
140
|
-
<thead>
|
|
141
|
-
<tr>
|
|
142
|
-
<th>State</th>
|
|
143
|
-
<th>Shell</th>
|
|
144
|
-
<th>Value / icon</th>
|
|
145
|
-
<th>Behaviour</th>
|
|
146
|
-
</tr>
|
|
147
|
-
</thead>
|
|
148
|
-
<tbody>
|
|
149
|
-
<tr>
|
|
150
|
-
<td><code>default</code></td>
|
|
151
|
-
<td>border <code>--outline-default</code>, on focus-within <code>--outline-focus</code></td>
|
|
152
|
-
<td>value <code>--text-primary</code>, placeholder <code>--text-placeholder</code>, icon <code>--text-secondary</code></td>
|
|
153
|
-
<td>Typing allowed; a click <em>anywhere in the field</em> (glyph and padding included) or <code>ArrowDown</code> opens the panel</td>
|
|
154
|
-
</tr>
|
|
155
|
-
<tr>
|
|
156
|
-
<td><code>success</code></td>
|
|
157
|
-
<td>border <code>--status-success-solid</code></td>
|
|
158
|
-
<td>calendar glyph <strong>stays</strong> leading; the <code>check</code> status icon takes the trailing slot</td>
|
|
159
|
-
<td>Unchanged; injected by <code>Field</code> when it is given a <code>success</code> message</td>
|
|
160
|
-
</tr>
|
|
161
|
-
<tr>
|
|
162
|
-
<td><code>error</code></td>
|
|
163
|
-
<td>border <code>--status-danger</code></td>
|
|
164
|
-
<td>calendar glyph <strong>stays</strong> in the leading slot; the intrinsic status icon takes the <em>trailing</em> slot, so the two never collide</td>
|
|
165
|
-
<td>Unchanged; sets <code>aria-invalid</code></td>
|
|
166
|
-
</tr>
|
|
167
|
-
<tr>
|
|
168
|
-
<td><code>disabled</code></td>
|
|
169
|
-
<td><code>--outline-default</code> border @ <code>--border-width-100</code>, <code>--disabled-background</code> fill</td>
|
|
170
|
-
<td>ink <code>--disabled-foreground</code></td>
|
|
171
|
-
<td>Input disabled and out of tab order; the panel cannot open</td>
|
|
172
|
-
</tr>
|
|
173
|
-
<tr>
|
|
174
|
-
<td><code>readonly</code></td>
|
|
175
|
-
<td><code>--outline-default</code> border @ <code>--border-width-100</code>, <code>--bg-readonly</code> fill</td>
|
|
176
|
-
<td>value <code>--text-primary</code>, icon <code>--icon-muted</code></td>
|
|
177
|
-
<td>Shows the value, is copyable and submits with the form, but the trigger <strong>does not open the calendar</strong> (<code>field-readonly.md:69</code>); carries <code>aria-readonly</code></td>
|
|
178
|
-
</tr>
|
|
179
|
-
</tbody>
|
|
180
|
-
</table>
|
|
181
|
-
|
|
182
|
-
Interactive states are CSS, not props: focus is a border-colour swap on the shell. The field has a
|
|
183
|
-
single focusable element — the input — so there is no second focus ring to reason about.
|
|
184
|
-
|
|
185
|
-
## Mobile
|
|
186
|
-
|
|
187
|
-
A **single** date field needs nothing special on a phone. The two things that do move belong to the
|
|
188
|
-
panel it opens, and are worth knowing here because this is where the decision gets made
|
|
189
|
-
(manifest `date-picker` 1.2.1 § `chrome.mobile` — see [DatePicker → Mobile](?path=/docs/design-system-molecules-datepicker--docs#mobile)):
|
|
190
|
-
|
|
191
|
-
- The single-month picker steps its **side padding** down below `md` (768px), `--space-600` → `--space-400`, so its 364px minimum clears a 390px viewport.
|
|
192
|
-
- The popover may **flip/shift past the page's own 16px gutter** toward the viewport edge; it is not confined to the padded content column.
|
|
193
|
-
|
|
194
|
-
**A date range is the case that does not scale down.** Two DateFields side by side do not fit a
|
|
195
|
-
phone column, and the dual-month DatePicker — the desktop answer — fits no phone viewport at all
|
|
196
|
-
(~760px, and the 48×36 Day Cell is a touch target that must not shrink — its `<button>` fills the
|
|
197
|
-
whole cell, so 48×36 is the real hit area and not just the tile). On mobile a range is
|
|
198
|
-
therefore a [`FieldPair`](?path=/docs/design-system-molecules-fieldpair--docs) in `format="date"`:
|
|
199
|
-
two fused cells, each opening its **own** single-month panel, no shared calendar and no cross-field
|
|
200
|
-
`minDate`/`maxDate`.
|
|
201
|
-
|
|
202
|
-
## API
|
|
203
|
-
|
|
204
|
-
<Controls of={DateFieldStories.Playground} />
|
|
205
|
-
|
|
206
|
-
<table>
|
|
207
|
-
<thead>
|
|
208
|
-
<tr>
|
|
209
|
-
<th>Prop</th>
|
|
210
|
-
<th>Type</th>
|
|
211
|
-
<th>Default</th>
|
|
212
|
-
<th>Notes</th>
|
|
213
|
-
</tr>
|
|
214
|
-
</thead>
|
|
215
|
-
<tbody>
|
|
216
|
-
<tr><td><code>value</code></td><td><code>Date</code></td><td>—</td><td>Controlled. The chosen date.</td></tr>
|
|
217
|
-
<tr><td><code>onValueChange</code></td><td><code>(value: Date | undefined) => void</code></td><td>—</td><td>Fires on day pick and on a committed draft; <code>undefined</code> means "unset".</td></tr>
|
|
218
|
-
<tr><td><code>size</code></td><td><code>'md' | 'sm'</code></td><td><code>'md'</code></td><td>Text Field height tier.</td></tr>
|
|
219
|
-
<tr><td><code>state</code></td><td><code>'default' | 'focused' | 'error' | 'success' | 'disabled' | 'readonly'</code></td><td><code>'default'</code></td><td>Visual state; usually driven by <code>Field</code>.</td></tr>
|
|
220
|
-
<tr><td><code>dateFormat</code></td><td><code>string</code></td><td><code>dd. MM. yyyy</code></td><td>Display <em>and</em> parse pattern, date-fns syntax.</td></tr>
|
|
221
|
-
<tr><td><code>locale</code></td><td><code>Locale</code> (date-fns)</td><td><code>cs</code></td><td>Drives week start, weekday names, month caption.</td></tr>
|
|
222
|
-
<tr><td><code>minDate</code> / <code>maxDate</code></td><td><code>Date</code></td><td>—</td><td>Bounds the window the panel offers (out-of-range days render disabled) <em>and</em> the typed draft — an out-of-range date is discarded on commit, day-granular.</td></tr>
|
|
223
|
-
<tr><td><code>placeholder</code></td><td><code>string</code></td><td>—</td><td>Show the expected pattern here, never the label.</td></tr>
|
|
224
|
-
<tr><td><code>id</code> / <code>name</code></td><td><code>string</code></td><td>—</td><td><code>id</code> is required for <code>Field</code> to wire label + helper text.</td></tr>
|
|
225
|
-
<tr><td><code>disabled</code> / <code>readOnly</code></td><td><code>boolean</code></td><td>—</td><td>Native attributes; win over <code>state</code> when set explicitly.</td></tr>
|
|
226
|
-
<tr><td><code>panelLabel</code> <strong>(required)</strong></td><td><code>string</code></td><td>—</td><td><code>aria-label</code> of the panel dialog. No default: the design system is locale-agnostic, and a name invisible to sighted review is exactly the kind that ships untranslated.</td></tr>
|
|
227
|
-
<tr><td><code>navLabels</code> <strong>(required)</strong></td><td><code>{ previousMonth, nextMonth, previousYear, nextYear }</code></td><td>—</td><td>Accessible names for the panel's four chevrons, passed straight through to <code>DatePicker</code>.</td></tr>
|
|
228
|
-
<tr><td><code>onFocus</code> / <code>onBlur</code></td><td><code>FocusEventHandler<HTMLInputElement></code></td><td>—</td><td>Forwarded to the input; the draft commit runs before <code>onBlur</code> — except when focus moves into the panel, where the day click is the commit instead.</td></tr>
|
|
229
|
-
<tr><td><code>aria-invalid</code> / <code>aria-describedby</code></td><td><code>boolean</code> / <code>string</code></td><td>—</td><td>Injected by <code>Field</code>; declared explicitly so the clone cannot drop them.</td></tr>
|
|
230
|
-
</tbody>
|
|
231
|
-
</table>
|
|
232
|
-
|
|
233
|
-
## Do / Don't
|
|
234
|
-
|
|
235
|
-
- ✅ Wrap in `Field` for the floating label — the `<label>` is the accessible name.
|
|
236
|
-
- ✅ Use the placeholder to show the expected pattern (`dd. mm. rrrr`). DateField follows the Text
|
|
237
|
-
Field floating-label rule, so an empty, unfocused field with **no** placeholder rests its label
|
|
238
|
-
inside the shell; a placeholder both teaches the format and floats the label out of its way.
|
|
239
|
-
- ✅ Take `dateFormat` from the consumer's locale config, so a market change does not need a code change.
|
|
240
|
-
- ✅ Keep the field typeable — do not layer a read-only overlay over the input to "force" the picker.
|
|
241
|
-
- ❌ Never use the placeholder as the label.
|
|
242
|
-
- ❌ Don't hardcode `dateFormat` per call site.
|
|
243
|
-
- ❌ Don't use two DateFields glued together as a range picker — on desktop use the dual-month `DatePicker`, on mobile a `FieldPair` in `format="date"` (see [Mobile](#mobile)).
|
|
244
|
-
- ❌ Don't rely on the field to validate: an unparseable draft is discarded, no error state is raised.
|
|
245
|
-
|
|
246
|
-
## Accessibility
|
|
247
|
-
|
|
248
|
-
- **Keyboard** — Tab reaches **one** element, the input; the calendar glyph is decoration and never
|
|
249
|
-
takes focus. `ArrowDown` opens the panel and moves focus onto a day — and when the panel is already
|
|
250
|
-
up (a click-open leaves focus in the input on purpose) it is the route *into* the grid, so a keyboard
|
|
251
|
-
user is never stuck having to Tab there. `Esc` closes it. Inside the panel
|
|
252
|
-
the day grid owns arrows / `PageUp` / `PageDown` / `Home` / `End` (`navigation: 'none'` on the
|
|
253
|
-
substrate) and is itself **one tab stop**: a single day carries `tabindex="0"` (the selected date,
|
|
254
|
-
else today, else the first day) and the rest are reached only by the arrow keys, so Tab never walks
|
|
255
|
-
35 days. Picking a day closes the panel and returns focus to the input. The shell shows focus as an
|
|
256
|
-
`--outline-focus` border swap.
|
|
257
|
-
- **Focus follows how the panel was opened.** Opening by **click** leaves focus in the input, because
|
|
258
|
-
the field is typeable and pulling focus into the grid would cut a typist off mid-date. Opening by
|
|
259
|
-
**ArrowDown** is explicit intent to browse, so there focus lands on the selected day (or today).
|
|
260
|
-
- **ARIA** — the input is the trigger: `role="combobox"` + `aria-haspopup="dialog"` + `aria-expanded` +
|
|
261
|
-
`aria-controls` pointing at the panel while it is open (APG *Date Picker Combobox*). The panel is
|
|
262
|
-
`role="dialog"` with `aria-label={panelLabel}`. Read-only carries `aria-readonly`, error carries
|
|
263
|
-
`aria-invalid`. Helper text is associated via `aria-describedby`, injected by `Field`.
|
|
264
|
-
- **Screen reader** — the input announces as a combobox with the `<label>` text, the formatted value and
|
|
265
|
-
its expanded state. Opening the panel announces the dialog by its `panelLabel`, then the grid by its
|
|
266
|
-
month caption. (Wording derived from the ARIA wiring — not yet verified against a real screen reader.)
|
|
267
|
-
- **Colour is never the only cue** — `Field` renders the error *text* alongside the `--status-danger`
|
|
268
|
-
border, so the error state does not rely on colour alone (WCAG 1.4.1).
|
|
269
|
-
- **Motion** — the panel's enter/exit is a 150 ms opacity + translate transition from
|
|
270
|
-
`useAnchoredPanel`, which reads `prefers-reduced-motion` at runtime and drops both the slide and the
|
|
271
|
-
duration when it is set.
|
|
272
|
-
|
|
273
|
-
> **Not yet measured:** the ink/background contrast ratios come from the FODS semantic tokens and have
|
|
274
|
-
> not been verified for this component. Run the `storybook-a11y-auditor` (or an axe pass over the
|
|
275
|
-
> stories) before treating AA conformance as confirmed.
|
|
276
|
-
|
|
277
|
-
Accessibility floor for every FODS component: `spec/01-foundations/accessibility.md`.
|
|
278
|
-
|
|
279
|
-
## Usage
|
|
280
|
-
|
|
281
|
-
```tsx
|
|
282
|
-
// Good — Field owns the label / helper / error, DateField owns the value
|
|
283
|
-
const [issuedOn, setIssuedOn] = React.useState<Date | undefined>();
|
|
284
|
-
|
|
285
|
-
<Field label="Datum vystavení" helperText="Datum, kdy byla faktura vystavena">
|
|
286
|
-
<DateField
|
|
287
|
-
id="issued-on"
|
|
288
|
-
name="issued_on"
|
|
289
|
-
value={issuedOn}
|
|
290
|
-
onValueChange={setIssuedOn}
|
|
291
|
-
placeholder="dd. mm. rrrr"
|
|
292
|
-
dateFormat={locale.dateFormat} // 'dd. MM. yyyy' CZ, 'MM/dd/yyyy' US, 'dd/MM/yyyy' GB
|
|
293
|
-
minDate={new Date(2020, 0, 1)}
|
|
294
|
-
/>
|
|
295
|
-
</Field>
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
Typing behaviour worth knowing:
|
|
299
|
-
|
|
300
|
-
- The typed draft is parsed **on blur** against `dateFormat`. A draft that does not parse is
|
|
301
|
-
**discarded, not coerced** — the field falls back to the committed value and raises **no** error state
|
|
302
|
-
of its own. Known limitation: validation is the form's job.
|
|
303
|
-
- An emptied field is a legitimate "unset the date" and reports `undefined`.
|
|
304
|
-
- DateField is deliberately **not** marked `autoFloating` in `Field.tsx` → `FIELD_CHILD_TRAITS`: it is a Text Field
|
|
305
|
-
sibling and follows the one floating-label rule (`text-field.md` § States), so an empty, unfocused,
|
|
306
|
-
valid date field rests its label inside. In practice the label floats anyway on the recommended
|
|
307
|
-
usage, because the format hint is passed as a `placeholder` and a placeholder floats it. Forcing the
|
|
308
|
-
float would strand the label over an empty shell whenever no placeholder was given.
|
|
309
|
-
|
|
310
|
-
```tsx
|
|
311
|
-
// Don't — the placeholder is not an accessible name
|
|
312
|
-
<DateField placeholder="Datum vystavení" value={issuedOn} onValueChange={setIssuedOn} />
|
|
313
|
-
|
|
314
|
-
// Don't — hardcoded per-market pattern in the call site
|
|
315
|
-
<DateField dateFormat="MM/dd/yyyy" value={issuedOn} onValueChange={setIssuedOn} />
|
|
316
|
-
|
|
317
|
-
// Don't — a range is not two DateFields; use the dual-month DatePicker
|
|
318
|
-
<DateField value={from} onValueChange={setFrom} />
|
|
319
|
-
<DateField value={to} onValueChange={setTo} />
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
## Related
|
|
323
|
-
|
|
324
|
-
- [`DatePicker`](?path=/docs/design-system-molecules-datepicker--docs) — the panel this field opens; use
|
|
325
|
-
it directly for a dual-month range (desktop only — it has no mobile treatment).
|
|
326
|
-
- [`FieldPair`](?path=/docs/design-system-molecules-fieldpair--docs) — `format="date"`: the range form
|
|
327
|
-
that works on a phone, two cells each opening their own single-month panel.
|
|
328
|
-
- [`TextField`](?path=/docs/design-system-atoms-textfield--docs) — the shell DateField reuses (border,
|
|
329
|
-
fill, height tiers, leading / trailing slot contract).
|
|
330
|
-
- [`Field`](?path=/docs/design-system-atoms-field--docs) — floating label, helper text, error line;
|
|
331
|
-
injects `aria-invalid` / `aria-describedby`.
|
|
332
|
-
- [`SelectField`](?path=/docs/design-system-molecules-selectfield--docs) — the sibling trigger that
|
|
333
|
-
**does not** allow typing: a read-only `<button role="combobox">`, because a Select's value must be one
|
|
334
|
-
of a closed list. A date is an open, keyable value, so DateField stays an `<input>`.
|
|
335
|
-
- Spec: `spec/03-atoms/text-field.md` ·
|
|
336
|
-
`spec/04-molecules/date-picker.md` · `spec/06-patterns/field-readonly.md`
|
|
337
|
-
|
|
338
|
-
## Migration notes
|
|
339
|
-
|
|
340
|
-
Not applicable.
|
|
@@ -1,221 +0,0 @@
|
|
|
1
|
-
import * as React from 'react';
|
|
2
|
-
import type { Meta, StoryObj } from '@storybook/react-vite';
|
|
3
|
-
import { DateField } from './DateField';
|
|
4
|
-
import { Field } from '../field/Field';
|
|
5
|
-
import { Section, Showcase } from '../../storybook/Section';
|
|
6
|
-
import { componentDoc } from '../../storybook/componentDoc';
|
|
7
|
-
|
|
8
|
-
// Derived from the clock, not pinned: a designer opening Storybook should see
|
|
9
|
-
// today's date and today's calendar (the unit tests pin dates instead).
|
|
10
|
-
const today = new Date();
|
|
11
|
-
|
|
12
|
-
const SIZES = ['md', 'sm'] as const;
|
|
13
|
-
const STATES = ['default', 'focused', 'error', 'success', 'disabled', 'readonly'] as const;
|
|
14
|
-
|
|
15
|
-
// The panel name and the four chevron names are required props — the design
|
|
16
|
-
// system is locale-agnostic and the consumer owns the wording. Storybook is the
|
|
17
|
-
// consumer here.
|
|
18
|
-
const PANEL_LABEL = 'Kalendář';
|
|
19
|
-
const NAV_LABELS = {
|
|
20
|
-
previousMonth: 'Předchozí měsíc',
|
|
21
|
-
nextMonth: 'Další měsíc',
|
|
22
|
-
previousYear: 'Předchozí rok',
|
|
23
|
-
nextYear: 'Další rok',
|
|
24
|
-
} as const;
|
|
25
|
-
const PANEL = { panelLabel: PANEL_LABEL, navLabels: NAV_LABELS } as const;
|
|
26
|
-
|
|
27
|
-
// The bare fields in Sizes, Matrix and States stand outside a `Field`, so nothing labels
|
|
28
|
-
// them (a label is always present — text-field.md § Copy). DateField takes no `aria-label`,
|
|
29
|
-
// so each gets a visually hidden <label> wired to its `id` instead.
|
|
30
|
-
const LABEL = 'Datum vystavení';
|
|
31
|
-
const HiddenLabel = ({ htmlFor }: { htmlFor: string }) => (
|
|
32
|
-
<label htmlFor={htmlFor} className="sr-only">
|
|
33
|
-
{LABEL}
|
|
34
|
-
</label>
|
|
35
|
-
);
|
|
36
|
-
|
|
37
|
-
// Stateful demos live in named components: a hook called straight inside a
|
|
38
|
-
// story's `render` breaks rules-of-hooks (repo convention — see ActionRow).
|
|
39
|
-
function DateFieldDemo(args: React.ComponentProps<typeof DateField>) {
|
|
40
|
-
const [value, setValue] = React.useState<Date | undefined>(today);
|
|
41
|
-
return (
|
|
42
|
-
<Field label="Datum vystavení" helperText="Bez vyplnění se doplní podle splatnosti">
|
|
43
|
-
<DateField
|
|
44
|
-
id="playground-date-field"
|
|
45
|
-
{...PANEL}
|
|
46
|
-
{...args}
|
|
47
|
-
value={value}
|
|
48
|
-
onValueChange={setValue}
|
|
49
|
-
/>
|
|
50
|
-
</Field>
|
|
51
|
-
);
|
|
52
|
-
}
|
|
53
|
-
|
|
54
|
-
function WithFieldDemo() {
|
|
55
|
-
const [value, setValue] = React.useState<Date | undefined>(today);
|
|
56
|
-
return (
|
|
57
|
-
<Field label="Datum vystavení">
|
|
58
|
-
<DateField
|
|
59
|
-
{...PANEL}
|
|
60
|
-
id="issued-on"
|
|
61
|
-
value={value}
|
|
62
|
-
onValueChange={setValue}
|
|
63
|
-
placeholder="dd. mm. rrrr"
|
|
64
|
-
/>
|
|
65
|
-
</Field>
|
|
66
|
-
);
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
function SizesDemo() {
|
|
70
|
-
const [value, setValue] = React.useState<Date | undefined>(today);
|
|
71
|
-
return (
|
|
72
|
-
<Showcase>
|
|
73
|
-
{SIZES.map(size => (
|
|
74
|
-
<Section key={size} title={size}>
|
|
75
|
-
<div className="w-[calc(var(--space-1200)*5)]">
|
|
76
|
-
<HiddenLabel htmlFor={`date-field-size-${size}`} />
|
|
77
|
-
<DateField {...PANEL} id={`date-field-size-${size}`} size={size} value={value} onValueChange={setValue} />
|
|
78
|
-
</div>
|
|
79
|
-
</Section>
|
|
80
|
-
))}
|
|
81
|
-
</Showcase>
|
|
82
|
-
);
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
const meta = {
|
|
86
|
-
title: 'Design System/Molecules/DateField',
|
|
87
|
-
component: DateField,
|
|
88
|
-
parameters: {
|
|
89
|
-
layout: 'centered',
|
|
90
|
-
containerWidth: 320,
|
|
91
|
-
docs: {
|
|
92
|
-
description: {
|
|
93
|
-
component: componentDoc({
|
|
94
|
-
summary:
|
|
95
|
-
'The trigger a Date Picker opens from — a Text Field shell with a calendar affordance in the leading slot. It is an editable `<input>`, so a date can be typed as well as picked; the typed draft is parsed against `dateFormat` on blur and discarded if it does not parse.',
|
|
96
|
-
useCases: [
|
|
97
|
-
'Any single date in a form — expense date, invoice issue / taxable / due date',
|
|
98
|
-
'`dateFormat` — display + parse pattern in date-fns syntax; per-market values (`dd. MM. yyyy` CZ, `MM/dd/yyyy` US) come from the consumer\'s locale config',
|
|
99
|
-
'`minDate` / `maxDate` — bound the window the panel offers',
|
|
100
|
-
'`state="readonly"` — shows the value, steps the calendar icon down to `--icon-muted` and never opens the panel',
|
|
101
|
-
'Mobile — a single date needs nothing special; the panel steps its side padding down and may sit past the page gutter. A date RANGE is the case that does not scale down',
|
|
102
|
-
],
|
|
103
|
-
bestPractices: [
|
|
104
|
-
'Wrap in `Field` for the floating label — the `<label>` is the accessible name, never the placeholder',
|
|
105
|
-
'Keep the field typeable: a keyboard user filling a long form is faster typing a date than paging a calendar',
|
|
106
|
-
'Use the placeholder to show the expected pattern, not as a label',
|
|
107
|
-
'For a date RANGE this field is never the answer — on desktop reach for the dual-month `DatePicker`, on mobile for a `FieldPair` in `format="date"` (the dual panel fits no phone viewport)',
|
|
108
|
-
],
|
|
109
|
-
knownIssues: [
|
|
110
|
-
'A draft that does not parse is silently discarded on blur and the field falls back to the committed value — it does not raise an error state of its own',
|
|
111
|
-
],
|
|
112
|
-
docsLink: {
|
|
113
|
-
label: 'spec/04-molecules/date-picker.md',
|
|
114
|
-
},
|
|
115
|
-
}),
|
|
116
|
-
},
|
|
117
|
-
},
|
|
118
|
-
},
|
|
119
|
-
argTypes: {
|
|
120
|
-
locale: { control: false },
|
|
121
|
-
value: { control: false },
|
|
122
|
-
onValueChange: { control: false },
|
|
123
|
-
navLabels: { control: false },
|
|
124
|
-
},
|
|
125
|
-
// `panelLabel` / `navLabels` are required, so the showcase stories — which
|
|
126
|
-
// render their own demos and pass no args — inherit them here.
|
|
127
|
-
args: PANEL,
|
|
128
|
-
} satisfies Meta<typeof DateField>;
|
|
129
|
-
|
|
130
|
-
export default meta;
|
|
131
|
-
type Story = StoryObj<typeof meta>;
|
|
132
|
-
|
|
133
|
-
export const Playground: Story = {
|
|
134
|
-
args: {
|
|
135
|
-
size: 'md',
|
|
136
|
-
placeholder: 'dd. mm. rrrr',
|
|
137
|
-
},
|
|
138
|
-
/*
|
|
139
|
-
* Wrapped in `Field`, which is how the component actually ships: the floating
|
|
140
|
-
* label is the real <label> and is what gives the control its accessible name
|
|
141
|
-
* (WCAG 4.1.2), and the helper line is what `aria-describedby` resolves to, so
|
|
142
|
-
* the Error state announces its message (WCAG 3.3.1). `Field` derives both from
|
|
143
|
-
* the child's `id`, so the Playground supplies one.
|
|
144
|
-
*/
|
|
145
|
-
render: args => <DateFieldDemo {...args} />,
|
|
146
|
-
};
|
|
147
|
-
|
|
148
|
-
export const Matrix: Story = {
|
|
149
|
-
parameters: {
|
|
150
|
-
layout: 'padded',
|
|
151
|
-
docs: {
|
|
152
|
-
description: {
|
|
153
|
-
story:
|
|
154
|
-
'Full state × size matrix — mirrors the Figma labelled grid. Rows = states, columns = sizes. Read-only keeps the calendar icon as a quiet marker but never opens the panel; disabled keeps the `--outline-default` border on the `--disabled-background` fill and dims all ink.',
|
|
155
|
-
},
|
|
156
|
-
},
|
|
157
|
-
},
|
|
158
|
-
render: () => (
|
|
159
|
-
<Showcase>
|
|
160
|
-
{STATES.map(state => (
|
|
161
|
-
<Section key={state} title={state} layout="row">
|
|
162
|
-
{SIZES.map(size => (
|
|
163
|
-
<div key={size} className="w-[calc(var(--space-1200)*5)]">
|
|
164
|
-
<HiddenLabel htmlFor={`date-field-${state}-${size}`} />
|
|
165
|
-
<DateField {...PANEL} id={`date-field-${state}-${size}`} state={state} size={size} value={today} />
|
|
166
|
-
</div>
|
|
167
|
-
))}
|
|
168
|
-
</Section>
|
|
169
|
-
))}
|
|
170
|
-
</Showcase>
|
|
171
|
-
),
|
|
172
|
-
};
|
|
173
|
-
|
|
174
|
-
/** Wrapped in `Field` — the label follows the one floating-label rule; the placeholder floats it. */
|
|
175
|
-
export const WithField: Story = {
|
|
176
|
-
parameters: {
|
|
177
|
-
docs: {
|
|
178
|
-
description: {
|
|
179
|
-
story:
|
|
180
|
-
'The field follows the Text Field floating-label rule: an empty, unfocused field with no placeholder rests its label inside the shell. Here the pattern placeholder teaches the format and floats the label out of its way.',
|
|
181
|
-
},
|
|
182
|
-
},
|
|
183
|
-
},
|
|
184
|
-
render: () => <WithFieldDemo />,
|
|
185
|
-
};
|
|
186
|
-
|
|
187
|
-
export const Sizes: Story = {
|
|
188
|
-
parameters: {
|
|
189
|
-
layout: 'padded',
|
|
190
|
-
docs: {
|
|
191
|
-
description: {
|
|
192
|
-
story: 'Medium (48) standalone, Small (40) in dense rows — the Text Field height tiers.',
|
|
193
|
-
},
|
|
194
|
-
},
|
|
195
|
-
},
|
|
196
|
-
render: () => <SizesDemo />,
|
|
197
|
-
};
|
|
198
|
-
|
|
199
|
-
export const States: Story = {
|
|
200
|
-
parameters: {
|
|
201
|
-
layout: 'padded',
|
|
202
|
-
docs: {
|
|
203
|
-
description: {
|
|
204
|
-
story:
|
|
205
|
-
'Read-only keeps the calendar icon as a quiet marker (`--icon-muted`) but does not open the panel; disabled keeps the `--outline-default` border on the `--disabled-background` fill and dims all ink.',
|
|
206
|
-
},
|
|
207
|
-
},
|
|
208
|
-
},
|
|
209
|
-
render: () => (
|
|
210
|
-
<Showcase>
|
|
211
|
-
{STATES.map(state => (
|
|
212
|
-
<Section key={state} title={state}>
|
|
213
|
-
<div className="w-[calc(var(--space-1200)*5)]">
|
|
214
|
-
<HiddenLabel htmlFor={`date-field-${state}`} />
|
|
215
|
-
<DateField {...PANEL} id={`date-field-${state}`} state={state} value={today} />
|
|
216
|
-
</div>
|
|
217
|
-
</Section>
|
|
218
|
-
))}
|
|
219
|
-
</Showcase>
|
|
220
|
-
),
|
|
221
|
-
};
|