@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.
- package/AGENTS.md +78 -0
- package/README.md +8 -0
- package/docs/component/card-divider.md +67 -0
- package/docs/component/card-row.md +58 -0
- package/docs/component/card.md +82 -0
- package/docs/component/collapsible-section.md +57 -0
- package/docs/component/empty-state.md +49 -0
- package/docs/component/meta-line.md +60 -0
- package/docs/component/metadata-list.md +60 -0
- package/docs/component/nav-desktop.md +62 -0
- package/docs/component/nav-mobile.md +82 -0
- package/docs/component/page.md +81 -0
- package/docs/component/progress-indicator.md +53 -0
- package/docs/component/tag.md +69 -0
- package/docs/component/theme-setting.md +58 -0
- package/docs/component/top-fade.md +60 -0
- package/docs/control/back-button.md +55 -0
- package/docs/control/button.md +78 -0
- package/docs/control/chips-input.md +77 -0
- package/docs/control/confirm-modal.md +68 -0
- package/docs/control/date-time-input.md +56 -0
- package/docs/control/field-list.md +66 -0
- package/docs/control/number-input.md +62 -0
- package/docs/control/page-actions-bar.md +64 -0
- package/docs/control/page-actions-menu.md +65 -0
- package/docs/control/page-footer-actions.md +69 -0
- package/docs/control/popover.md +74 -0
- package/docs/control/segmented-control.md +73 -0
- package/docs/control/select.md +86 -0
- package/docs/control/switch.md +73 -0
- package/docs/control/text-area.md +52 -0
- package/docs/control/text-input.md +73 -0
- package/docs/control/use-modal-dialog.md +76 -0
- package/docs/corners.md +68 -0
- package/docs/hooks.md +104 -0
- package/docs/icon.md +102 -0
- package/docs/patterns.md +116 -0
- package/docs/philosophy.md +91 -0
- package/docs/theme.md +96 -0
- package/docs/toast.md +85 -0
- package/docs/tokens.md +95 -0
- 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.
|