@korzun/design 0.0.2 → 0.0.4

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 (61) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +11 -1
  3. package/dist/component/index.d.ts +1 -1
  4. package/dist/component/index.d.ts.map +1 -1
  5. package/dist/component/index.js.map +1 -1
  6. package/dist/component/tag/index.d.ts +5 -2
  7. package/dist/component/tag/index.d.ts.map +1 -1
  8. package/dist/component/tag/index.js +2 -2
  9. package/dist/component/tag/index.js.map +1 -1
  10. package/dist/component/tag/style.d.ts +2 -1
  11. package/dist/component/tag/style.d.ts.map +1 -1
  12. package/dist/component/tag/style.js +21 -7
  13. package/dist/component/tag/style.js.map +1 -1
  14. package/dist/theme/theme.d.ts +5 -0
  15. package/dist/theme/theme.d.ts.map +1 -1
  16. package/dist/theme/theme.js +13 -1
  17. package/dist/theme/theme.js.map +1 -1
  18. package/docs/component/card-divider.md +67 -0
  19. package/docs/component/card-row.md +58 -0
  20. package/docs/component/card.md +82 -0
  21. package/docs/component/collapsible-section.md +57 -0
  22. package/docs/component/empty-state.md +49 -0
  23. package/docs/component/meta-line.md +60 -0
  24. package/docs/component/metadata-list.md +60 -0
  25. package/docs/component/nav-desktop.md +62 -0
  26. package/docs/component/nav-mobile.md +82 -0
  27. package/docs/component/page.md +81 -0
  28. package/docs/component/progress-indicator.md +53 -0
  29. package/docs/component/tag.md +69 -0
  30. package/docs/component/theme-setting.md +58 -0
  31. package/docs/component/top-fade.md +60 -0
  32. package/docs/control/back-button.md +55 -0
  33. package/docs/control/button.md +78 -0
  34. package/docs/control/chips-input.md +77 -0
  35. package/docs/control/confirm-modal.md +68 -0
  36. package/docs/control/date-time-input.md +56 -0
  37. package/docs/control/field-list.md +66 -0
  38. package/docs/control/number-input.md +62 -0
  39. package/docs/control/page-actions-bar.md +64 -0
  40. package/docs/control/page-actions-menu.md +65 -0
  41. package/docs/control/page-footer-actions.md +69 -0
  42. package/docs/control/popover.md +74 -0
  43. package/docs/control/segmented-control.md +73 -0
  44. package/docs/control/select.md +86 -0
  45. package/docs/control/switch.md +73 -0
  46. package/docs/control/text-area.md +52 -0
  47. package/docs/control/text-input.md +73 -0
  48. package/docs/control/use-modal-dialog.md +76 -0
  49. package/docs/corners.md +68 -0
  50. package/docs/hooks.md +104 -0
  51. package/docs/icon.md +102 -0
  52. package/docs/patterns.md +116 -0
  53. package/docs/philosophy.md +91 -0
  54. package/docs/theme.md +96 -0
  55. package/docs/toast.md +85 -0
  56. package/docs/tokens.md +95 -0
  57. package/package.json +7 -1
  58. package/src/component/index.ts +1 -1
  59. package/src/component/tag/index.tsx +7 -2
  60. package/src/component/tag/style.ts +27 -7
  61. package/src/theme/theme.ts +16 -1
@@ -0,0 +1,64 @@
1
+ # PageActionsBar
2
+
3
+ `import { PageActionsBar } from '@korzun/design/control'`
4
+
5
+ The **desktop** page-actions row: `primary` items render as inline Buttons and
6
+ the rest collapse into a "More…" overflow menu. It is hidden at 640px and
7
+ below, where `PageActionsMenu` shows the same items. Usually you don't render
8
+ it yourself: pass `headerActions` (and `actionsLabel`) to `Page`, which puts it
9
+ in the header row.
10
+
11
+ Use something else for: mobile (`PageActionsMenu`), bottom-of-page form actions
12
+ (`PageFooterActions`), a one-off button inside a card (`Button`).
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ |---|---|---|---|
18
+ | `items` | `PageActionItem[]` | (required) | See [page-actions-menu](page-actions-menu.md#pageactionitem) for the item shape. |
19
+ | `actionsLabel` | `string` | `'More…'` | Visible text and accessible name of the overflow trigger (default accessible name: "More actions"). Pass `'Actions'` when every item is overflow. |
20
+
21
+ No `className`.
22
+
23
+ ## How items are placed
24
+
25
+ - `primary: true` → an inline `Button` (`type="default"`, default
26
+ `radius="background"`, because the bar sits on the page background).
27
+ `align: 'leading'` puts it at the left; anything else is trailing, at the
28
+ right. `danger` and `disabled` apply.
29
+ - Not primary → the overflow menu (solid card surface, `radius.md`, items
30
+ `radius.sm`), opened by the trigger at the far right. `separatorBefore`
31
+ draws a divider there.
32
+ - No overflow items → no trigger.
33
+ - **`intentProps` only work on overflow items**; primary Buttons drop them.
34
+ - Items are keyed by `label`, so labels must be unique.
35
+
36
+ ## Behaviour to know
37
+
38
+ The menu closes on item select (before `onClick` runs), Escape, or an outside
39
+ mousedown. The trigger is a native `<button>` with `aria-haspopup="menu"` and
40
+ `aria-expanded`. No arrow-key navigation in the menu.
41
+
42
+ ## Example
43
+
44
+ ```tsx
45
+ <Page
46
+ headerActions={[
47
+ { label: 'Read', onClick: read, primary: true, align: 'leading' },
48
+ { label: 'Edit', onClick: edit, primary: true },
49
+ { label: 'Download', onClick: download },
50
+ { label: 'Delete', onClick: remove, danger: true, separatorBefore: true },
51
+ ]}
52
+ >
53
+ …
54
+ </Page>
55
+
56
+ // Every action in the menu, trigger labelled "Actions".
57
+ <Page headerActions={uploadActions} actionsLabel="Actions">…</Page>
58
+ ```
59
+
60
+ ## Do / don't
61
+
62
+ - Do mark at most two or three items `primary`; the rest belong in the menu.
63
+ - Do use `Page headerActions` so the mobile menu gets the same items.
64
+ - Don't rely on `intentProps` for a primary item.
@@ -0,0 +1,65 @@
1
+ # PageActionsMenu
2
+
3
+ `import { PageActionsMenu, type PageActionItem, type PageActionIntentProps } from '@korzun/design/control'`
4
+
5
+ The **mobile** page-actions control: a round glass "More actions" button (⋯)
6
+ that opens a glass menu listing every action. It is hidden at 641px and up,
7
+ where `PageActionsBar` takes over with the same items. Usually you don't render
8
+ it yourself: pass `headerActions` to `Page`, which renders both.
9
+
10
+ Use something else for: desktop header actions (`PageActionsBar`), bottom-of-
11
+ page form actions (`PageFooterActions`), a single inline action (`Button`).
12
+
13
+ ## Props
14
+
15
+ | Prop | Type | Default | Notes |
16
+ |---|---|---|---|
17
+ | `items` | `PageActionItem[]` | (required) | All of them appear in the menu, in order. |
18
+
19
+ No `className`, no label prop (the trigger is always "More actions").
20
+
21
+ ## PageActionItem
22
+
23
+ Shared with `PageActionsBar`, so one array drives both.
24
+
25
+ | Field | Type | Notes |
26
+ |---|---|---|
27
+ | `label` | `string` | Menu text. **Must be unique**: it is the React key. |
28
+ | `onClick` | `() => void` | Receives no event. The menu closes first. |
29
+ | `danger` | `boolean` | Red text. Styling only. |
30
+ | `disabled` | `boolean` | |
31
+ | `separatorBefore` | `boolean` | Divider above this item (ignored on the first). `danger` does not add one. |
32
+ | `intentProps` | `{ onMouseEnter, onFocus, onTouchStart }` | Spread onto the menu item, e.g. to prefetch. |
33
+ | `primary` | `boolean` | **Ignored here.** Only `PageActionsBar` uses it. |
34
+ | `align` | `'leading' \| 'trailing'` | **Ignored here.** Only `PageActionsBar` uses it. |
35
+
36
+ ## Behaviour to know
37
+
38
+ - Closes on item select, Escape, or a mousedown outside. No arrow-key
39
+ navigation; Tab moves through the items.
40
+ - The menu is a floating layer (`radius.md`, glass, items `radius.sm`),
41
+ absolutely positioned under the trigger, right-aligned.
42
+ - It doesn't place itself: `Page` puts it in the sticky controls row
43
+ (`margin-left: auto` keeps it at the trailing end, with or without a
44
+ `BackButton`).
45
+
46
+ ## Example
47
+
48
+ ```tsx
49
+ const actions: PageActionItem[] = [
50
+ { label: 'Edit', onClick: edit, primary: true },
51
+ { label: 'Read', onClick: read, primary: true, align: 'leading' },
52
+ { label: 'Download', onClick: download, intentProps: prefetchDownload },
53
+ { label: 'Delete', onClick: () => setConfirming(true), danger: true, separatorBefore: true },
54
+ ];
55
+
56
+ // Preferred: Page renders PageActionsMenu (mobile) and PageActionsBar (desktop).
57
+ <Page back="/library" headerActions={actions}>…</Page>
58
+ ```
59
+
60
+ ## Do / don't
61
+
62
+ - Do pass the same `items` you give `PageActionsBar` (or just use `Page`).
63
+ - Do put destructive items last with `separatorBefore`.
64
+ - Don't render it on its own and expect it on desktop; it is hidden there.
65
+ - Don't give two items the same `label`; they collide as React keys.
@@ -0,0 +1,69 @@
1
+ # PageFooterActions
2
+
3
+ `import { PageFooterActions, type FooterAction } from '@korzun/design/control'`
4
+
5
+ A row of Buttons for the bottom of a page, typically Cancel / Save for a form
6
+ that spans several cards. Leading items sit left, trailing items right. It is
7
+ a plain flex row (not sticky, shown at every width). `Page` renders it after
8
+ its children when you pass `footerActions`; you can also render it directly
9
+ after your form.
10
+
11
+ Use something else for: header actions (`PageActionsBar` / `PageActionsMenu`
12
+ via `Page headerActions`), a Card's own submit (`Button` in the Card `footer`),
13
+ modal buttons (`Button radius="modal"`).
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ |---|---|---|---|
19
+ | `items` | `FooterAction[]` | (required) | Rendered in order within each side. |
20
+
21
+ No `className`.
22
+
23
+ ## FooterAction
24
+
25
+ | Field | Type | Notes |
26
+ |---|---|---|
27
+ | `label` | `string` | Button text; may change between renders (`Save` → `Saving…`) without remounting. |
28
+ | `onClick` | `() => void` | **Required even for a submit item, and ignored there** (the form submits). Pass `() => {}`. Receives no event. |
29
+ | `emphasis` | `boolean` | `type="primary"`; otherwise `type="default"`. |
30
+ | `danger` | `boolean` | Red treatment. |
31
+ | `disabled` | `boolean` | |
32
+ | `loading` | `boolean` | Spinner; blocks clicks. |
33
+ | `align` | `'leading' \| 'trailing'` | Default trailing. |
34
+ | `submit` | `boolean` | Native submit button. |
35
+ | `form` | `string` | Id of the `<form>` to submit; needed because the row sits outside the form. |
36
+
37
+ Buttons use the default `radius` (`background`, `radius.lg`), correct because
38
+ the row sits on the page background below the cards; see
39
+ [corners](../corners.md). Don't put PageFooterActions inside a `Card`.
40
+
41
+ ## Example
42
+
43
+ ```tsx
44
+ <form id={formId} action={save}>
45
+ <Card title="Details">…</Card>
46
+ <Card title="Identifiers">…</Card>
47
+ </form>
48
+ <PageFooterActions
49
+ items={[
50
+ { label: 'Cancel', onClick: () => navigate(path.book(book.id)), disabled: isPending },
51
+ {
52
+ label: isPending ? 'Saving…' : 'Save',
53
+ onClick: () => {},
54
+ submit: true,
55
+ form: formId,
56
+ emphasis: true,
57
+ loading: isPending,
58
+ disabled: hasInvalidFields,
59
+ },
60
+ ]}
61
+ />
62
+ ```
63
+
64
+ ## Do / don't
65
+
66
+ - Do give exactly one item `emphasis`.
67
+ - Do pair `submit` with `form` when the row is outside the `<form>`.
68
+ - Don't put a destructive action beside Save without `danger` and
69
+ `align: 'leading'`.
@@ -0,0 +1,74 @@
1
+ # Popover
2
+
3
+ `import { Popover } from '@korzun/design/control'`
4
+
5
+ A positioning primitive: renders `children` in a portal on `document.body`,
6
+ `position: fixed` directly beneath an anchor element, so a dropdown can escape
7
+ ancestors that clip overflow (rounded cards). It paints **nothing** itself: no
8
+ background, border, shadow, or radius. `Select` and `ChipsInput` build their
9
+ dropdowns on it.
10
+
11
+ Use something else for: a modal (`useModalDialog`), page action menus
12
+ (`PageActionsMenu`, `PageActionsBar`), choosing from a list (`Select`).
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ |---|---|---|---|
18
+ | `anchorRef` | `RefObject<HTMLElement \| null>` | (required) | Element to sit under. Left edges align. |
19
+ | `open` | `boolean` | (required) | When `false`, renders nothing. Fully controlled. |
20
+ | `children` | `ReactNode` | (required) | Your surface: give it its own background, border, radius. |
21
+ | `gap` | `number` | `4` | Pixels between the anchor's bottom and the popover. |
22
+ | `matchWidth` | `boolean` | `true` | Width = anchor width. `false` lets content size itself. |
23
+ | `onClose` | `() => void` | | Called on a mousedown outside both anchor and content. Omit to opt out. Receives no event. |
24
+ | `className` | `string` | | Applied to the fixed wrapper. Override with `'&&'`, never `!important`. |
25
+
26
+ ## Behaviour to know
27
+
28
+ - **No Escape handling and no focus management.** Add your own keydown handler
29
+ if Escape should close it.
30
+ - Always opens below the anchor; it does not flip up or clamp to the viewport.
31
+ It repositions on window resize and on any scroll (capture phase).
32
+ - First paint is skipped until the anchor is measured, so it never flashes at 0,0.
33
+ - z-index is `theme.zIndex.sticky` (1000). Inside a modal `<dialog>` opened with
34
+ `showModal()`, a body portal sits outside the dialog's top layer, so it is
35
+ likely hidden behind the dialog and inert. Test before using it there.
36
+ - Clicking the anchor does not count as "outside", so a toggle button on the
37
+ anchor works without racing `onClose`.
38
+
39
+ ## Styling the surface
40
+
41
+ A popover is a floating layer: corners `radius.md` with `shadow.hoverLift` (or
42
+ `recipe.glass`), and the items inside it `radius.sm`. See
43
+ [corners](../corners.md).
44
+
45
+ ```ts
46
+ menu: {
47
+ backgroundColor: theme.color.bg.card,
48
+ border: `1px solid ${theme.color.border.strong}`,
49
+ borderRadius: theme.radius.md,
50
+ boxShadow: theme.shadow.hoverLift,
51
+ padding: theme.space.xs,
52
+ },
53
+ item: { borderRadius: theme.radius.sm, padding: theme.space.md },
54
+ ```
55
+
56
+ ## Example
57
+
58
+ ```tsx
59
+ const anchor = useRef<HTMLDivElement>(null);
60
+ const [open, setOpen] = useState(false);
61
+
62
+ <div ref={anchor} className={styles.anchor}>
63
+ <Button onClick={() => setOpen((o) => !o)}>Filters</Button>
64
+ </div>
65
+ <Popover anchorRef={anchor} open={open} matchWidth={false} onClose={() => setOpen(false)}>
66
+ <div className={styles.menu}>…</div>
67
+ </Popover>
68
+ ```
69
+
70
+ ## Do / don't
71
+
72
+ - Do wrap a `Button` in a `<div ref>` to anchor it; `Button` takes no ref.
73
+ - Do give the content its own surface and radius; the wrapper is transparent.
74
+ - Don't expect it to close on Escape or on selection; that is your code.
@@ -0,0 +1,73 @@
1
+ # SegmentedControl
2
+
3
+ `import { SegmentedControl } from '@korzun/design/control'`
4
+
5
+ A row of equal-width radio segments in a track, with a lens that slides to the
6
+ checked one. Options can be text, or an icon over a small caption. Optionally
7
+ clearable, and read-only when `onChange` is omitted. Generic over the value
8
+ type: `V extends string`.
9
+
10
+ Use something else for: many options or long labels (`Select`), on/off
11
+ (`Switch`), actions (`Button`).
12
+
13
+ ## Props
14
+
15
+ | Prop | Type | Default | Notes |
16
+ |---|---|---|---|
17
+ | `label` | `string` | (required) | The group's accessible name (`aria-label`). **Not rendered visibly**; put a visible label beside it yourself. |
18
+ | `options` | `ReadonlyArray<{ value: V; label: string; Icon?: (props: IconProps) => JSX.Element }>` | (required) | `label` is each segment's accessible name. `Icon` is a component (`Icon: SearchIcon`). |
19
+ | `value` | `V \| null` | (required) | `null`, or a value no option has, checks nothing and draws no lens. |
20
+ | `onChange` | `(value: V) => void`, or `(value: V \| null) => void` with `clearable` | | **Omit for read-only**: segments get `aria-disabled` and ignore clicks and keys. |
21
+ | `clearable` | `boolean` | `false` | Clicking the checked segment, Backspace or Delete call `onChange(null)`. Without it, clicking the checked segment does nothing. |
22
+ | `showLabels` | `boolean` | `true` | `false` hides captions, **only for options with an `Icon`**; text-only options always show their label. |
23
+ | `surface` | `'card' \| 'row'` | `'card'` | `card`: paints its own `bg.track` rail. `row`: transparent, for a control sitting inside a shaded field row. |
24
+
25
+ No `className`, no `name` (not a form field). The segment type is not exported;
26
+ declare options `as const` or type them inline.
27
+
28
+ ## Keyboard
29
+
30
+ On the group: ArrowRight/ArrowUp and ArrowLeft/ArrowDown step one option and do
31
+ not wrap; Home/End jump to the ends; digits 1–9 pick that option; Backspace and
32
+ Delete clear when `clearable`. Modified keys (Ctrl/Cmd/Alt) are left alone.
33
+
34
+ ## Choosing a surface
35
+
36
+ The track and lens are always `radius.md` (see [corners](../corners.md)), so the
37
+ control belongs inside a card or modal.
38
+
39
+ - Directly in a `Card` body: omit `surface` (`'card'`).
40
+ - Inside a shaded `bg.cardHeader` row you built (label left, control right):
41
+ `surface="row"`, so the row itself is the track and the lens is flush with it.
42
+
43
+ ## Examples
44
+
45
+ ```tsx
46
+ const SORTS = [
47
+ { value: 'title', label: 'Title' },
48
+ { value: 'author', label: 'Author' },
49
+ { value: 'added', label: 'Added' },
50
+ ] as const;
51
+
52
+ <SegmentedControl label="Sort by" options={SORTS} value={sort} onChange={setSort} />
53
+
54
+ // Icon segments, clearable, captions hidden; onChange receives null on clear.
55
+ <SegmentedControl
56
+ label="Rating"
57
+ options={RATINGS /* { value: '1', label: 'Bad', Icon: ThumbDownIcon }, … */}
58
+ value={rating}
59
+ onChange={setRating}
60
+ clearable
61
+ showLabels={false}
62
+ />
63
+
64
+ // Read-only display.
65
+ <SegmentedControl label="Rating" options={RATINGS} value={rating} />
66
+ ```
67
+
68
+ ## Do / don't
69
+
70
+ - Do keep it to a handful of short options; segments are equal columns.
71
+ - Do pass `clearable` whenever `null` is a valid answer, or the user can never
72
+ get back to it.
73
+ - Don't pass `onChange={() => {}}` to show a value; omit `onChange` for read-only.
@@ -0,0 +1,86 @@
1
+ # Select
2
+
3
+ `import { Select, type SelectOption, type SelectProps } from '@korzun/design/control'`
4
+
5
+ A single-value dropdown with type-to-search (on by default), an optional "Add:
6
+ …" entry for new values, a clear button, and a loading state. The dropdown is a
7
+ `Popover`, so it escapes clipping cards.
8
+
9
+ Use something else for: 2–5 options that fit in one row (`SegmentedControl`),
10
+ several values (`ChipsInput`), on/off (`Switch`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `name` | `string` | (required) | Only lands on the search box while it is open; see "Forms". |
17
+ | `value` | `string \| undefined` | (required) | Controlled. A value not in `options` displays as the raw string. |
18
+ | `options` | `SelectOption[]` | (required) | `string`, or `{ label, value, description? }`. Mix freely. |
19
+ | `onChange` | `(value: string \| undefined) => void` | no-op | Receives the option's `value`, `undefined` from the clear button, or the trimmed typed text from "Add:". Not an event. |
20
+ | `surface` | `'card' \| 'page'` | `'card'` | Sets radius **and** elevation together; see "Choosing a surface". |
21
+ | `label` | `string` | | Visible label. |
22
+ | `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row. |
23
+ | `placeholder` | `string` | `'Select…'` | Shown when nothing is selected. |
24
+ | `searchable` | `boolean` | `true` | Opening swaps the trigger for a search box. `false`: a plain list, arrow keys only. |
25
+ | `allowCreate` | `boolean` | `false` | With a search query that matches no label exactly, adds an "Add: *query*" option. |
26
+ | `clearable` | `boolean` | `true` | Shows a ✕ when a value is set. Pass `false` for required fields. |
27
+ | `loading` | `boolean` | `false` | Shows a spinner and "Loading…"; can't open. |
28
+ | `disabled` | `boolean` | `false` | Faded to 50%; can't open; no clear button. |
29
+
30
+ No `className`.
31
+
32
+ ## Choosing a surface
33
+
34
+ Follow [corners](../corners.md):
35
+
36
+ - Inside a `Card` or a modal: omit it (`'card'`, `radius.md`, no shadow).
37
+ - Directly on the page background (e.g. a global picker above the cards):
38
+ `surface="page"` (`radius.lg` + `shadow.cardStack`, like a card).
39
+ - There is no `sm` option for a select nested inside an inset box.
40
+
41
+ ## Forms
42
+
43
+ There is no hidden input carrying `value`: native `FormData` will not contain
44
+ the selection (only the search text while open). Keep `value` in state and
45
+ submit that. The `<label>` targets the search box, so it is not the closed
46
+ trigger's accessible name; the trigger announces the selected label or
47
+ placeholder.
48
+
49
+ ## Keyboard
50
+
51
+ Closed: Enter, Space or ArrowDown open it. Open: ArrowUp/ArrowDown move (and
52
+ wrap), Enter selects, Escape or Tab close. The highlight starts on the first
53
+ option, not the current value.
54
+
55
+ ## Examples
56
+
57
+ ```tsx
58
+ // In a Card form: a fixed list, required.
59
+ <Select
60
+ name="coverFit"
61
+ label="Fit"
62
+ value={coverFit}
63
+ options={[
64
+ { label: 'Contain', value: 'contain', description: 'Letterbox the cover' },
65
+ { label: 'Cover', value: 'cover' },
66
+ ]}
67
+ onChange={setCoverFit}
68
+ searchable={false}
69
+ clearable={false}
70
+ />
71
+
72
+ // A creatable field with async options.
73
+ <Select name="seriesName" label="Name" value={series || undefined}
74
+ options={seriesNames} loading={seriesLoading} allowCreate onChange={setSeries} />
75
+
76
+ // On the page background, no label.
77
+ <Select name="library" surface="page" value={libraryId} options={libraries}
78
+ onChange={setLibraryId} placeholder="Select user…" />
79
+ ```
80
+
81
+ ## Do / don't
82
+
83
+ - Do pass `clearable={false}` when an empty value is invalid.
84
+ - Do test before using inside a modal `<dialog>`: the dropdown portals outside
85
+ the dialog's top layer (see [popover](popover.md)).
86
+ - Don't pass `surface="page"` inside a card.
@@ -0,0 +1,73 @@
1
+ # Switch
2
+
3
+ `import { Switch } from '@korzun/design/control'`
4
+
5
+ An on/off toggle (`role="switch"`) with an optional label and description, a
6
+ full-row `horizontal` layout for forms, and a `loading` state for saves in
7
+ flight. Controlled: you own `checked`.
8
+
9
+ Use something else for: one of several options (`SegmentedControl`, `Select`),
10
+ an action that happens on click (`Button`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `name` | `string` | (required) | **Not a form field**: there is no hidden input. Only the last-resort accessible name. |
17
+ | `checked` | `boolean` | (required) | Controlled. |
18
+ | `onChange` | `(checked: boolean) => void` | (required) | Receives the new value, not an event. Not called while `disabled` or `loading`. |
19
+ | `label` | `string` | | Visible label and accessible name. |
20
+ | `ariaLabel` | `string` | | Accessible name when the visible label lives elsewhere (a grid's row and column headers). Wins over `label`. Without either, `name` is announced. |
21
+ | `description` | `ReactNode` | | Helper text under the label, linked by `aria-describedby`. |
22
+ | `layout` | `'default' \| 'horizontal'` | `'default'` | `default`: track, then label, inline. `horizontal`: full-width `bg.cardHeader` row (`radius.md`), label and description left, track right; **the whole row toggles**, description included. |
23
+ | `radius` | `'inset' \| 'pill'` | `'inset'` | Track shape; see "Choosing a radius". |
24
+ | `loading` | `boolean` | `false` | Ignores clicks immediately and sets `aria-busy`; the thumb becomes a spinner only after 150ms, so fast saves don't flash. Keeps its colour. |
25
+ | `disabled` | `boolean` | `false` | Fades to 40%, removes it from the tab order. |
26
+
27
+ No `className`. Keyboard: Enter and Space toggle. Clicks and those keys stop
28
+ propagation, so a switch inside a clickable card row won't trigger the row.
29
+
30
+ ## Choosing a radius
31
+
32
+ See [corners](../corners.md).
33
+
34
+ - In a shaded row (`layout="horizontal"`, or inside any field row): omit it
35
+ (`inset`, a 4px track concentric with the row's 8px corner).
36
+ - In a `Card` header (`headerAction`), or anywhere with no nearby corner to
37
+ echo: `radius="pill"`.
38
+
39
+ ## Examples
40
+
41
+ ```tsx
42
+ // A form setting inside a Card.
43
+ <Switch
44
+ name="bwCover"
45
+ label="Grayscale"
46
+ layout="horizontal"
47
+ description="Convert cover to grayscale for monochrome screens."
48
+ checked={bwCover}
49
+ onChange={setBwCover}
50
+ />
51
+
52
+ // In a Card header: pill.
53
+ <Card
54
+ title="Series"
55
+ headerAction={
56
+ <Switch name="isSeries" ariaLabel="Part of a series" radius="pill"
57
+ checked={isSeries} onChange={setIsSeries} />
58
+ }
59
+ >…</Card>
60
+
61
+ // Saving straight to the server.
62
+ <Switch name="push-device" label="This device" checked={subscribed}
63
+ loading={busy} disabled={!supported} onChange={toggleSubscription} />
64
+ ```
65
+
66
+ ## Do / don't
67
+
68
+ - Do pass `loading` while the save runs instead of `disabled`; `disabled` means
69
+ "you may not change this".
70
+ - Do give a label-less switch an `ariaLabel`; `name` is a machine key.
71
+ - Don't expect a switch to submit with a `<form>`; send `checked` from state.
72
+ - Don't put an interactive element in `description` of a `horizontal` switch:
73
+ clicking it toggles the switch.
@@ -0,0 +1,52 @@
1
+ # TextArea
2
+
3
+ `import { TextArea } from '@korzun/design/control'`
4
+
5
+ A multi-line text field with an optional label, validation, an optional
6
+ auto-grow mode, and a character counter near `maxLength`. Same label/layout
7
+ system as `TextInput`.
8
+
9
+ Use something else for: single-line text (`TextInput`), tags (`ChipsInput`).
10
+
11
+ ## Props
12
+
13
+ | Prop | Type | Default | Notes |
14
+ |---|---|---|---|
15
+ | `name` | `string` | (required) | The textarea's `name` and the key passed to `onValidChange`. |
16
+ | `value` | `string \| undefined` | `''` | Typed as required. Re-syncs into the field only when the prop changes. |
17
+ | `onChange` | `(value: string \| undefined) => void` | no-op | Receives the string, **`undefined` when emptied**, not an event. **Not called while `validate` fails.** |
18
+ | `label` | `string` | | Not linked to the textarea (no `htmlFor`). |
19
+ | `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row with `radius.md`. |
20
+ | `variant` | `'outlined' \| 'borderless'` | `'outlined'` | `outlined` uses the input recipe (border, `bg.input`); `borderless` drops the border (keeps `radius.md`) and sets no background of its own, so the browser's default textarea background shows; check it in dark mode. |
21
+ | `autoResize` | `boolean` | `false` | Grows to fit content (no scrollbar). Min height 7rem with it, 10rem without; set inline, so a class can't lower it. |
22
+ | `maxLength` | `number` | | Native limit, plus a `n/max` counter once within `max(10% of max, 50)` characters; red at the limit. |
23
+ | `placeholder` | `string` | | |
24
+ | `validate` | `(value: string) => boolean` | `() => true` | `false` turns the label red. |
25
+ | `onValidChange` | `(name: string, valid: boolean) => void` | no-op | Fires only when validity flips. |
26
+
27
+ No `className`, no `disabled`, no `rows`, never resizable by the user
28
+ (`resize: none`).
29
+
30
+ ## Examples
31
+
32
+ ```tsx
33
+ // A note field in a Card form (default horizontal layout).
34
+ <TextArea name="note" label="Note" value={note} onChange={setNote} />
35
+
36
+ // A long description that grows as the user types, label above.
37
+ <TextArea
38
+ name="description"
39
+ layout="vertical"
40
+ autoResize
41
+ maxLength={3000}
42
+ value={description}
43
+ onChange={setDescription}
44
+ />
45
+ ```
46
+
47
+ ## Do / don't
48
+
49
+ - Do use `autoResize` for long free text so the card doesn't scroll inside itself.
50
+ - Do set `maxLength` when the server has a limit; the counter only appears near it.
51
+ - Don't expect `onChange('')`; an empty field reports `undefined`.
52
+ - Don't try to shrink it below 7rem / 10rem with CSS; the min height is inline.
@@ -0,0 +1,73 @@
1
+ # TextInput
2
+
3
+ `import { TextInput } from '@korzun/design/control'`
4
+
5
+ A single-line text (or password) field with an optional label, optional
6
+ validation, and a character counter that appears near `maxLength`. The default
7
+ `horizontal` layout puts the label and field on one shaded row, which is how
8
+ form fields look inside a `Card`.
9
+
10
+ Use something else for: multi-line text (`TextArea`), numbers (`NumberInput`),
11
+ picking from a list (`Select`), a list of tags (`ChipsInput`), dates
12
+ (`DateTimeInput`).
13
+
14
+ ## Props
15
+
16
+ | Prop | Type | Default | Notes |
17
+ |---|---|---|---|
18
+ | `name` | `string` | (required) | The input's `name` (form data) and the key passed to `onValidChange`. |
19
+ | `value` | `string \| undefined` | `''` | Typed as required: pass it, even as `undefined`. See "Controlled-ish" below. |
20
+ | `onChange` | `(value: string \| undefined) => void` | no-op | Receives the string, **`undefined` when the field is emptied**, not an event. **Not called while `validate` fails.** |
21
+ | `label` | `string` | | Visible label. Not linked to the input (`<label>` has no `htmlFor`). |
22
+ | `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row with `radius.md`; `inline` paints nothing. |
23
+ | `placeholder` | `string` | | |
24
+ | `password` | `boolean` | `false` | Renders `type="password"`. |
25
+ | `maxLength` | `number` | | Native limit, plus a `n/max` counter once within `max(10% of max, 10)` characters; red at the limit. |
26
+ | `validate` | `(value: string) => boolean` | `() => true` | Runs on each keystroke. `false` turns the label and border red. |
27
+ | `onValidChange` | `(name: string, valid: boolean) => void` | no-op | Fires only when validity flips. |
28
+ | `onKeyDown` | `(event: KeyboardEvent<HTMLInputElement>) => void` | | Passed through; this one does receive the event. |
29
+ | `autoComplete` | `HTMLInputAutoCompleteAttribute` | | Passed through. |
30
+ | `autoCapitalize` | `'none' \| 'sentences' \| 'words' \| 'characters'` | | Passed through. |
31
+ | `action` | `{ icon, action, danger? }` | | **Broken: do not use.** The icon button is drawn but its `action` callback is never wired up, so clicking does nothing. |
32
+
33
+ No `className`, no `disabled`, no `id`.
34
+
35
+ ## Controlled-ish
36
+
37
+ The field keeps its own text. It re-syncs from `value` only when the `value`
38
+ prop changes. While `validate` fails, the field shows the invalid text but
39
+ `onChange` is not called, so your state keeps the last valid value. Track
40
+ `onValidChange` to block submit.
41
+
42
+ ## Examples
43
+
44
+ ```tsx
45
+ // Inside a Card form: default horizontal layout.
46
+ <TextInput
47
+ name="new-password"
48
+ label="New"
49
+ password
50
+ autoComplete="new-password"
51
+ value={newPassword}
52
+ onChange={(v) => setNewPassword(v ?? '')}
53
+ />
54
+
55
+ // Validated, reporting validity to the form.
56
+ <TextInput
57
+ name="name"
58
+ label="Name"
59
+ maxLength={64}
60
+ validate={(v) => v.length <= 64}
61
+ onValidChange={(field, ok) => setValid((s) => ({ ...s, [field]: ok }))}
62
+ value={name}
63
+ onChange={setName}
64
+ />
65
+ ```
66
+
67
+ ## Do / don't
68
+
69
+ - Do keep the default `horizontal` layout for fields in a `Card` body; use
70
+ `vertical` when the label is long or the field is wide.
71
+ - Do coalesce `undefined` (`v ?? ''`) if your state is a plain string.
72
+ - Don't pass an `action`; render a separate `Button` beside the field instead.
73
+ - Don't rely on clicking the label to focus the field; it isn't associated.