@vokality/design-system 1.3.0 → 3.0.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.
Files changed (175) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +51 -5
  3. package/dist/browser.d.ts +13 -0
  4. package/dist/browser.js +7 -0
  5. package/dist/charts/chart.d.ts +6 -5
  6. package/dist/charts/chart.js +44 -25
  7. package/dist/chat.d.ts +54 -0
  8. package/dist/chat.js +1 -0
  9. package/dist/components/Accordion/Accordion.js +1 -1
  10. package/dist/components/Alert/Alert.js +5 -2
  11. package/dist/components/AppShell/AppShell.js +10 -14
  12. package/dist/components/Avatar/Avatar.js +2 -2
  13. package/dist/components/AvatarGroup/AvatarGroup.js +2 -2
  14. package/dist/components/BarChart/BarChart.js +17 -15
  15. package/dist/components/Breadcrumbs/Breadcrumbs.js +6 -3
  16. package/dist/components/Calendar/Calendar.js +6 -5
  17. package/dist/components/Card/Card.js +2 -3
  18. package/dist/components/ChatInbox/ChatInbox.d.ts +11 -0
  19. package/dist/components/ChatInbox/ChatInbox.js +49 -0
  20. package/dist/components/ChatPanel/ChatPanel.d.ts +3 -0
  21. package/dist/components/ChatPanel/ChatPanel.js +13 -0
  22. package/dist/components/ChatPanel/composer.d.ts +5 -0
  23. package/dist/components/ChatPanel/composer.js +32 -0
  24. package/dist/components/ChatPanel/transcript.d.ts +13 -0
  25. package/dist/components/ChatPanel/transcript.js +39 -0
  26. package/dist/components/ChatWidget/ChatWidget.d.ts +12 -0
  27. package/dist/components/ChatWidget/ChatWidget.js +42 -0
  28. package/dist/components/Checkbox/Checkbox.d.ts +5 -10
  29. package/dist/components/Checkbox/Checkbox.js +5 -19
  30. package/dist/components/CodeBlock/CodeBlock.js +19 -5
  31. package/dist/components/Combobox/Combobox.js +22 -15
  32. package/dist/components/Combobox/ListPanel.js +20 -9
  33. package/dist/components/CommandPalette/CommandPalette.js +33 -14
  34. package/dist/components/ContextMenu/ContextMenu.d.ts +2 -2
  35. package/dist/components/ContextMenu/ContextMenu.js +5 -50
  36. package/dist/components/DatePicker/DatePicker.js +35 -29
  37. package/dist/components/DescriptionList/DescriptionList.js +1 -1
  38. package/dist/components/Dialog/Dialog.d.ts +24 -7
  39. package/dist/components/Dialog/Dialog.js +30 -41
  40. package/dist/components/Drawer/Drawer.d.ts +4 -2
  41. package/dist/components/EmptyState/EmptyState.js +2 -2
  42. package/dist/components/ErrorSummary/ErrorSummary.js +5 -3
  43. package/dist/components/FaqList/FaqList.js +1 -1
  44. package/dist/components/Field/Field.js +4 -4
  45. package/dist/components/Fieldset/Fieldset.js +3 -3
  46. package/dist/components/FileUpload/FileUpload.js +17 -9
  47. package/dist/components/Grid/Grid.d.ts +867 -5
  48. package/dist/components/Grid/Grid.js +3 -4
  49. package/dist/components/Heading/Heading.js +2 -1
  50. package/dist/components/Icon/Icon.js +4 -2
  51. package/dist/components/Inline/Inline.d.ts +867 -5
  52. package/dist/components/Inline/Inline.js +2 -3
  53. package/dist/components/LineChart/LineChart.js +17 -15
  54. package/dist/components/LinkProvider/LinkProvider.d.ts +1 -1
  55. package/dist/components/LinkProvider/LinkProvider.js +6 -2
  56. package/dist/components/List/List.js +1 -1
  57. package/dist/components/MediaCard/MediaCard.js +2 -2
  58. package/dist/components/Menu/Menu.js +6 -43
  59. package/dist/components/Menu/entries.d.ts +1 -30
  60. package/dist/components/Menu/entries.js +16 -100
  61. package/dist/components/MultiSelect/MultiSelect.js +43 -34
  62. package/dist/components/NumberInput/NumberInput.js +17 -18
  63. package/dist/components/OtpInput/OtpInput.d.ts +1 -1
  64. package/dist/components/OtpInput/OtpInput.js +10 -67
  65. package/dist/components/PageHeader/PageHeader.js +2 -2
  66. package/dist/components/Pagination/Pagination.js +3 -1
  67. package/dist/components/PasswordInput/PasswordInput.d.ts +1 -1
  68. package/dist/components/PasswordInput/PasswordInput.js +9 -4
  69. package/dist/components/Popover/Popover.d.ts +6 -7
  70. package/dist/components/Popover/Popover.js +2 -19
  71. package/dist/components/Progress/Progress.d.ts +1 -1
  72. package/dist/components/Progress/Progress.js +7 -11
  73. package/dist/components/Radio/Radio.d.ts +4 -2
  74. package/dist/components/RadioGroup/RadioGroup.d.ts +5 -12
  75. package/dist/components/RadioGroup/RadioGroup.js +6 -33
  76. package/dist/components/RichTextEditor/RichTextEditor.d.ts +63 -0
  77. package/dist/components/RichTextEditor/RichTextEditor.js +175 -0
  78. package/dist/components/RichTextEditor/toolbar.d.ts +15 -0
  79. package/dist/components/RichTextEditor/toolbar.js +142 -0
  80. package/dist/components/RichTextEditor/uploads.d.ts +41 -0
  81. package/dist/components/RichTextEditor/uploads.js +124 -0
  82. package/dist/components/SearchInput/SearchInput.js +4 -2
  83. package/dist/components/SectionHeader/SectionHeader.js +1 -3
  84. package/dist/components/SegmentedControl/SegmentedControl.js +2 -12
  85. package/dist/components/Select/Select.d.ts +15 -16
  86. package/dist/components/Select/Select.js +11 -252
  87. package/dist/components/Slider/Slider.js +11 -21
  88. package/dist/components/Sparkline/Sparkline.js +8 -3
  89. package/dist/components/Spinner/Spinner.js +5 -2
  90. package/dist/components/Stack/Stack.d.ts +867 -5
  91. package/dist/components/Stack/Stack.js +2 -3
  92. package/dist/components/Stat/Stat.js +6 -3
  93. package/dist/components/Steps/Steps.js +6 -3
  94. package/dist/components/Switch/Switch.d.ts +7 -7
  95. package/dist/components/Switch/Switch.js +4 -10
  96. package/dist/components/Table/Table.js +38 -19
  97. package/dist/components/Tabs/Tabs.js +2 -22
  98. package/dist/components/Tag/Tag.js +3 -1
  99. package/dist/components/Text/Text.d.ts +9 -5
  100. package/dist/components/Text/Text.js +3 -4
  101. package/dist/components/TileGrid/TileGrid.js +1 -1
  102. package/dist/components/TimePicker/TimePicker.js +35 -33
  103. package/dist/components/Timeline/Timeline.js +5 -4
  104. package/dist/components/Toaster/Toaster.js +21 -17
  105. package/dist/components/Tooltip/Tooltip.d.ts +6 -6
  106. package/dist/components/Tooltip/Tooltip.js +3 -17
  107. package/dist/components/TreeView/TreeView.js +15 -12
  108. package/dist/components.css +281 -60
  109. package/dist/hooks/useTheme.js +6 -6
  110. package/dist/icons/message-circle.svg +1 -0
  111. package/dist/internal/CharCount.js +3 -1
  112. package/dist/internal/choice.d.ts +10 -48
  113. package/dist/internal/choice.js +8 -96
  114. package/dist/internal/describedBy.d.ts +3 -0
  115. package/dist/internal/describedBy.js +4 -0
  116. package/dist/internal/options.d.ts +10 -5
  117. package/dist/internal/options.js +25 -11
  118. package/dist/internal/status.d.ts +3 -2
  119. package/dist/internal/status.js +10 -2
  120. package/dist/internal/useScrollActive.js +2 -2
  121. package/dist/internal/useToday.d.ts +3 -0
  122. package/dist/internal/useToday.js +42 -0
  123. package/dist/lib/dates.js +25 -15
  124. package/dist/lib/format.js +11 -8
  125. package/dist/lib/icons.d.ts +5 -0
  126. package/dist/lib/icons.js +2 -0
  127. package/dist/lib/math.js +17 -5
  128. package/dist/lib/rich-text.d.ts +13 -0
  129. package/dist/lib/rich-text.js +62 -0
  130. package/dist/lib/space.d.ts +1 -2
  131. package/dist/lib/space.js +4 -1
  132. package/dist/lib/text.js +1 -1
  133. package/dist/lib/theme.js +1 -1
  134. package/dist/localization.d.ts +166 -0
  135. package/dist/localization.js +142 -0
  136. package/dist/tokens.css +2 -0
  137. package/dist/tokens.dtcg.json +10 -0
  138. package/dist/tokens.json +10 -0
  139. package/dist/types.d.ts +6 -1
  140. package/dist/vokality.css +283 -60
  141. package/dist/vokality.iife.js +35981 -9698
  142. package/docs/brand.md +8 -5
  143. package/docs/components/AppShell/README.md +1 -1
  144. package/docs/components/Badge/README.md +1 -1
  145. package/docs/components/BarChart/README.md +1 -0
  146. package/docs/components/Button/README.md +4 -2
  147. package/docs/components/ChatInbox/README.md +41 -0
  148. package/docs/components/ChatWidget/README.md +47 -0
  149. package/docs/components/Checkbox/README.md +7 -3
  150. package/docs/components/ContextMenu/README.md +7 -3
  151. package/docs/components/Dialog/README.md +9 -4
  152. package/docs/components/Drawer/README.md +1 -1
  153. package/docs/components/Field/README.md +1 -1
  154. package/docs/components/Fieldset/README.md +2 -2
  155. package/docs/components/Inline/README.md +1 -1
  156. package/docs/components/LineChart/README.md +1 -0
  157. package/docs/components/LocaleProvider/README.md +48 -0
  158. package/docs/components/Menu/README.md +13 -8
  159. package/docs/components/OtpInput/README.md +9 -5
  160. package/docs/components/PasswordInput/README.md +11 -2
  161. package/docs/components/Popover/README.md +6 -3
  162. package/docs/components/Progress/README.md +3 -1
  163. package/docs/components/RadioGroup/README.md +5 -2
  164. package/docs/components/RichTextEditor/README.md +84 -0
  165. package/docs/components/SegmentedControl/README.md +2 -0
  166. package/docs/components/Select/README.md +13 -17
  167. package/docs/components/Skeleton/README.md +1 -1
  168. package/docs/components/Slider/README.md +4 -2
  169. package/docs/components/Steps/README.md +1 -1
  170. package/docs/components/Switch/README.md +5 -2
  171. package/docs/components/Tabs/README.md +4 -2
  172. package/docs/components/Text/README.md +1 -1
  173. package/docs/components/Toaster/README.md +3 -1
  174. package/docs/components/Tooltip/README.md +5 -3
  175. package/package.json +49 -5
package/docs/brand.md CHANGED
@@ -15,7 +15,7 @@ The Vokality design system is the shared look for anything Vokality builds or pu
15
15
  - Start buttons with a verb ("Save changes", "Export CSV"), and confirm with the same verb in the past tense ("Saved", "Exported").
16
16
  - Error messages say what went wrong and how to fix it, without apology: "Enter an email address like name@company.com."
17
17
  - Headlines may use the two-beat pattern: a light setup in `display-light`, then a bold close in `display-bold` ("Fewer steps. Same result.").
18
- - No emoji, no exclamation marks, no superlatives, no filler numbers.
18
+ - No emoji in interface or brand copy, no exclamation marks, no superlatives, no filler numbers. User-authored rich text may contain Unicode emoji.
19
19
 
20
20
  ## Components
21
21
 
@@ -24,7 +24,7 @@ Build screens from **primitives** first. **Patterns** are primitives already com
24
24
  | Layer | Group | Components |
25
25
  | --- | --- | --- |
26
26
  | Primitives | Actions | `Button` (primary, outline, ghost, danger; default and `sm`; `loading`, `block`), `IconButton`, `Link`, `Menu` (submenus, checkbox and radio items), `ContextMenu` |
27
- | Primitives | Form controls | `Field` (label, hint, error), `Input` (prefix, suffix, character count), `Textarea`, `PasswordInput`, `NumberInput`, `Slider`, `OtpInput`, `SearchInput`, `Select`, `Combobox`, `MultiSelect`, `DatePicker` (typed or picked), `Calendar`, `TimePicker`, `Checkbox`, `Radio`, `RadioGroup`, `Switch`, `SegmentedControl`, `FileUpload`, `ErrorSummary` |
27
+ | Primitives | Form controls | `Field` (label, hint, error), `Input` (prefix, suffix, character count), `Textarea`, `RichTextEditor` (Markdown, emoji, attachment uploads), `PasswordInput`, `NumberInput`, `Slider`, `OtpInput`, `SearchInput`, `Select`, `Combobox`, `MultiSelect`, `DatePicker` (typed or picked), `Calendar`, `TimePicker`, `Checkbox`, `Radio`, `RadioGroup`, `Switch`, `SegmentedControl`, `FileUpload`, `ErrorSummary` |
28
28
  | Primitives | Feedback | `Alert`, `Toaster` + `toast()`, `Progress`, `Spinner`, `Skeleton`, `EmptyState` |
29
29
  | Primitives | Overlays | `Dialog` (and alert dialog), `Drawer`, `Popover`, `Tooltip`, `CommandPalette` (⌘K) |
30
30
  | Primitives | Navigation | `Tabs`, `Pagination`, `Breadcrumbs`, `NavList`, `Steps`, `TreeView` |
@@ -98,7 +98,7 @@ The test suite checks these pairs in every theme and fails the build if one slip
98
98
 
99
99
  ## Space and layout
100
100
 
101
- - Dense operational apps can opt in with `data-density="compact"` on `<html>`. The shared compact scale is 20px page titles, 16px section titles, 14px body and controls, 12px metadata and 24px statistics. Headers add no trailing section margin; compose vertical rhythm with `Stack`. Actions align with the page title. Controls share a 32px height for fine pointers and retain 44px when a coarse pointer is available. The default scale is unchanged.
101
+ - Dense operational apps can opt in with `data-density="compact"` on `<html>`. The shared compact scale is 20px page titles, 16px section titles, 14px body and fine-pointer controls (16px input text with a coarse pointer, which stops iOS focus zoom), 24px statistics; smaller text (metadata, captions) keeps its size. Table cells, list and navigation rows, menus and cards tighten too. Headers add no trailing section margin; compose vertical rhythm with `Stack`. Actions align with the page title. Controls share a 32px height for fine pointers and retain 44px when a coarse pointer is available. The default scale is unchanged.
102
102
 
103
103
  - Apps: wrap the screen in `AppShell` (56px top bar, 15rem sidebar that collapses to icons and becomes an overlay below 48rem), put a `PageHeader` at the top of each page, and lay out content with `Stack`, `Inline` and `Grid`. Start new pages from the templates.
104
104
  - Sites and documents: set content in one frame, max-width 80rem (`--content-max`), outlined left, right and bottom by `border-subtle`, over a faint 10px dot grid (`.vk-dot-grid`) on marketing pages.
@@ -118,6 +118,7 @@ The test suite checks these pairs in every theme and fails the build if one slip
118
118
  - Durations are tokens: `motion-fast` 200ms (link, icon and color changes), `motion-normal` 300ms (button fills, overlays opening), `motion-slow` 500ms (page entrance). Easing: `ease-standard`, `cubic-bezier(0.4, 0, 0.2, 1)`. They are exported to CSS, Tailwind and the DTCG file.
119
119
  - Overlays fade and rise 0.5rem; drawers slide 1.5rem. Pages may float up 1.25rem on load. Images in media cards scale to 1.04 on hover.
120
120
  - The square glyph's 3.4s border sweep is the one ambient animation; don't add others.
121
+ - Chat uses Motion for React: a 200ms fade with a small rise and scale on opening, a 120ms exit, quiet launcher hover/press feedback, and a short entrance for newly added messages. Existing conversation history stays still. Radix continues to own interaction and focus behavior.
121
122
  - Under `prefers-reduced-motion` every animation and transition stops.
122
123
 
123
124
  ## Iconography
@@ -140,6 +141,7 @@ The test suite checks these pairs in every theme and fails the build if one slip
140
141
 
141
142
  ## Locale and formatting
142
143
 
144
+ - Use `LocaleProvider` from `@vokality/design-system/localization` for scoped interface copy and formatting. English is the default; Dutch messages cover `nl-*` locales. Providers inherit translations, accept typed message overrides, update with application locale changes, and reach portalled controls. Existing label props take precedence; a control's explicit locale selects its own default dictionary and formatting. Papiamentu tags use the documented Dutch fallback, rather than claiming a Papiamentu translation.
143
145
  - Format numbers, money, percentages and dates with `formatNumber`, `formatCurrency`, `formatPercent` and `formatDate`, and pass the same `locale` to `Calendar`, `DatePicker` and `TimePicker`. Never build these strings by hand.
144
146
  - Supported and tested: `en-US`, `nl-NL`, and the Dutch Caribbean locales `nl-CW` (Curaçao), `nl-AW` (Aruba), `nl-SX` (Sint Maarten) and `nl-SR` (Suriname). Papiamentu tags (`pap-CW`, `pap-AW`) fall back to the matching Dutch locale for numbers and dates, since browsers carry no Papiamentu data.
145
147
  - Currency: the Caribbean guilder (`XCG`, which replaced `ANG`) shows as "Cg.", the Aruban florin (`AWG`) as "Afl.". The Surinamese dollar always shows its code (`SRD`), because its local "$" reads as US dollars.
@@ -148,7 +150,7 @@ The test suite checks these pairs in every theme and fails the build if one slip
148
150
  ## Touch and pointer
149
151
 
150
152
  - Tooltips open on hover after 400ms, at once on keyboard focus, and on a tap for 1.5s. They hold only a hint: anything a touch user needs must also be visible or in the control's label.
151
- - Every target is at least 32px (`sm` buttons) and 44px for form controls. Context menus also open with the keyboard (Shift+F10 or the Menu key).
153
+ - Every target is at least 24px (WCAG 2.5.8); small controls such as tag remove buttons and sort headers extend their hit area without changing their look. With a coarse pointer, buttons, form controls, menu, navigation and tree rows, choices and pagination are 44px in every density. Context menus also open with the keyboard (Shift+F10 or the Menu key).
152
154
 
153
155
  ## Using the system in code
154
156
 
@@ -161,5 +163,6 @@ The test suite checks these pairs in every theme and fails the build if one slip
161
163
 
162
164
  - The visual language was first taken from the Vokality website and generalised for every Vokality project. The package (the private `Vokality/design-system` repository) is the source of truth: tokens in `tokens/tokens.json`, components in `src/`, and this documentation in `docs/`. Fluid `clamp()` sizes, textures and one-off color mixes live in the component CSS.
163
165
  - Versioning follows semver: renaming or removing a token, component or prop is a major release; new tokens, components and props are minor; fixes are patches. See `CONTRIBUTING.md` and `CHANGELOG.md`.
164
- - Not yet defined: rich-text editing, and a Figma component library (the tokens import into Figma; the components themselves exist only in code).
166
+ - Rich-text editing uses `RichTextEditor` from `@vokality/design-system/rich-text`: Markdown is the persisted value, with basic formatting, Unicode emoji and app-provided attachment uploads. The editor uses system tokens and accessible field/toolbar conventions.
167
+ - Components are authored in code. Tokens import into Figma; a parallel Figma component library is optional and is not maintained here.
165
168
  - Fonts are Latin subsets.
@@ -10,7 +10,7 @@ The frame of an application: a top bar with the brand, search and account action
10
10
 
11
11
  ## Behaviour
12
12
  - Desktop: the collapse button hides and shows the sidebar.
13
- - Mobile (under 48rem): the menu button opens the sidebar over the page with the `overlay` scrim as a modal dialog (Radix Dialog, `aria-modal`, labelled by `sidebarLabel`): it slides in 1.5rem, focus moves to its first link and stays inside, the rest of the shell is hidden from assistive technology, and Esc or a scrim click closes it and returns focus to the menu button. Widening the window past 48rem closes it.
13
+ - Mobile (under 48rem): the menu button opens the sidebar over the page with the `overlay` scrim as a modal dialog (Radix Dialog, `aria-modal`, labelled by `sidebarLabel`): it slides in 1.5rem, Radix chooses initial focus and traps it inside (its default autofocus skips links), the rest of the shell is hidden from assistive technology, and Esc or a scrim click closes it and returns focus to the menu button. Widening the window past 48rem closes it.
14
14
 
15
15
  ## Props
16
16
  - `brand`, `sidebar`, `sidebarFooter`, `search`, `actions`, `children`, `defaultCollapsed`, `mainId`, `height`, and labels: `skipLabel`, `menuLabel`, `collapseLabel`, `expandLabel`, `sidebarLabel`.
@@ -1,6 +1,6 @@
1
1
  # Badge
2
2
 
3
- `icon` adds a system status icon beside the label. Standard span attributes and a forwarded ref allow a badge to be a tooltip trigger: `<Tooltip content="Connected recently"><Badge tone="success" icon="circle-check" tabIndex={0}>Online</Badge></Tooltip>`. Focusable badges show the shared focus ring and provide a 32px target (44px with a coarse pointer); essential information must also remain visible.
3
+ `icon` adds a system status icon beside the label. Standard span attributes and a forwarded ref allow a badge to be a tooltip trigger: `<Tooltip content="Connected recently"><Badge tone="success" icon="circle-check" tabIndex={0}>Online</Badge></Tooltip>`. Focusable badges show the shared focus ring and provide a `--button-height-sm` target (32px, 44px with a coarse pointer); essential information must also remain visible.
4
4
 
5
5
  A small outlined tag for status, set beside a title or in a table cell.
6
6
 
@@ -11,6 +11,7 @@ Vertical bars for comparing amounts across categories or periods: grouped for a
11
11
  ## Props
12
12
  - `data`: rows; `xKey` (default `label`) names the category field.
13
13
  - `series`: `{ key, label }[]`; omit for one series read from `value`.
14
+ - Measurements must be finite numbers or `null`; other values throw a `TypeError`. Null or absent fields display `—` in the data table and tooltip and retain zero-height geometry. Formatters receive finite numbers only.
14
15
  - `stacked`, `height` (240), `valueFormat(v)`, `tickFormat(v)`, `title`, `description`, `allowTable` (true), `locale`.
15
16
 
16
17
  ## Color
@@ -40,6 +40,8 @@ The button for actions and record names, with square corners and a visible keybo
40
40
 
41
41
  ## Rules
42
42
  - One `primary` per view. Put it first in a row and last in a dialog footer.
43
- - Under 40rem, buttons stretch to the column width; `text` stays content-sized. Text buttons support multiline labels and keep a 32px minimum target, 44px with a coarse pointer.
44
- - With `data-density="compact"` on `html`, action labels use 12px and record names use 14px. Buttons align with inputs at 32px for fine pointers or 44px when a coarse pointer is available.
43
+ - Under 40rem, buttons stretch to the column width; `text` stays content-sized. Text buttons support multiline labels and keep a 32px minimum target.
44
+ - With `data-density="compact"` on `html`, record names use 14px and action labels keep their size (12px, 11px at `sm`). Compact redefines `--button-height` and `--button-height-sm` to the control height, so buttons of both sizes align with inputs at 32px for fine pointers or 44px when a coarse pointer is available.
45
+ - Beside a field in an `Inline` row, a button takes the field height (44px by default, 32px compact with a fine pointer).
46
+ - With a coarse pointer, every button and icon button is 44px in any density (`--button-height` and `--button-height-sm` follow `--control-height`).
45
47
  - Don't use a button for navigation inside running text; use `Link`.
@@ -0,0 +1,41 @@
1
+ # ChatInbox
2
+
3
+ An embedded thread list and conversation panel. Wider containers show both; phone-sized containers show the list or selected conversation, with a Back action. The transcript and Markdown composer are shared with `ChatWidget`.
4
+
5
+ ```tsx
6
+ import { useState } from "react";
7
+ import { ChatInbox } from "@vokality/design-system/chat-inbox";
8
+ import type { ChatMessage, ChatThread } from "@vokality/design-system/chat-models";
9
+
10
+ function Inbox({ threads, messages }: { threads: ChatThread[]; messages: ChatMessage[] }) {
11
+ const [selected, setSelected] = useState<string | null>(null);
12
+ return <ChatInbox
13
+ title="Inbox"
14
+ threads={threads}
15
+ selectedThreadId={selected}
16
+ onSelectThread={setSelected}
17
+ messages={messages}
18
+ composer={{ onSend(markdown) { sendToApplication(selected, markdown); } }}
19
+ />;
20
+ }
21
+ ```
22
+
23
+ ## Thread data
24
+
25
+ `threads` is an array of `ChatThread`: `id`, `title`, optional render-ready `preview`, `avatar`, `timestamp`, positive whole-number `unreadCount` and `disabled`. IDs stay stable across updates. The application owns filtering, fetching, selection, message data, delivery and retry requests.
26
+
27
+ `selectedThreadId` and `onSelectThread(id)` form the controlled selection contract. Back emits `null`. `title` names the thread list and defaults to “Conversations”; the conversation header uses the selected thread title. With no selection, `emptySelection` overrides the invitation to choose a conversation. An empty thread list has localized feedback.
28
+
29
+ Selecting a thread focuses its heading after the application accepts the selection. Back returns focus to its thread button. The layout responds to container width, including inside a narrow desktop column. No viewport listener, custom list keyboard behavior or routing is added.
30
+
31
+ ## Conversation and composer
32
+
33
+ The remaining props match `ChatWidget`: `messages`, `composer`, `emptyState`, `pending`, `error`, `onRetry`, `onRetryMessage(id)` and transcript `aria-label`. See [ChatWidget](../ChatWidget/README.md) for the render-ready message and Markdown composer contracts.
34
+
35
+ Writing comes first. A small lower action row offers Aa, emoji and optional attachments; Aa reveals bold, italic, link and bullet-list controls through the editor's native Radix disclosure.
36
+
37
+ Switching threads remounts the conversation panel, canceling pending editor uploads and clearing an uncontrolled draft. Supply a controlled composer value and keep drafts by thread ID in the application when drafts should survive navigation. Applications also own successful-send acknowledgement: controlled drafts do not clear automatically.
38
+
39
+ Use `LocaleProvider.messages.chat` for conversation labels and `messages.richText` for editor labels. Colors, typography, outlines and compact controls use system tokens. The inbox height follows the dynamic viewport; the thread list, transcript and composer have bounded scrolling. No AI service or backend is bundled.
40
+
41
+ New messages receive a brief Motion fade and 4px rise. Existing thread history appears immediately without a stagger. Reduced-motion preferences remove the translation and animation duration.
@@ -0,0 +1,47 @@
1
+ # ChatWidget
2
+
3
+ A floating chat icon opens a conversation above it. The panel shares its transcript and Markdown composer with `ChatInbox`. Radix Popover owns opening, focus, Escape, outside dismissal and returning focus to the launcher.
4
+
5
+ ```tsx
6
+ import { ChatWidget } from "@vokality/design-system/chat-widget";
7
+ import type { ChatMessage } from "@vokality/design-system/chat-models";
8
+
9
+ const messages: ChatMessage[] = [{
10
+ id: "welcome",
11
+ author: { name: "Support" },
12
+ direction: "incoming",
13
+ content: <p>What can we help you with?</p>,
14
+ }];
15
+
16
+ <ChatWidget
17
+ title="Ledger support"
18
+ messages={messages}
19
+ composer={{ onSend(markdown) { sendToApplication(markdown); } }}
20
+ />;
21
+ ```
22
+
23
+ ## Data and delivery
24
+
25
+ `ChatMessage` contains a stable `id`, `author: { name, avatar? }`, `direction`, render-ready `content`, optional `timestamp`, and optional `delivery`. `delivery: { state: "pending" }` shows sending feedback. `{ state: "failed", error? }` shows failure feedback and a retry action when `onRetryMessage(id)` is supplied. Omit delivery for a sent message.
26
+
27
+ The application owns the message array, transport, authentication, async sending, retries and persistence. Content is a React node; strings are displayed as text. The component does not parse incoming Markdown or inject HTML. Render formatted content in your application, including through an existing read-only `RichTextEditor` if useful.
28
+
29
+ ## Composer
30
+
31
+ `composer` accepts `value`, `defaultValue`, `onChange`, `onSend(markdown)`, `disabled`, `sending`, `label`, `sendLabel`, `placeholder` and `name`. `onSend` accepts the CommonMark document synchronously; handle application promises and errors in your callback. An uncontrolled draft clears after the callback returns normally. A controlled draft remains until the application changes `value`.
32
+
33
+ The Send action is disabled for empty drafts, while `disabled` or `sending` is true, and while attachment uploads are pending. Existing editor formatting, emoji and attachments are reused. Pass `onUploadAttachment`, `accept`, `maxFileSize`, `emojiOptions` and `onUploadError` through `composer`; the editor validates uploaded links, handles retry/cancel and ignores stale responses.
34
+
35
+ The composer shows the writing field first. Its lower action row contains Aa, emoji, and an attachment action when uploads are configured. Aa reveals bold, italic, link and bullet-list tools; the full standalone editor toolbar is kept out of the initial chat view.
36
+
37
+ ## States and layout
38
+
39
+ - `open`, `defaultOpen`, `onOpenChange` and `modal` pass directly to Radix. The default is non-modal. `align` chooses the start or end corner; end is the default.
40
+ - `triggerLabel` overrides “Open chat”; `unreadCount` adds an accessible unread count.
41
+ - `title` names the panel; `description` adds supporting content. `aria-label` names the transcript log.
42
+ - `emptyState`, `pending`, `error` and `onRetry` present application state. New messages are announced politely; scrolling up to read history stops automatic following.
43
+ - The launcher respects safe-area insets. Panel height follows the dynamic viewport and available Radix space. Long text wraps, while transcript and composer scroll within the panel.
44
+
45
+ Motion animates the native Radix panel with a brief fade and 8px rise on opening, and a shorter exit. The launcher has small hover/press feedback. New messages fade in with a 4px rise; existing history is shown immediately. Reduced-motion preferences remove translations, scaling and animation duration. Radix retains focus, keyboard and dismissal behavior throughout.
46
+
47
+ Built-in labels use `LocaleProvider.messages.chat`; rich-editor labels remain in `messages.richText`. All themes and compact density use existing tokens. Import the system CSS once. No AI service or backend is bundled.
@@ -20,9 +20,13 @@ A square box for turning a single option on or off, or for picking several optio
20
20
  | Disabled, checked | `muted-subtle` fill and border | `primary-foreground` check |
21
21
 
22
22
  ## Props
23
- - `label` (required), `description`, `indeterminate`, `hideLabel` (keeps the label for screen readers only, as in table rows), and any checkbox attribute: `name`, `value`, `checked` or `defaultChecked`, `onChange`, `disabled`, `required`.
24
- - `onChange` receives a change event whose `target` reads `checked`, `value` and `name` as a native checkbox would. Clicking an indeterminate box checks it.
25
- - The ref (and any `Tooltip` or `Popover` around it) gets the control, a `button` with `role="checkbox"` and `aria-checked` (`mixed` when indeterminate). Inside a `form` a hidden checkbox carries `name`, `value` and `required`, so it submits, validates and resets like a native one.
23
+ - `label` (required), `description`, `hideLabel`, and Radix Checkbox Root props: `name`, `value`, `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `required`, and button DOM callbacks.
24
+ - `checked` and `defaultChecked` accept `boolean | "indeterminate"`. Radix owns uncontrolled state, keyboard interaction and form inputs. `onCheckedChange(state)` reports the new state directly.
25
+ - Use `defaultChecked="indeterminate"` for an uncontrolled mixed checkbox; clicking it checks it. A controlled checkbox uses `checked="indeterminate"` until its caller supplies a new state.
26
+ - The ref and DOM callbacks refer to the real `HTMLButtonElement` with `role="checkbox"`. Inside a form, Radix supplies its hidden checkbox for submission, validation and reset.
27
+ - Migration: replace `indeterminate` with a checked-state value and replace `onChange(event)` with `onCheckedChange(state)`. For example, `<Checkbox label="All" checked={some ? "indeterminate" : all} onCheckedChange={setChecked} />`.
28
+
29
+ See [Radix Checkbox](https://www.radix-ui.com/primitives/docs/components/checkbox) for the behavior and callback contract.
26
30
 
27
31
  ## Rules
28
32
  - The label states what will be true when checked ("Email me when an invoice is paid").
@@ -1,13 +1,17 @@
1
1
  # ContextMenu
2
2
 
3
- Right-click (or long-press, or Shift+F10) actions for a region: a file, a row, a canvas object. Built on Radix ContextMenu (non-modal).
3
+ Actions for a region: a file, a row, a canvas object. The component styles Radix ContextMenu and maps `items` to its primitive parts. Radix owns trigger gestures, modal focus management, positioning, navigation and dismissal.
4
4
 
5
5
  ## Behaviour
6
- - Opens at the pointer (or after a 700ms press on touch screens) with the same `Menu` panel, items, separators, checkable items and submenus, and the same keyboard. It stays inside the viewport and focus moves to its first item.
7
- - Shift+F10 or the context-menu key opens it at the focused element's bottom-left corner (in every browser, not only those that send a `contextmenu` event for those keys). Esc, Tab, a click outside or scrolling closes it; after Esc, Tab or choosing an item focus returns to where it was.
6
+ - Radix opens at a native context-menu event's pointer position and supports touch/pen long press. It supplies collision handling and the same primitive items, separators, checkable items and submenus as `Menu`.
7
+ - Pointer opening focuses the menu container; arrow navigation then reaches enabled items. Keyboard opening depends on the browser emitting a native `contextmenu` event. The wrapper does not synthesize Shift+F10 or context-menu-key events.
8
+ - Esc and item selection close the menu using Radix's focus lifecycle. Tab is prevented while open. The wrapper adds no scrolling listener, delayed opening, custom focus movement or alternate dismissal behavior.
9
+ - Root menus and submenus shrink to Radix's measured available width and height near viewport edges. The usual 13rem minimum applies when it fits; longer labels and shortcuts wrap, and the submenu arrow retains its size. Positioning and side changes remain native.
8
10
 
9
11
  ## Props
10
12
  - `items` (as in `Menu`), `children` (the region, wrapped in a `div.vk-context-target`; put a focusable element inside so keyboard users can open it), `label` (the menu's name, default "Actions"), `disabled` (no menu: the browser's own shows instead).
11
13
 
12
14
  ## Rules
13
15
  - A context menu is a shortcut. Every action in it must also be reachable another way (a row `Menu`, a toolbar button), because touch and keyboard users may never open it.
16
+
17
+ See the [Radix Context Menu documentation](https://www.radix-ui.com/primitives/docs/components/context-menu) for the underlying interaction contract.
@@ -10,15 +10,18 @@ A modal window that takes focus for a task or decision before people return to t
10
10
  5. **Footer**: right-aligned buttons above a `border-subtle` rule: the confirming action last, as `primary` (or `danger` for destructive ones).
11
11
 
12
12
  ## Behaviour
13
- - Opening moves focus to the first field in the body (or the element marked `data-autofocus`), else the first footer button.
13
+ - Radix owns initial focus and Tab order. With the standard header, the close button is the first eligible control. `data-autofocus` has no special meaning; applications can use the native `contentProps.onOpenAutoFocus` hook when a task needs a particular target.
14
14
  - Tab and Shift+Tab stay inside the dialog. The page behind can't scroll and is hidden from assistive technology and pointer input while it is open.
15
- - Esc, the close button and a backdrop click call `onClose`. Closing returns focus to whatever opened the dialog.
16
- - `role="alertdialog"` is for destructive confirmations: no close button, and Esc and the backdrop do nothing, so people must choose.
15
+ - Esc, the close button and a backdrop click call `onOpenChange(false)` and the optional `onClose` alias. Use `trigger` to compose a Radix Trigger; Radix then restores focus to that trigger on close. Imperative openings without a trigger need application-specific focus handling through the native content hooks.
16
+ - `role="alertdialog"` uses Radix AlertDialog: outside presses do nothing, Escape closes, and the `cancel` element receives initial focus. Supply `cancel` and `action` elements to compose native Radix Cancel and Action controls.
17
17
  - The panel rises 0.5rem as it fades in (none under reduced motion); it closes at once.
18
18
  - Selects, menus, date pickers and popovers inside the body float above the dialog, so a field near the bottom can open its list without being clipped.
19
19
 
20
20
  ## Props
21
- - `open`, `onClose`, `title`, `description`, `children`, `footer`, `size`, `role`, `dismissible`, `closeOnBackdrop`, `closeLabel`.
21
+ - Native state: `open`, `defaultOpen`, `onOpenChange`. `onClose` remains an alias for a close notification.
22
+ - Composition: `trigger` (one focusable element that forwards its ref), `title`, `description`, `children`, `footer`, and alert dialog `cancel` / `action` elements.
23
+ - Presentation: `size`, `role`, `hideCloseButton`, `closeLabel`, `className`. Hiding the close button does not disable native dismissal.
24
+ - `contentProps` forwards Radix Content props, including autofocus, Escape and outside-interaction hooks. AlertDialog always owns outside dismissal. The old `dismissible` and `closeOnBackdrop` policies are removed; when an application needs an exception, prevent the corresponding native event explicitly.
22
25
 
23
26
  ## Accessibility
24
27
  `role="dialog"` (or `alertdialog`), `aria-modal="true"`, labelled by the title (`aria-labelledby`) and described by the description (`aria-describedby`, only when there is one); rendered in a portal on `document.body`. Open state is exposed as `data-state="open"` on the overlay and the panel.
@@ -26,3 +29,5 @@ A modal window that takes focus for a task or decision before people return to t
26
29
  ## Rules
27
30
  - The title states the task or question ("Delete INV-1043?"). Buttons repeat the verb ("Delete invoice"), never "OK" or "Yes".
28
31
  - One dialog at a time. For side detail that people compare against the page, use a `Drawer`.
32
+
33
+ [Radix Dialog documentation](https://www.radix-ui.com/primitives/docs/components/dialog) and [AlertDialog documentation](https://www.radix-ui.com/primitives/docs/components/alert-dialog) define the interaction contract.
@@ -6,7 +6,7 @@ A modal panel that slides in from the side, for detail views and longer forms th
6
6
  Same parts as `Dialog` (header, body, footer) in a full-height panel up to 28rem wide (the full width on phones), with a 1px `border` on its inner edge. It slides in 1.5rem from its side (from the left for `side="left"`).
7
7
 
8
8
  ## Behaviour
9
- Identical to `Dialog` (Radix Dialog): focus moves in and is trapped, Esc and a backdrop click close it, focus returns to the opener, and the page can't scroll.
9
+ Identical to `Dialog` (Radix Dialog): focus moves in and is trapped, Esc and a backdrop click close it, focus returns to its `trigger`, and the page can't scroll.
10
10
 
11
11
  ## Props
12
12
  - All `Dialog` props, plus `side`: `right` (default) or `left`.
@@ -3,7 +3,7 @@
3
3
  The wrapper that gives any form control its label, hint and error, and wires them together for assistive technology.
4
4
 
5
5
  ## Anatomy
6
- 1. **Label**: a Radix Label, `card-eyebrow` style in `muted-foreground`, uppercase; clicking it focuses the control. An optional marker ("Optional") sits after it in `muted-subtle`, sentence case.
6
+ 1. **Label**: a Radix Label, `card-eyebrow` style in `muted-foreground`, uppercase; native label activation reaches the control. A contenteditable editor receives an explicit focus bridge because HTML labels cannot target it. An optional marker ("Optional") sits after it in `muted-subtle`, sentence case.
7
7
  2. **Control**: one `Input`, `Textarea`, `SearchInput`, `Select`, `Combobox`, `MultiSelect` or `DatePicker` passed as the child.
8
8
  3. **Hint** (optional): `small` text in `muted-subtle` under the control.
9
9
  4. **Error** (optional): `small` text in `primary-hover`, below the hint.
@@ -17,8 +17,8 @@ A labelled group of related controls, such as permissions or notification prefer
17
17
 
18
18
  ```tsx
19
19
  <Fieldset legend="Permissions" hint="Choose what this staff member can do.">
20
- <Checkbox label="Read operations" checked={read} onChange={setRead} />
21
- <Checkbox label="Manage invitations" checked={invite} onChange={setInvite} />
20
+ <Checkbox label="Read operations" checked={read} onCheckedChange={checked => setRead(checked === true)} />
21
+ <Checkbox label="Manage invitations" checked={invite} onCheckedChange={checked => setInvite(checked === true)} />
22
22
  </Fieldset>
23
23
  ```
24
24
 
@@ -1,6 +1,6 @@
1
1
  # Inline
2
2
 
3
- Standard element attributes and events pass through to `as`, including IDs, ARIA labels and form events. Use `<Inline as="form" onSubmit={...}>` for a search toolbar. `style` can size a flex item; visual controls remain system components.
3
+ Standard element attributes and events pass through to `as`, including IDs, ARIA labels and form events. Use `<Inline as="form" onSubmit={...}>` for a search toolbar. When a row contains a field, its buttons and icon buttons take the field height (`--control-height`), whatever their `size`, so they sit flush. `style` can size a flex item; visual controls remain system components.
4
4
 
5
5
  Lays children out in a row that wraps, with one gap. For button groups, tag lists, metadata rows and toolbars.
6
6
 
@@ -9,6 +9,7 @@ Lines for change over time: one to four series, each labeled directly at its end
9
9
 
10
10
  ## Props
11
11
  - `data`, `xKey`, `series`, `height`, `valueFormat`, `tickFormat`, `directLabels` (true for up to four series), `title`, `description`, `allowTable`, `locale`.
12
+ - Measurements must be finite numbers or `null`; other values throw a `TypeError`. Null or absent fields display `—` in the data table and tooltip and retain zero-height geometry. Formatters receive finite numbers only.
12
13
 
13
14
  ## Color
14
15
  - Series take `chart-1` … `chart-8` in order and never cycle; slot 1 is Vokality orange. A ninth series folds into "Other".
@@ -0,0 +1,48 @@
1
+ # LocaleProvider
2
+
3
+ Choose the language for the system's built-in visible and accessible labels, and the default locale for dates and chart numbers. No provider means `en-US`, consistently on the server and client.
4
+
5
+ ## Use
6
+
7
+ ```tsx
8
+ import { LocaleProvider, useLocale } from "@vokality/design-system/localization";
9
+ import { Calendar, DatePicker, Pagination } from "@vokality/design-system";
10
+
11
+ <LocaleProvider locale="nl-CW">
12
+ <Calendar />
13
+ <DatePicker />
14
+ <Pagination pageCount={5} />
15
+ </LocaleProvider>
16
+ ```
17
+
18
+ The provider adds no element. Set the document's `lang` separately so assistive technology pronounces app content in the right language. Pass the same initial locale during server rendering and hydration; the provider never reads `navigator.language`.
19
+
20
+ ## Languages and formatting
21
+
22
+ - English is the default dictionary. Dutch translations are included for `nl-NL`, `nl-CW`, `nl-AW`, `nl-SX` and `nl-SR` (and other Dutch locale tags).
23
+ - `pap-CW` and `pap-AW` use the existing matching Dutch formatter fallback and Dutch interface labels. These are **not Papiamentu translations**.
24
+ - Other supported Intl locales format dates/numbers in that locale and use English built-in copy until supplied with a `messages` dictionary. Invalid or unsupported locale tags fall back to `en-US`.
25
+ - `Calendar`, `DatePicker`, `TimePicker`, `BarChart` and `LineChart` keep their `locale` prop: it takes precedence over the provider for both formatting and default labels.
26
+ - Standalone `formatNumber`, `formatCurrency`, `formatPercent` and `formatDate` functions have no React context. Pass the hook's `locale` in their options.
27
+
28
+ ## Overrides and inheritance
29
+
30
+ `messages` accepts a typed partial dictionary. String keys supply labels; function keys receive the values to interpolate and can handle plurals. Existing component-specific props such as `closeLabel`, `clearLabel`, `emptyText`, `title` and `rowLabel` still take precedence.
31
+
32
+ ```tsx
33
+ <LocaleProvider locale="nl-NL" messages={{
34
+ close: "Venster sluiten",
35
+ fixProblems: (count) => count === 1 ? "Controleer één veld" : `Controleer ${count} velden`,
36
+ richText: { bold: "Vet maken" },
37
+ }}>
38
+ <App />
39
+ </LocaleProvider>
40
+ ```
41
+
42
+ Nested providers inherit the locale when omitted and merge only the supplied message keys, including `richText` keys. Explicit message overrides inherit even when a nested provider or component chooses another locale. Changes update the current subtree, including React portals such as dialogs, date pickers and toast regions.
43
+
44
+ `useLocale(localeOverride?)` returns `{ locale, messages }`. `locale` is the resolved formatter locale. `LocaleMessages`, `RichTextMessages`, `LocaleMessageOverrides`, `LocaleValue` and `LocaleProviderProps` provide the TypeScript contracts from this same entrypoint.
45
+
46
+ ## Scope
47
+
48
+ The dictionary covers the system's own interface copy: control actions, navigation, loading and status announcements, errors, upload feedback, chart controls, command palette hints and rich-text actions. App-authored content, options, headings, validation messages, file names and toast titles remain the caller's responsibility.
@@ -1,6 +1,6 @@
1
1
  # Menu
2
2
 
3
- A button that opens a list of actions: row actions in a table, "More" in a toolbar, a sort menu. Built on Radix DropdownMenu (non-modal: the page keeps scrolling and a click outside closes it and lands where it was aimed).
3
+ A button that opens a list of actions: row actions in a table, "More" in a toolbar, a sort menu. The component styles Radix DropdownMenu and maps `items` to its primitive parts. Radix owns opening gestures, modal focus management, typeahead, navigation and dismissal, using its default interaction behavior.
4
4
 
5
5
  ## Anatomy
6
6
  1. **Trigger**: an outline `Button` with a chevron glyph cell (`label`), or an `IconButton` (`icon` with `triggerLabel`), usually `ellipsis`.
@@ -20,18 +20,21 @@ A button that opens a list of actions: row actions in a table, "More" in a toolb
20
20
  | Key | Action |
21
21
  | --- | --- |
22
22
  | Enter, Space, ↓ on the trigger | Opens on the first item |
23
- | ↑ on the trigger | Opens on the last item |
24
- | ↓ / ↑ | Next or previous item, wrapping |
23
+ | ↓ / ↑ within the menu | Next or previous enabled item |
25
24
  | Home / End | First or last item |
26
25
  | Letters | Jump to the next item starting with them; letters typed within a second build a prefix |
27
- | Enter / Space | Run the item and close; `onSelect` runs once focus is back on the trigger |
26
+ | Enter / Space | Activate the item using Radix's selection and closing behavior |
28
27
  | Esc | Close and return focus to the trigger |
29
- | Tab | Close and move on |
28
+ | Tab | Prevented while the menu is open; use Esc or activate an item to close |
29
+
30
+ Pointer opening leaves focus on the menu container until an item is pointed to or keyboard navigation begins. Keyboard opening focuses the first enabled item. The wrapper adds no alternative ArrowUp trigger gesture, wrapping, focus scheduling or delayed selection callbacks.
30
31
 
31
32
  ## Checkable items and submenus
32
- - `{ type: 'checkbox', label, checked, onCheckedChange }`: a `menuitemcheckbox` with a check; choosing it calls `onCheckedChange(!checked)`, then `onSelect`, and keeps the menu open.
33
- - `{ type: 'radio', label, checked, onSelect }`: a `menuitemradio` with a dot, for one choice from a group (sort order, density). Consecutive radio items form one `group`, named by a label entry right before them; choosing one keeps the menu open.
34
- - `{ label, items: [...] }`: a submenu with a chevron; it opens to the right on hover, → or Enter, and ← or Esc goes back.
33
+ - `{ type: 'checkbox', label, checked, onCheckedChange }`: a Radix `CheckboxItem` with a check. Its native `onCheckedChange` updates the caller's state; `onSelect` is forwarded directly. Selection closes the menu.
34
+ - `{ type: 'radio', label, checked, onSelect }`: a Radix `RadioItem` with a dot. Consecutive entries form one `RadioGroup`, named by a preceding label entry. The caller updates `checked` through `onSelect`; selection closes the menu.
35
+ - `{ label, items: [...] }`: a Radix submenu with a chevron. Hover or the reading-direction arrow opens it; the opposite arrow returns to the parent. Esc closes the menu.
36
+
37
+ `onSelect` runs at Radix's selection event. If an action opens another component, that component owns its focus lifecycle; the menu does not defer callbacks or move focus on the application's behalf.
35
38
 
36
39
  ## Accessibility
37
40
  WAI-ARIA menu button: the trigger has `aria-haspopup="menu"`, `aria-expanded` and `aria-controls`; the panel is `role="menu"`, labelled by the trigger, with `menuitem`s (`menuitemcheckbox` / `menuitemradio` with `aria-checked`) and a roving focus. Checkable items carry `data-state="checked"` or `"unchecked"`.
@@ -43,3 +46,5 @@ WAI-ARIA menu button: the trigger has `aria-haspopup="menu"`, `aria-expanded` an
43
46
  ## Rules
44
47
  - Menus hold actions. To pick a value, use `Select`; to navigate, use links.
45
48
  - Put destructive items last, after a separator, and confirm them with a `Dialog`.
49
+
50
+ See the [Radix Dropdown Menu documentation](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) for the underlying interaction contract.
@@ -1,17 +1,21 @@
1
1
  # OtpInput
2
2
 
3
- Boxes for a one-time code from an authenticator app, a text message or an email.
3
+ Styled Radix One-Time Password Field parts for a code from an authenticator app, a text message or an email. `unstable_OneTimePasswordField` is a preview API supplied by the pinned `radix-ui@1.8.0`; dependency updates must verify its contract.
4
4
 
5
5
  ## Anatomy
6
- `length` (6) square boxes, 44px wide, centered digits in Space Grotesk at 20px, 0.5rem apart.
6
+ `length` (6) boxes, up to 44px wide, centered digits in Space Grotesk at 20px, 0.5rem apart. Boxes share the available width on narrow screens and wrap when fewer than 24px per box would remain; their height follows the shared control height.
7
7
 
8
8
  ## Behaviour
9
- - Typing a digit moves to the next box; Backspace in an empty box goes back and clears it; ← → move between boxes.
10
- - Pasting a code fills every box. The first box has `autoComplete="one-time-code"`, so phones offer the code from a message.
11
- - `onComplete(code)` fires once all boxes are filled; submit there or enable the button.
9
+ - Radix owns typing, validation, navigation, selection, paste and autofill. The wrapper adds no keyboard handlers, focus movement, paste parsing or internal value state.
10
+ - A single Tab stop represents the code. Direction keys move between available boxes; Home/End reach the ends. Backspace removes the current character and moves back; Delete removes it and shifts later characters back.
11
+ - Pasting replaces the whole code, regardless of the focused box. Radix assigns `autoComplete="one-time-code"` to its active autofill input.
12
+ - `onChange(code)` maps to Radix's `onValueChange`. `onComplete(code)` also runs for a changed value that fills all `length` boxes. The wrapper does not enable automatic form submission; Enter retains the primitive's native form behavior.
13
+ - Radix's `HiddenInput` supplies the single named form value. Disabled fields are excluded from form data.
12
14
 
13
15
  ## Props
14
16
  - `length`, `value` + `onChange`, or `defaultValue`, `onComplete`, `numeric` (default true), `name`, `disabled`, `label` (each box is announced "Digit 3 of 6").
15
17
 
16
18
  ## Rules
17
19
  - Say where the code was sent in the `Field` hint ("Sent to •••• 1803"), and offer a resend link below.
20
+
21
+ Labels use `LocaleProvider`; `label` overrides the per-box noun. See the [Radix One-Time Password Field documentation](https://www.radix-ui.com/primitives/docs/components/one-time-password-field) for the underlying behavior.
@@ -1,9 +1,16 @@
1
1
  # PasswordInput
2
2
 
3
- A password field with a Show/Hide button, so people can check what they typed.
3
+ A styled Radix Password Toggle Field, so people can check what they typed. `unstable_PasswordToggleField` is a preview API supplied by the pinned `radix-ui@1.8.0`; dependency updates must verify its contract.
4
4
 
5
5
  ## Anatomy
6
- The `Input` box with a suffix button: 11px uppercase "Show" / "Hide" in `muted-foreground`, `primary-tint` on hover. The button sets `aria-pressed`.
6
+ Radix `Root`, `Input`, `Toggle` and `Slot` compose with the system's `Input` using `asChild`. The suffix button uses 11px uppercase "Show" / "Hide" in `muted-foreground` and `primary-tint` on hover. Localized text and `aria-pressed` are rendered from Radix's visibility value.
7
+
8
+ ## Behaviour
9
+ - Radix owns visibility and selection/focus restoration; the wrapper keeps no reveal state and adds no toggle or focus handlers.
10
+ - Pointer toggling returns focus to the input and preserves selection. Keyboard toggling keeps focus on the toggle.
11
+ - In the pinned preview primitive, a keyboard activation immediately after a pointer activation can still return focus to the input while Radix's pointer cleanup is pending.
12
+ - Form submission and reset restore the hidden password state through the primitive.
13
+ - Radix makes the toggle unavailable to assistive technology before hydration, then connects it to the input with `aria-controls`.
7
14
 
8
15
  ## Props
9
16
  - Any `Input` prop. `autoComplete` defaults to `current-password`; use `new-password` on sign-up and reset forms. `showLabel`, `hideLabel` for translations.
@@ -11,3 +18,5 @@ The `Input` box with a suffix button: 11px uppercase "Show" / "Hide" in `muted-f
11
18
 
12
19
  ## Rules
13
20
  - Never block paste. State the rules in the `Field` hint before people type ("At least 12 characters"), not after.
21
+
22
+ See the [Radix Password Toggle Field documentation](https://www.radix-ui.com/primitives/docs/components/password-toggle-field) for the underlying behavior.
@@ -7,13 +7,14 @@ A small non-modal panel attached to a button, for interactive content that doesn
7
7
  2. **Panel**: `surface-elevated`, 1px `border`, square, 0.75rem padding, at least 16rem wide (`width` to set it), with an optional title in Manrope 600. It sits 4px below the trigger, lined up with its start (or end, `align="end"`) edge, flips above when there is no room below and shrinks to the room it has; it rises 0.5rem as it fades in.
8
8
 
9
9
  ## Behaviour
10
- - Opening moves focus to the first control inside (not when it starts open with `defaultOpen`).
10
+ - Radix manages focus when the panel opens, including `defaultOpen`.
11
11
  - Esc closes and returns focus to the trigger. Clicking outside, or moving focus out of it, closes it.
12
12
  - The page stays usable behind it; nothing else is blocked.
13
13
 
14
14
  ## Props
15
- - `label`, `title`, `icon`, `variant`, `size`, `align`, `width`, `defaultOpen`.
16
- - `children`: content, or a function `({ close }) => content` so buttons inside can close it.
15
+ - `label`, `title`, `icon`, `variant`, `size`, `align`, `width`.
16
+ - Native Radix state and mode: `open`, `defaultOpen`, `onOpenChange`, `modal`.
17
+ - `children`: panel content. `close`: one focusable element rendered through Radix Close. The former render-function child is replaced by native Close composition; for more application-specific actions, control `open` through `onOpenChange`.
17
18
 
18
19
  ## Accessibility
19
20
  The trigger has `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; the panel is `role="dialog"`, labelled by its title (or the trigger's label), rendered in a portal on `document.body` with `data-state` and `data-side`.
@@ -21,3 +22,5 @@ The trigger has `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; t
21
22
  ## Rules
22
23
  - Use a `Dialog` when the content needs full attention or a decision before continuing.
23
24
  - Use a `Tooltip` for plain text with nothing to interact with.
25
+
26
+ [Radix Popover documentation](https://www.radix-ui.com/primitives/docs/components/popover) defines focus and dismissal behavior.
@@ -16,4 +16,6 @@ A bar showing how far a task has got, or that it is still running.
16
16
  - `value`, `max` (100), `label`, `showValue`, `valueText` ("9.2 of 10 GB"), `tone`, `aria-label` when there's no visible label.
17
17
 
18
18
  ## Accessibility
19
- Built on Radix Progress: `role="progressbar"` with `aria-valuenow/min/max` (left out when indeterminate; a value outside 0 to `max` is clamped) and the label wired with `aria-labelledby`. The track carries `data-state` (`loading`, `complete` or `indeterminate`).
19
+ Built on Radix Progress: `role="progressbar"` with `aria-valuenow/min/max` (the current value is omitted when indeterminate; min/max remain available) and the label wired with `aria-labelledby`. Values must be within `0..max`; Radix handles invalid values as indeterminate and reports invalid props. Radix supplies its percentage value label unless `valueText` is provided. The track carries `data-state` (`loading`, `complete` or `indeterminate`).
20
+
21
+ [Radix Progress documentation](https://www.radix-ui.com/primitives/docs/components/progress) defines the value and accessibility contract.
@@ -8,8 +8,9 @@ A labelled set of radio options sharing one name, rendered as a `fieldset` with
8
8
 
9
9
  ## Props
10
10
  - `label` (the legend), `name`, `options` (strings or `{ value, label, description, disabled }`).
11
- - Controlled with `value` and `onChange`, or uncontrolled with `defaultValue` (`onChange` is called in both cases).
12
- - `onChange` receives a change event whose `target` reads `value`, `name` and `checked` as a native radio would.
11
+ - Controlled with `value` and `onValueChange`, or uncontrolled with `defaultValue` (`onValueChange` is called in both cases).
12
+ - `onValueChange(value)` receives the selected string directly; Radix owns the controlled or uncontrolled state and keyboard interaction.
13
+ - Migration: replace `onChange={event => setValue(event.target.value)}` with `onValueChange={setValue}`.
13
14
  - `inline` for two to four short options.
14
15
 
15
16
  ## Keyboard
@@ -21,3 +22,5 @@ The `fieldset` has `role="radiogroup"`, named by the legend; each option is a `b
21
22
  ## Rules
22
23
  - Two to five options. More than that, use a `Select`.
23
24
  - Order options logically (by size, by frequency), not alphabetically by default.
25
+
26
+ See [Radix RadioGroup](https://www.radix-ui.com/primitives/docs/components/radio-group) for the public behavior and root props.