@korzun/design 0.0.3 → 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 (42) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +8 -0
  3. package/docs/component/card-divider.md +67 -0
  4. package/docs/component/card-row.md +58 -0
  5. package/docs/component/card.md +82 -0
  6. package/docs/component/collapsible-section.md +57 -0
  7. package/docs/component/empty-state.md +49 -0
  8. package/docs/component/meta-line.md +60 -0
  9. package/docs/component/metadata-list.md +60 -0
  10. package/docs/component/nav-desktop.md +62 -0
  11. package/docs/component/nav-mobile.md +82 -0
  12. package/docs/component/page.md +81 -0
  13. package/docs/component/progress-indicator.md +53 -0
  14. package/docs/component/tag.md +69 -0
  15. package/docs/component/theme-setting.md +58 -0
  16. package/docs/component/top-fade.md +60 -0
  17. package/docs/control/back-button.md +55 -0
  18. package/docs/control/button.md +78 -0
  19. package/docs/control/chips-input.md +77 -0
  20. package/docs/control/confirm-modal.md +68 -0
  21. package/docs/control/date-time-input.md +56 -0
  22. package/docs/control/field-list.md +66 -0
  23. package/docs/control/number-input.md +62 -0
  24. package/docs/control/page-actions-bar.md +64 -0
  25. package/docs/control/page-actions-menu.md +65 -0
  26. package/docs/control/page-footer-actions.md +69 -0
  27. package/docs/control/popover.md +74 -0
  28. package/docs/control/segmented-control.md +73 -0
  29. package/docs/control/select.md +86 -0
  30. package/docs/control/switch.md +73 -0
  31. package/docs/control/text-area.md +52 -0
  32. package/docs/control/text-input.md +73 -0
  33. package/docs/control/use-modal-dialog.md +76 -0
  34. package/docs/corners.md +68 -0
  35. package/docs/hooks.md +104 -0
  36. package/docs/icon.md +102 -0
  37. package/docs/patterns.md +116 -0
  38. package/docs/philosophy.md +91 -0
  39. package/docs/theme.md +96 -0
  40. package/docs/toast.md +85 -0
  41. package/docs/tokens.md +95 -0
  42. package/package.json +4 -1
@@ -0,0 +1,68 @@
1
+ # ConfirmModal
2
+
3
+ `import { ConfirmModal } from '@korzun/design/control'`
4
+
5
+ A ready-made yes/no modal on a native `<dialog>` (via `useModalDialog`): a
6
+ title, a body (`children`), and a footer with a text Cancel and a primary
7
+ Confirm button. It is always mounted and fully controlled by `isOpen`.
8
+
9
+ Use something else for: a modal with its own form or more than two actions
10
+ (build it on [`useModalDialog`](use-modal-dialog.md)), a non-blocking notice
11
+ (toast).
12
+
13
+ ## Props
14
+
15
+ | Prop | Type | Default | Notes |
16
+ |---|---|---|---|
17
+ | `isOpen` | `boolean` | `false` | Controls visibility. Keep the element rendered; toggle this. |
18
+ | `title` | `string` | `'Confirm action'` | Header text. |
19
+ | `children` | `ReactNode` | | Body, rendered in secondary text colour. |
20
+ | `confirmText` | `string` | `'Confirm'` | |
21
+ | `cancelText` | `string` | `'Cancel'` | |
22
+ | `onConfirm` | `() => void` | no-op | Receives no event. **Does not close the modal**: set `isOpen` to `false` yourself when done. |
23
+ | `onCancel` | `() => void` | no-op | Called by the Cancel button, Escape, and a backdrop click. Receives no event. Close the modal in it. |
24
+ | `danger` | `boolean` | `false` | Red Confirm button; also tints `icon` red. |
25
+ | `icon` | `ComponentType<IconProps>` | | Icon **component** shown before the title (`icon={AlertOctagonIcon}`), not an element. |
26
+ | `loading` | `boolean` | `false` | Spinner on Confirm; disables both buttons; Escape and backdrop clicks are ignored (`canDismiss = !loading`). |
27
+ | `confirmDisabled` | `boolean` | `false` | Disables only Confirm (e.g. until a checkbox is ticked). |
28
+
29
+ No `className`. The props type is not exported; use
30
+ `ComponentProps<typeof ConfirmModal>` if you need it.
31
+
32
+ ## Behaviour to know
33
+
34
+ - Footer buttons already use `radius="modal"`; the dialog uses
35
+ `recipe.modal.dialog` (`radius.lg`, it sits on the page). See
36
+ [corners](../corners.md).
37
+ - `onCancel` is the single dismissal path, so whatever you do there runs for
38
+ Escape and backdrop clicks too.
39
+
40
+ ## Example
41
+
42
+ ```tsx
43
+ const [confirming, setConfirming] = useState(false);
44
+
45
+ <Button danger onClick={() => setConfirming(true)}>Delete</Button>
46
+ <ConfirmModal
47
+ isOpen={confirming}
48
+ title="Delete book?"
49
+ confirmText="Delete"
50
+ danger
51
+ icon={AlertOctagonIcon}
52
+ loading={deleting}
53
+ onCancel={() => setConfirming(false)}
54
+ onConfirm={async () => {
55
+ await remove();
56
+ setConfirming(false);
57
+ }}
58
+ >
59
+ This can't be undone.
60
+ </ConfirmModal>
61
+ ```
62
+
63
+ ## Do / don't
64
+
65
+ - Do pass `loading` while the request runs, so the user can't dismiss mid-flight.
66
+ - Do close the modal in both `onCancel` and (after success) `onConfirm`.
67
+ - Don't render it conditionally (`{open && <ConfirmModal …/>}`); toggle `isOpen`.
68
+ - Don't pass `icon={<AlertOctagonIcon />}`; pass the component.
@@ -0,0 +1,56 @@
1
+ # DateTimeInput
2
+
3
+ `import { DateTimeInput, type DateTimeInputProps } from '@korzun/design/control'`
4
+
5
+ A date with an optional time, edited through the browser's native date and time
6
+ pickers and stored as an ISO 8601 string. The time box stays disabled until
7
+ there is a date; clearing the date clears the time.
8
+
9
+ Use something else for: free text (`TextInput`), a year-only number
10
+ (`NumberInput`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `name` | `string` | (required) | Date input's `name`; the time input is named `` `${name}Time` ``. |
17
+ | `value` | `string \| undefined` | (required) | ISO 8601: `2023`, `2023-06`, `2023-06-06`, or a timestamp. `undefined` and `''` mean no date. Re-syncs when the prop changes. |
18
+ | `onChange` | `(value: string \| undefined) => void` | no-op | Receives the recomposed string, not an event (see below). |
19
+ | `label` | `string` | | Linked to the date input. The time input is labelled `` `${label} time` `` (or `Time`). |
20
+ | `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row with `radius.md`. |
21
+
22
+ No `className`, no `disabled`, no `min` / `max`.
23
+
24
+ ## Value format
25
+
26
+ | User has | `onChange` receives |
27
+ |---|---|
28
+ | no date | `undefined` |
29
+ | a date only | `'2023-06-06'` |
30
+ | date and time | `'2023-06-06T16:30:00Z'` |
31
+
32
+ - **The time is UTC, not local.** A stored `2015-08-04T22:30:00-05:00` displays
33
+ as 2015-08-05, 03:30, and the user picks times in UTC too.
34
+ - Year and year-month values display as the 1st of the period (`1965` shows
35
+ 1965-01-01). Merely displaying doesn't rewrite them; editing does.
36
+ - An unreadable value (`'June 2023'`, `'2023-13-45'`) displays as empty.
37
+ - Native form data holds the date and the time as **two separate fields**
38
+ (`name`, `nameTime`), not the composed value. Submit `value` from state.
39
+
40
+ ## Example
41
+
42
+ ```tsx
43
+ // In a Card form.
44
+ <DateTimeInput
45
+ name="publishDate"
46
+ label="Publish Date"
47
+ value={publishDate}
48
+ onChange={setPublishDate}
49
+ />
50
+ ```
51
+
52
+ ## Do / don't
53
+
54
+ - Do keep the composed string from `onChange` in state and send that.
55
+ - Do tell users times are UTC if that matters for the field.
56
+ - Don't read `FormData.get(name)` expecting a timestamp; it is only the date part.
@@ -0,0 +1,66 @@
1
+ # FieldList
2
+
3
+ `import { FieldList, type ColumnDescriptor, type FieldRow } from '@korzun/design/control'`
4
+
5
+ An editable list of rows, each with one or more text/number inputs and a
6
+ remove button, plus a dashed "add" button underneath. Fully controlled: you own
7
+ the rows and apply every change. On phones a row's columns stack.
8
+
9
+ Use something else for: a list of single words or tags (`ChipsInput`), a fixed
10
+ set of fields (`TextInput` / `NumberInput` directly).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `rows` | `FieldRow[]` | (required) | `{ _key: string } & Record<string, string \| number \| undefined>`. `_key` must be stable and unique: it is the React key and part of each input's `name`. |
17
+ | `columns` | `ColumnDescriptor[]` | (required) | One input per column per row; see below. |
18
+ | `onAdd` | `() => void` | (required) | Append a row with a fresh `_key`. Receives no event. |
19
+ | `onRemove` | `(rowKey: string) => void` | (required) | |
20
+ | `onChange` | `(rowKey: string, fieldKey: string, value: string \| number \| undefined) => void` | (required) | `string` from a text column, `number` from a number column, `undefined` when a field is emptied. Not called while that field's `validate` fails. |
21
+ | `onValidChange` | `(fieldName: string, valid: boolean) => void` | | `fieldName` is `` `${rowKey}.${columnKey}` ``. Fires only when validity flips. |
22
+ | `addLabel` | `string` | (required) | Text of the add button ("Add identifier"). |
23
+
24
+ No `className`.
25
+
26
+ `ColumnDescriptor` is
27
+ `{ type: 'text' | 'number'; key: string; placeholder?: string; validate?: (text: string) => boolean }`.
28
+ A text column renders a `TextInput`, a number column a `NumberInput` (see
29
+ those docs for the controlled-ish behaviour). A number column shows a row value
30
+ only if it is a `number`; a numeric string displays as empty.
31
+
32
+ ## Behaviour to know
33
+
34
+ - The add button is hard-wired to `radius="card"`, so FieldList belongs in a
35
+ `Card` body (or a modal). On the page background its corners will be one step
36
+ too square.
37
+ - Inputs have no labels; use `placeholder` to say what each column is.
38
+ - Every remove button is titled "Remove row" (its accessible name); they are not
39
+ distinguished per row.
40
+
41
+ ## Example
42
+
43
+ ```tsx
44
+ <Card title="Identifiers">
45
+ <FieldList
46
+ addLabel="Add identifier"
47
+ columns={[
48
+ { type: 'text', key: 'scheme', placeholder: 'Scheme (e.g. isbn)' },
49
+ { type: 'text', key: 'value', placeholder: 'Value' },
50
+ ]}
51
+ rows={identifiers}
52
+ onAdd={() => setIdentifiers((r) => [...r, { _key: crypto.randomUUID() }])}
53
+ onRemove={(key) => setIdentifiers((r) => r.filter((row) => row._key !== key))}
54
+ onChange={(key, field, value) =>
55
+ setIdentifiers((r) => r.map((row) => (row._key === key ? { ...row, [field]: value } : row)))
56
+ }
57
+ onValidChange={handleValidChange}
58
+ />
59
+ </Card>
60
+ ```
61
+
62
+ ## Do / don't
63
+
64
+ - Do generate `_key` once per row (`crypto.randomUUID()`), never from the index.
65
+ - Do strip `_key` before sending rows to the server.
66
+ - Don't store numeric columns as strings; they won't display.
@@ -0,0 +1,62 @@
1
+ # NumberInput
2
+
3
+ `import { NumberInput } from '@korzun/design/control'`
4
+
5
+ A single-line field for a number, with an optional label and validation. It
6
+ parses with `parseFloat` and reports `number | undefined`. Same label/layout
7
+ system as `TextInput`.
8
+
9
+ Use something else for: one of a few fixed numbers (`SegmentedControl` or
10
+ `Select`), free text (`TextInput`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `name` | `string` | (required) | The input's `name` and the key passed to `onValidChange`. |
17
+ | `label` | `string \| undefined` | (required key) | **Must be passed, even as `label={undefined}`**: the type has no `?`. Not linked to the input (no `htmlFor`). |
18
+ | `value` | `number \| undefined` | (required) | Re-syncs into the field only when the prop changes. |
19
+ | `onChange` | `(value: number \| undefined) => void` | no-op | Receives `parseFloat(text)`, or `undefined` when emptied. **Not called while `validate` fails.** |
20
+ | `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row with `radius.md`. |
21
+ | `placeholder` | `string` | | |
22
+ | `validate` | `(text: string) => boolean` | empty or numeric | Receives the **raw text**. Replacing it replaces the numeric check, so include one yourself. |
23
+ | `onValidChange` | `(name: string, valid: boolean) => void` | no-op | Fires only when validity flips. |
24
+
25
+ No `className`, no `disabled`, no `min` / `max` / `step`.
26
+
27
+ ## Behaviour to know
28
+
29
+ - It is a plain `<input>` (no `type="number"`, no `inputMode`), so phones show
30
+ the full text keyboard and there are no spinner arrows.
31
+ - The default check accepts anything JavaScript reads as a number: `1.5`, `-3`,
32
+ `1e3` (reported as `1000`).
33
+ - Invalid text stays visible with a red label and border; your state keeps the
34
+ last valid number.
35
+
36
+ ## Examples
37
+
38
+ ```tsx
39
+ // In a Card form.
40
+ <NumberInput
41
+ name="seriesIndex"
42
+ label="Index"
43
+ value={seriesIndex}
44
+ onChange={setSeriesIndex}
45
+ />
46
+
47
+ // A custom rule: still check the text is numeric.
48
+ <NumberInput
49
+ name="coverWidth"
50
+ label="Width"
51
+ value={coverWidth}
52
+ onChange={setCoverWidth}
53
+ validate={(t) => t === '' || (/^\d+$/.test(t) && Number(t) <= 4096)}
54
+ onValidChange={(field, ok) => setValid((s) => ({ ...s, [field]: ok }))}
55
+ />
56
+ ```
57
+
58
+ ## Do / don't
59
+
60
+ - Do pass `label={undefined}` explicitly when there is no visible label.
61
+ - Do report `onValidChange` into the form and disable submit while any field is invalid.
62
+ - Don't expect integer-only input unless your `validate` enforces it.
@@ -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.