@vokality/design-system 2.0.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.
- package/CHANGELOG.md +28 -0
- package/README.md +49 -3
- package/dist/browser.d.ts +13 -0
- package/dist/browser.js +7 -0
- package/dist/charts/chart.d.ts +6 -5
- package/dist/charts/chart.js +44 -25
- package/dist/chat.d.ts +54 -0
- package/dist/chat.js +1 -0
- package/dist/components/Accordion/Accordion.js +1 -1
- package/dist/components/Alert/Alert.js +5 -2
- package/dist/components/AppShell/AppShell.js +10 -14
- package/dist/components/Avatar/Avatar.js +2 -2
- package/dist/components/AvatarGroup/AvatarGroup.js +2 -2
- package/dist/components/BarChart/BarChart.js +17 -15
- package/dist/components/Breadcrumbs/Breadcrumbs.js +6 -3
- package/dist/components/Calendar/Calendar.js +6 -5
- package/dist/components/Card/Card.js +2 -3
- package/dist/components/ChatInbox/ChatInbox.d.ts +11 -0
- package/dist/components/ChatInbox/ChatInbox.js +49 -0
- package/dist/components/ChatPanel/ChatPanel.d.ts +3 -0
- package/dist/components/ChatPanel/ChatPanel.js +13 -0
- package/dist/components/ChatPanel/composer.d.ts +5 -0
- package/dist/components/ChatPanel/composer.js +32 -0
- package/dist/components/ChatPanel/transcript.d.ts +13 -0
- package/dist/components/ChatPanel/transcript.js +39 -0
- package/dist/components/ChatWidget/ChatWidget.d.ts +12 -0
- package/dist/components/ChatWidget/ChatWidget.js +42 -0
- package/dist/components/Checkbox/Checkbox.d.ts +5 -10
- package/dist/components/Checkbox/Checkbox.js +5 -19
- package/dist/components/CodeBlock/CodeBlock.js +19 -5
- package/dist/components/Combobox/Combobox.js +22 -15
- package/dist/components/Combobox/ListPanel.js +20 -9
- package/dist/components/CommandPalette/CommandPalette.js +33 -14
- package/dist/components/ContextMenu/ContextMenu.d.ts +2 -2
- package/dist/components/ContextMenu/ContextMenu.js +5 -50
- package/dist/components/DatePicker/DatePicker.js +35 -29
- package/dist/components/DescriptionList/DescriptionList.js +1 -1
- package/dist/components/Dialog/Dialog.d.ts +24 -7
- package/dist/components/Dialog/Dialog.js +30 -41
- package/dist/components/Drawer/Drawer.d.ts +4 -2
- package/dist/components/EmptyState/EmptyState.js +2 -2
- package/dist/components/ErrorSummary/ErrorSummary.js +5 -3
- package/dist/components/FaqList/FaqList.js +1 -1
- package/dist/components/Field/Field.js +2 -2
- package/dist/components/FileUpload/FileUpload.js +17 -9
- package/dist/components/Grid/Grid.d.ts +5 -5
- package/dist/components/Grid/Grid.js +1 -1
- package/dist/components/Heading/Heading.js +2 -1
- package/dist/components/Icon/Icon.js +4 -2
- package/dist/components/Inline/Inline.d.ts +7 -7
- package/dist/components/LineChart/LineChart.js +17 -15
- package/dist/components/LinkProvider/LinkProvider.d.ts +1 -1
- package/dist/components/LinkProvider/LinkProvider.js +6 -2
- package/dist/components/List/List.js +1 -1
- package/dist/components/MediaCard/MediaCard.js +2 -2
- package/dist/components/Menu/Menu.js +6 -43
- package/dist/components/Menu/entries.d.ts +1 -30
- package/dist/components/Menu/entries.js +16 -100
- package/dist/components/MultiSelect/MultiSelect.js +43 -34
- package/dist/components/NumberInput/NumberInput.js +17 -18
- package/dist/components/OtpInput/OtpInput.d.ts +1 -1
- package/dist/components/OtpInput/OtpInput.js +10 -67
- package/dist/components/PageHeader/PageHeader.js +2 -2
- package/dist/components/Pagination/Pagination.js +3 -1
- package/dist/components/PasswordInput/PasswordInput.d.ts +1 -1
- package/dist/components/PasswordInput/PasswordInput.js +9 -4
- package/dist/components/Popover/Popover.d.ts +6 -7
- package/dist/components/Popover/Popover.js +2 -19
- package/dist/components/Progress/Progress.d.ts +1 -1
- package/dist/components/Progress/Progress.js +7 -11
- package/dist/components/Radio/Radio.d.ts +4 -2
- package/dist/components/RadioGroup/RadioGroup.d.ts +5 -12
- package/dist/components/RadioGroup/RadioGroup.js +6 -33
- package/dist/components/RichTextEditor/RichTextEditor.d.ts +63 -0
- package/dist/components/RichTextEditor/RichTextEditor.js +175 -0
- package/dist/components/RichTextEditor/toolbar.d.ts +15 -0
- package/dist/components/RichTextEditor/toolbar.js +142 -0
- package/dist/components/RichTextEditor/uploads.d.ts +41 -0
- package/dist/components/RichTextEditor/uploads.js +124 -0
- package/dist/components/SearchInput/SearchInput.js +4 -2
- package/dist/components/SectionHeader/SectionHeader.js +1 -3
- package/dist/components/SegmentedControl/SegmentedControl.js +2 -12
- package/dist/components/Select/Select.d.ts +15 -16
- package/dist/components/Select/Select.js +11 -252
- package/dist/components/Slider/Slider.js +11 -21
- package/dist/components/Sparkline/Sparkline.js +8 -3
- package/dist/components/Spinner/Spinner.js +5 -2
- package/dist/components/Stack/Stack.d.ts +5 -5
- package/dist/components/Stat/Stat.js +6 -3
- package/dist/components/Steps/Steps.js +6 -3
- package/dist/components/Switch/Switch.d.ts +7 -7
- package/dist/components/Switch/Switch.js +4 -10
- package/dist/components/Table/Table.js +38 -19
- package/dist/components/Tabs/Tabs.js +2 -22
- package/dist/components/Tag/Tag.js +3 -1
- package/dist/components/Text/Text.d.ts +1 -1
- package/dist/components/TileGrid/TileGrid.js +1 -1
- package/dist/components/TimePicker/TimePicker.js +35 -33
- package/dist/components/Timeline/Timeline.js +5 -4
- package/dist/components/Toaster/Toaster.js +21 -17
- package/dist/components/Tooltip/Tooltip.d.ts +6 -6
- package/dist/components/Tooltip/Tooltip.js +3 -17
- package/dist/components/TreeView/TreeView.js +15 -12
- package/dist/components.css +179 -8
- package/dist/hooks/useTheme.js +6 -6
- package/dist/icons/message-circle.svg +1 -0
- package/dist/internal/CharCount.js +3 -1
- package/dist/internal/choice.d.ts +10 -48
- package/dist/internal/choice.js +8 -96
- package/dist/internal/options.d.ts +10 -5
- package/dist/internal/options.js +25 -11
- package/dist/internal/status.d.ts +3 -2
- package/dist/internal/status.js +10 -2
- package/dist/internal/useScrollActive.js +2 -2
- package/dist/internal/useToday.d.ts +3 -0
- package/dist/internal/useToday.js +42 -0
- package/dist/lib/dates.js +25 -15
- package/dist/lib/format.js +11 -8
- package/dist/lib/icons.d.ts +5 -0
- package/dist/lib/icons.js +2 -0
- package/dist/lib/math.js +17 -5
- package/dist/lib/rich-text.d.ts +13 -0
- package/dist/lib/rich-text.js +62 -0
- package/dist/lib/space.d.ts +1 -2
- package/dist/lib/space.js +4 -1
- package/dist/lib/text.js +1 -1
- package/dist/lib/theme.js +1 -1
- package/dist/localization.d.ts +166 -0
- package/dist/localization.js +142 -0
- package/dist/vokality.css +179 -8
- package/dist/vokality.iife.js +35986 -9685
- package/docs/brand.md +6 -3
- package/docs/components/AppShell/README.md +1 -1
- package/docs/components/BarChart/README.md +1 -0
- package/docs/components/ChatInbox/README.md +41 -0
- package/docs/components/ChatWidget/README.md +47 -0
- package/docs/components/Checkbox/README.md +7 -3
- package/docs/components/ContextMenu/README.md +7 -3
- package/docs/components/Dialog/README.md +9 -4
- package/docs/components/Drawer/README.md +1 -1
- package/docs/components/Field/README.md +1 -1
- package/docs/components/Fieldset/README.md +2 -2
- package/docs/components/LineChart/README.md +1 -0
- package/docs/components/LocaleProvider/README.md +48 -0
- package/docs/components/Menu/README.md +13 -8
- package/docs/components/OtpInput/README.md +9 -5
- package/docs/components/PasswordInput/README.md +11 -2
- package/docs/components/Popover/README.md +6 -3
- package/docs/components/Progress/README.md +3 -1
- package/docs/components/RadioGroup/README.md +5 -2
- package/docs/components/RichTextEditor/README.md +84 -0
- package/docs/components/SegmentedControl/README.md +2 -0
- package/docs/components/Select/README.md +13 -17
- package/docs/components/Skeleton/README.md +1 -1
- package/docs/components/Slider/README.md +4 -2
- package/docs/components/Steps/README.md +1 -1
- package/docs/components/Switch/README.md +5 -2
- package/docs/components/Tabs/README.md +4 -2
- package/docs/components/Toaster/README.md +3 -1
- package/docs/components/Tooltip/README.md +5 -3
- 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` |
|
|
@@ -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.
|
|
@@ -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
|
-
-
|
|
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
|
|
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`.
|
|
@@ -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
|
|
@@ -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`, `
|
|
24
|
-
- `
|
|
25
|
-
-
|
|
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
|
-
|
|
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
|
-
-
|
|
7
|
-
-
|
|
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
|
-
-
|
|
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
|
|
16
|
-
- `role="alertdialog"`
|
|
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`, `
|
|
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
|
|
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;
|
|
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}
|
|
21
|
-
<Checkbox label="Manage invitations" checked={invite}
|
|
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
|
|
|
@@ -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.
|
|
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
|
-
| ↑
|
|
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 |
|
|
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 |
|
|
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 `
|
|
33
|
-
- `{ type: 'radio', label, checked, onSelect }`: a `
|
|
34
|
-
- `{ label, items: [...] }`: a submenu with a chevron
|
|
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
|
-
|
|
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)
|
|
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
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
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
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
|
16
|
-
-
|
|
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` (
|
|
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 `
|
|
12
|
-
- `
|
|
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.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# RichTextEditor
|
|
2
|
+
|
|
3
|
+
A real rich-text surface powered by ProseMirror. The value is a CommonMark Markdown string, including formatting, Unicode emoji and durable attachment links. Import the editor from its own entrypoint so applications that do not edit rich text do not bundle the editor engine.
|
|
4
|
+
|
|
5
|
+
```tsx
|
|
6
|
+
import { Field } from "@vokality/design-system";
|
|
7
|
+
import { RichTextEditor } from "@vokality/design-system/rich-text";
|
|
8
|
+
import type { RichTextAttachment } from "@vokality/design-system/rich-text";
|
|
9
|
+
|
|
10
|
+
async function uploadAttachment(file: File, { signal }: { signal: AbortSignal }): Promise<RichTextAttachment> {
|
|
11
|
+
const body = new FormData();
|
|
12
|
+
body.append("file", file);
|
|
13
|
+
const response = await fetch("/api/attachments", { method: "POST", body, signal });
|
|
14
|
+
if (!response.ok) throw new Error("Upload failed");
|
|
15
|
+
// Validate your endpoint's unknown response before returning clean data.
|
|
16
|
+
const result: unknown = await response.json();
|
|
17
|
+
if (typeof result !== "object" || result === null || !("url" in result) ||
|
|
18
|
+
!("name" in result) || typeof result.url !== "string" || typeof result.name !== "string") {
|
|
19
|
+
throw new TypeError("Invalid attachment response");
|
|
20
|
+
}
|
|
21
|
+
return { url: result.url, name: result.name };
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
<Field label="Notes" hint="Formatting and attachments are saved as Markdown.">
|
|
25
|
+
<RichTextEditor
|
|
26
|
+
name="notes"
|
|
27
|
+
defaultValue="## Project notes\n\nStart writing."
|
|
28
|
+
onUploadAttachment={uploadAttachment}
|
|
29
|
+
accept="image/*,.pdf"
|
|
30
|
+
maxFileSize={10 * 1024 * 1024}
|
|
31
|
+
/>
|
|
32
|
+
</Field>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Anatomy
|
|
36
|
+
|
|
37
|
+
- Formatting toolbar: paragraph, headings 1–3, bold, italic, inline code, code block, bullet/ordered lists, blockquote, links, emoji, optional attachments, undo and redo.
|
|
38
|
+
- `toolbar="minimal"` places the writing field first, followed by a small action row: Aa, emoji, and attachments when uploads are configured. Aa opens a native Radix disclosure with bold, italic, link and bullet-list controls. The default `toolbar="full"` retains the complete toolbar above the field. Both layouts use the same editor commands and Markdown model.
|
|
39
|
+
- Multiline editable textbox: its `id` and forwarded `HTMLDivElement` ref point to the actual editor. `Field` wires label, hint, error and invalid state onto it.
|
|
40
|
+
- A native form field carries the Markdown value. Required validation prevents an empty submission and focuses the visible editor. A disabled editor is excluded from form data; a read-only editor remains included.
|
|
41
|
+
- Attachment progress/error rows provide cancellation, retry and removal. Uploaded files become Markdown links in separate paragraphs at the document's end, so a late response never replaces a later selection.
|
|
42
|
+
|
|
43
|
+
## Value and supported content
|
|
44
|
+
|
|
45
|
+
Use `value` with `onChange` for a controlled editor, or `defaultValue` for an uncontrolled one. Changes emit canonical CommonMark; whitespace, list markers and equivalent Markdown syntax may normalize. Selection changes do not emit. External controlled values replace the document and reset edit history; normal parent echoes preserve selection and history. Native form reset restores the uncontrolled default and cancels pending uploads.
|
|
46
|
+
|
|
47
|
+
The parser and serializer preserve the CommonMark document model: paragraphs, six heading levels, bold, italic, inline/fenced code, nested lists, blockquotes, hard breaks, horizontal rules, links and inline images. The toolbar offers the first three heading levels. Unicode emoji remain ordinary text and survive copying and Markdown reloads. The default picker is a small searchable set; `emojiOptions` supplies other Unicode sequences with localized accessible labels. Operating-system emoji input and pasted emoji also work.
|
|
48
|
+
|
|
49
|
+
Raw HTML is treated as text. GFM tables, task lists, mentions, embeds and arbitrary HTML are outside this content contract; this is not a general HTML editor. Render saved Markdown using a trusted CommonMark renderer with raw HTML disabled and the same URL policy. `Prose` provides the system's reading styles.
|
|
50
|
+
|
|
51
|
+
## Attachments
|
|
52
|
+
|
|
53
|
+
`onUploadAttachment(file, { signal })` enables the attach button. The application owns authentication, endpoint validation, storage, upload progress transport and deletion of server assets. It returns `{ name, url }` after upload. The editor validates this result at runtime, then inserts its escaped name as a Markdown link.
|
|
54
|
+
|
|
55
|
+
`accept` filters the file chooser; `maxFileSize` rejects oversized files before upload. The server must enforce its own limits. Multiple files upload independently. Failed attempts retain their file for retry. Canceling, unmounting, resetting or locking the editor aborts pending attempts; late results are ignored even if the callback disregards the signal. Removing an uploaded attachment removes its document reference, without deleting the server file. Editing/removing attachment links directly is ordinary document editing; undo can restore them.
|
|
56
|
+
|
|
57
|
+
`onUploadPendingChange(pending)` observes the existing upload attempt lifecycle, so a surrounding send action can wait for attachment links. It reports when attempts start, settle or abort; canceling or unmounting releases pending state. It adds no upload tracking or transport.
|
|
58
|
+
|
|
59
|
+
Links accept HTTP(S), mailto, tel and relative/fragment URLs. Attachment and image URLs accept HTTP(S) and relative URLs. Script/data/blob URLs, protocol-relative URLs, backslashes and control characters are rejected. The same document policy guards pasted content before it reaches the view. Editing a link never navigates the application.
|
|
60
|
+
|
|
61
|
+
## States and tokens
|
|
62
|
+
|
|
63
|
+
- Default: `card` fill, `input-border`, body type from `control-font-size`.
|
|
64
|
+
- Focus: `primary` border with a 2px `ring` outline on the editor or toolbar action.
|
|
65
|
+
- Pressed formatting: `primary`, `primary-tint`, `primary-line`, plus `aria-pressed`.
|
|
66
|
+
- Invalid: `danger` border; pair with `Field error` for an explanation.
|
|
67
|
+
- Disabled: dashed border and unavailable toolbar; `readOnly` retains selectable content and hides the toolbar.
|
|
68
|
+
- Forced colors: selected tools use system `Highlight`/`HighlightText`. There are no animations. Touch actions meet the shared control height.
|
|
69
|
+
|
|
70
|
+
## Accessibility and localization
|
|
71
|
+
|
|
72
|
+
The toolbar uses Radix's roving focus: Tab enters/exits once, Left/Right move between available tools, and Home/End jump to the ends. Mouse formatting preserves the editor selection. Bold/italic have standard Mod+B/Mod+I shortcuts; Mod+Z and Shift+Mod+Z undo/redo. Enter splits list items; Mod+[ and Mod+] outdent/indent; Shift+Enter adds a hard break. Link and emoji panels are Radix popovers with labeled controls and Escape handling. Emoji options have searchable text labels. Upload feedback has a polite live region, and every action names its file.
|
|
73
|
+
|
|
74
|
+
All built-in labels, emoji names and upload feedback use `LocaleProvider`, including changes while the editor is mounted. `emojiOptions` labels and app-supplied placeholders use the application's language.
|
|
75
|
+
|
|
76
|
+
The editor initializes in an effect, so server rendering and hydration do not access browser globals. Its form value and accessible textbox exist in the initial HTML; the editable document mounts on the client.
|
|
77
|
+
|
|
78
|
+
## Props
|
|
79
|
+
|
|
80
|
+
`value`, `defaultValue`, `onChange`, `name`, `id`, `disabled`, `readOnly`, `toolbar`, `required`, `placeholder`, `className`, `onBlur`, `onUploadAttachment`, `accept`, `maxFileSize`, `emojiOptions`, `onUploadError`, `onUploadPendingChange`, and `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-invalid`. Types and prop documentation ship through the direct `rich-text` entrypoint.
|
|
81
|
+
|
|
82
|
+
## Engine references
|
|
83
|
+
|
|
84
|
+
The [official Markdown module](https://code.haverbeke.berlin/prosemirror/prosemirror-markdown) defines the CommonMark schema, parser and serializer. The [official ProseMirror guide](https://prosemirror.net/docs/guide/) explains immutable editor state, transactions and the view; the [Radix toolbar documentation](https://www.radix-ui.com/primitives/docs/components/toolbar) documents the keyboard model.
|
|
@@ -17,3 +17,5 @@ Built on Radix RadioGroup: `role="radiogroup"` (named by `label`) with `radio` b
|
|
|
17
17
|
## Rules
|
|
18
18
|
- The choice applies immediately. For a choice inside a form, use `RadioGroup`.
|
|
19
19
|
- Keep labels to one word where you can.
|
|
20
|
+
|
|
21
|
+
Radix owns selection and keyboard interaction. Pass `defaultValue` explicitly when an initial selection is needed; the wrapper does not choose the first option.
|