@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,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.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# useModalDialog
|
|
2
|
+
|
|
3
|
+
`import { useModalDialog } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A hook that drives a native `<dialog>` from an `isOpen` boolean: it calls
|
|
6
|
+
`showModal()` / `close()` for you and routes Escape and backdrop clicks to
|
|
7
|
+
`onDismiss`. It is the base for every modal in the library (`ConfirmModal`
|
|
8
|
+
uses it). There is no general `Dialog` component; build custom modals with
|
|
9
|
+
this hook plus the `theme.recipe.modal.*` styles.
|
|
10
|
+
|
|
11
|
+
Use something else for: a plain yes/no confirmation (`ConfirmModal`), a
|
|
12
|
+
dropdown or non-modal floating layer (`Popover`).
|
|
13
|
+
|
|
14
|
+
## Signature
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
function useModalDialog(
|
|
18
|
+
isOpen: boolean,
|
|
19
|
+
onDismiss: () => void,
|
|
20
|
+
canDismiss?: boolean, // default true
|
|
21
|
+
): RefObject<HTMLDialogElement | null>;
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
| Argument | Type | Default | Notes |
|
|
25
|
+
|---|---|---|---|
|
|
26
|
+
| `isOpen` | `boolean` | (required) | The single source of truth. `true` calls `showModal()`, `false` calls `close()`. |
|
|
27
|
+
| `onDismiss` | `() => void` | (required) | Called on Escape and on a backdrop click. **It does not close anything itself**: set your `isOpen` state to `false` in it. Receives no event. |
|
|
28
|
+
| `canDismiss` | `boolean` | `true` | When `false`, Escape and backdrop clicks are swallowed. Pass `!loading` (or `countdown === 0`) so an in-flight request can't be escaped. |
|
|
29
|
+
|
|
30
|
+
Returns a ref to attach to the `<dialog>`.
|
|
31
|
+
|
|
32
|
+
## Behaviour to know
|
|
33
|
+
|
|
34
|
+
- Escape fires the dialog's `cancel` event; the hook always calls
|
|
35
|
+
`preventDefault()` so the browser never closes the dialog behind React's back.
|
|
36
|
+
- A backdrop click counts only when **both** mousedown and mouseup land on the
|
|
37
|
+
`<dialog>` element itself (its content lives in a child). Dragging a text
|
|
38
|
+
selection out of an input onto the backdrop does not dismiss.
|
|
39
|
+
- The `<dialog>` must stay mounted. Rendering it conditionally (`{isOpen && <dialog…>}`)
|
|
40
|
+
breaks `showModal()`; its children also stay mounted while closed, so reset
|
|
41
|
+
any form state yourself when reopening.
|
|
42
|
+
- Never call `showModal()` / `close()` yourself.
|
|
43
|
+
|
|
44
|
+
## Example
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
const ref = useModalDialog(isOpen, onClose, !saving);
|
|
48
|
+
|
|
49
|
+
<dialog ref={ref} className={styles.dialog} onClick={(e) => e.stopPropagation()}>
|
|
50
|
+
<div className={styles.header}>Edit progress</div>
|
|
51
|
+
<div className={styles.body}>…</div>
|
|
52
|
+
<div className={styles.footer}>
|
|
53
|
+
<Button type="text" radius="modal" disabled={saving} onClick={onClose}>Cancel</Button>
|
|
54
|
+
<Button type="primary" radius="modal" loading={saving} onClick={save}>Save</Button>
|
|
55
|
+
</div>
|
|
56
|
+
</dialog>
|
|
57
|
+
|
|
58
|
+
// style.ts
|
|
59
|
+
dialog: { ...theme.recipe.modal.dialog }, // radius.lg: the dialog sits on the page
|
|
60
|
+
header: { ...theme.recipe.modal.header },
|
|
61
|
+
body: { padding: `0 ${theme.space.xxl} ${theme.space.xxl}` },
|
|
62
|
+
footer: { ...theme.recipe.modal.footer },
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Do / don't
|
|
66
|
+
|
|
67
|
+
- Do pass `canDismiss={!loading}` and also disable the Cancel button while
|
|
68
|
+
loading, so every exit is gated the same way.
|
|
69
|
+
- Do keep the `onClick={(e) => e.stopPropagation()}` on the `<dialog>` when it
|
|
70
|
+
is rendered inside a clickable ancestor (a card row); it only stops bubbling,
|
|
71
|
+
dismissal is the hook's job.
|
|
72
|
+
- Do use `radius="modal"` on Buttons inside, and `md` corners for any inset
|
|
73
|
+
surface inside (see [corners](../corners.md)).
|
|
74
|
+
- Don't put a `Select` or `ChipsInput` in a modal without testing it: their
|
|
75
|
+
dropdowns portal to `document.body`, outside the dialog's top layer (see
|
|
76
|
+
[popover](popover.md)).
|
package/docs/corners.md
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Corners
|
|
2
|
+
|
|
3
|
+
Corner radius tracks **depth**, not size. Surfaces on the page background have
|
|
4
|
+
the roundest corners. Each surface nested inside another gets a squarer,
|
|
5
|
+
concentric corner, so the inner curve follows the outer one.
|
|
6
|
+
|
|
7
|
+
## Tokens
|
|
8
|
+
|
|
9
|
+
| Token | Value | Use |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `theme.radius.lg` | 16px | Surfaces on the page background |
|
|
12
|
+
| `theme.radius.md` | 8px | One level in: inside a card or modal; also floating layers |
|
|
13
|
+
| `theme.radius.sm` | 4px | Two levels in: inside an input, inset box, row, or menu |
|
|
14
|
+
| `theme.radius.pill` | 999px | Capsules: nav bar, a Switch with no nearby corner |
|
|
15
|
+
| `theme.radius.circle` | 50% | Round glass buttons |
|
|
16
|
+
|
|
17
|
+
## The rule
|
|
18
|
+
|
|
19
|
+
Find where the element sits, then read its radius from this table:
|
|
20
|
+
|
|
21
|
+
| Where the element sits | Radius | Examples |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| On the page background | `lg` | `Card`, modal dialog (`recipe.modal.dialog`), a standalone `Button` (default `radius`), `<Select surface="page">` |
|
|
24
|
+
| Inside a card or modal | `md` | inputs (`recipe.input`), `Button radius="card"` / `"modal"`, `Tag`, shaded rows, inset boxes |
|
|
25
|
+
| Inside one of those | `sm` | a chip inside an input, `Button radius="inset"` inside an inset box, a menu item, a Switch track in a shaded row |
|
|
26
|
+
| Flush with its parent (zero inset, edges touch) | the parent's radius | an unlabelled Select's trigger, an input filling its row |
|
|
27
|
+
| Inset 4px or less from its parent | `calc(parent − inset)` | a Switch thumb 2px inside a 4px track is 2px |
|
|
28
|
+
| A small control with no nearby corner | `pill` / `circle` | a Switch in a full-width card header |
|
|
29
|
+
| A floating layer (popover, menu, dropdown, toast) | `md`, plus `shadow.hoverLift` or `recipe.glass` | its items are `sm` |
|
|
30
|
+
|
|
31
|
+
**Step down one token per level** (`lg` → `md` → `sm`). Do not subtract the
|
|
32
|
+
padding: a Card has 13px of inset, but the inputs inside it are `md` (8px), not
|
|
33
|
+
16 − 13 = 3px. Exact subtraction applies only to tight insets of 4px or less.
|
|
34
|
+
|
|
35
|
+
## Picking the prop
|
|
36
|
+
|
|
37
|
+
Components take the radius as the **surface they sit on**, not as a size:
|
|
38
|
+
|
|
39
|
+
| Component | Prop | Values |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `Button` | `radius` | `background` (lg, the default), `card` (md), `modal` (md), `inset` (sm) |
|
|
42
|
+
| `Select` | `surface` | `page` (lg), `card` (md) |
|
|
43
|
+
| `Switch` | `radius` | `inset` (sm track), `pill` |
|
|
44
|
+
|
|
45
|
+
- Every `Button` inside a `Card` (body or footer) gets `radius="card"`. Leaving
|
|
46
|
+
it out gives a 16px button inside a 16px card: a bug.
|
|
47
|
+
- Every `Button` in a modal footer gets `radius="modal"`.
|
|
48
|
+
- `type="link"` buttons have no padding or background, so radius doesn't apply.
|
|
49
|
+
|
|
50
|
+
## In your own styles
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
const useStyles = createUseStyles((theme: Theme) => ({
|
|
54
|
+
panel: { ...theme.recipe.card.shell }, // already lg
|
|
55
|
+
inset: {
|
|
56
|
+
backgroundColor: theme.color.bg.cardHeader,
|
|
57
|
+
borderRadius: theme.radius.md, // one level in
|
|
58
|
+
padding: theme.space.md,
|
|
59
|
+
},
|
|
60
|
+
chip: { borderRadius: theme.radius.sm }, // two levels in
|
|
61
|
+
knob: { borderRadius: `calc(${theme.radius.sm} - 2px)` }, // 2px inset
|
|
62
|
+
}));
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- Never write a literal `borderRadius` (`'12px'`, `'50%'`). The only
|
|
66
|
+
non-token form allowed is `calc(theme.radius.X - Npx)` for tight insets.
|
|
67
|
+
- Known off-scale values in the library (don't copy them): `CardRow` uses
|
|
68
|
+
`12px`, and `Card size="small"` uses `9px`.
|
package/docs/hooks.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Hooks
|
|
2
|
+
|
|
3
|
+
`import { isStandalone, useMinimizeOnScroll, usePullToRefresh } from '@korzun/design/hooks'`
|
|
4
|
+
|
|
5
|
+
Mobile-chrome behaviour shared by the layout components: detecting the
|
|
6
|
+
installed app, minimizing bottom chrome on scroll, and pull-to-refresh. All
|
|
7
|
+
three read the **window** scroller; they do nothing for content scrolling in an
|
|
8
|
+
inner `overflow: auto` element.
|
|
9
|
+
|
|
10
|
+
## `isStandalone()`
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
isStandalone(): boolean
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
True when running as an installed PWA (added to the home screen):
|
|
17
|
+
`(display-mode: standalone)` matches, or iOS Safari's
|
|
18
|
+
`navigator.standalone === true`. Not a hook; a plain function, safe to call
|
|
19
|
+
during render because the status can't change within a session. It touches
|
|
20
|
+
`window`, so don't call it during server rendering.
|
|
21
|
+
|
|
22
|
+
Use it to gate chrome that only makes sense when installed: `TopFade` and a
|
|
23
|
+
pull-to-refresh indicator.
|
|
24
|
+
|
|
25
|
+
## `useMinimizeOnScroll({ resetKey })`
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
useMinimizeOnScroll({ resetKey }: { resetKey: string }): MinimizeOnScroll
|
|
29
|
+
type MinimizeOnScroll = { minimized: boolean; expand: () => void }
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
iOS-tab-bar behaviour for bottom chrome. `NavMobile` already uses it; call it
|
|
33
|
+
yourself only for other chrome.
|
|
34
|
+
|
|
35
|
+
- Minimizes when one scroll frame moves **down** at `>= MINIMIZE_SPEED`
|
|
36
|
+
(`0.8` px/ms). Speed, not distance: slow reading never minimizes.
|
|
37
|
+
- Expands after scrolling **up** `EXPAND_AFTER` (`12`) px back from the furthest-down point
|
|
38
|
+
reached since minimizing, on reaching the top, or when you call `expand()`.
|
|
39
|
+
- Only user-driven scrolls count: it ignores scrolling until a `touchstart` or
|
|
40
|
+
`wheel` is seen after `resetKey` last changed (so scroll restoration doesn't
|
|
41
|
+
minimize it). Changing `resetKey` also expands. Pass the route's
|
|
42
|
+
`useLocation().key`.
|
|
43
|
+
- iOS rubber-band overscroll (top and bottom) is clamped out.
|
|
44
|
+
|
|
45
|
+
## `usePullToRefresh(onRefresh, { enabled })`
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
usePullToRefresh(onRefresh: () => Promise<unknown>, options?: { enabled?: boolean }): PullState
|
|
49
|
+
type PullPhase = 'idle' | 'pulling' | 'armed' | 'refreshing'
|
|
50
|
+
type PullState = { phase: PullPhase; offset: number }
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Pull-down-to-refresh for the standalone app, which has no browser gesture. It
|
|
54
|
+
**draws nothing**; you render an indicator from the returned state.
|
|
55
|
+
|
|
56
|
+
- Measures the page's own rubber-band overscroll past the top while a finger is
|
|
57
|
+
down (`-window.scrollY`), so it works only where the browser rubber-bands
|
|
58
|
+
(iOS). It never cancels a touch.
|
|
59
|
+
- `offset`: px of pull, capped at `PULL_THRESHOLD * 1.5` (105). `pulling` below
|
|
60
|
+
`PULL_THRESHOLD` (`70`), `armed` at or above it.
|
|
61
|
+
- Releasing while armed calls `onRefresh` and holds `refreshing` with `offset`
|
|
62
|
+
pinned at `PULL_THRESHOLD` until the promise settles (resolve **or** reject),
|
|
63
|
+
then returns to `idle`. Release short of the threshold returns to `idle`.
|
|
64
|
+
- Ignored: touches starting inside an open `<dialog>`, overscroll with no finger
|
|
65
|
+
down, new pulls while refreshing, and everything when `enabled: false`
|
|
66
|
+
(default `true`).
|
|
67
|
+
- `onRefresh` is read through a ref; an inline closure is fine.
|
|
68
|
+
- **`onRefresh` must return a promise.** A function returning `undefined`
|
|
69
|
+
throws on `.then` and leaves the phase stuck at `refreshing`. Use an `async`
|
|
70
|
+
function.
|
|
71
|
+
|
|
72
|
+
## Examples
|
|
73
|
+
|
|
74
|
+
```tsx
|
|
75
|
+
// An indicator for the installed app, mounted once in the layout.
|
|
76
|
+
export const PullToRefreshIndicator = () => {
|
|
77
|
+
const client = useApolloClient();
|
|
78
|
+
const refresh = useCallback(
|
|
79
|
+
() => client.refetchQueries({ include: 'active' }).then(() => undefined, () => undefined),
|
|
80
|
+
[client]
|
|
81
|
+
);
|
|
82
|
+
const { phase, offset } = usePullToRefresh(refresh);
|
|
83
|
+
const style = {
|
|
84
|
+
transform: `translateY(${offset}px)`,
|
|
85
|
+
opacity: Math.min(1, offset / PULL_THRESHOLD),
|
|
86
|
+
};
|
|
87
|
+
return (
|
|
88
|
+
<div style={style}>
|
|
89
|
+
{phase === 'refreshing'
|
|
90
|
+
? <SpinnerIcon role="status" aria-label="Refreshing" className={styles.spinner} />
|
|
91
|
+
: <ChevronIcon aria-hidden className={phase === 'armed' ? styles.up : styles.down} />}
|
|
92
|
+
</div>
|
|
93
|
+
);
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
{isStandalone() && <PullToRefreshIndicator />}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Do / don't
|
|
100
|
+
|
|
101
|
+
- Do gate pull-to-refresh UI on `isStandalone()`; browser tabs have their own.
|
|
102
|
+
- Do return a promise from `onRefresh` that settles even on failure.
|
|
103
|
+
- Don't call `useMinimizeOnScroll` for the bar `NavMobile` already manages.
|
|
104
|
+
- Don't expect any of these to track a nested scroll container.
|
package/docs/icon.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Icons
|
|
2
|
+
|
|
3
|
+
`import { SearchIcon, type IconProps } from '@korzun/design/icon'`
|
|
4
|
+
|
|
5
|
+
Inline SVG icon components, mostly from [Tabler](https://tabler.io/icons) on a
|
|
6
|
+
24×24 view box. Each one paints in `currentColor`, so it takes the text colour
|
|
7
|
+
of wherever it sits, in both themes, including hover and selected states.
|
|
8
|
+
|
|
9
|
+
Use something else for: a determinate progress mark (`ProgressIndicator`), a
|
|
10
|
+
loading state on a button (`Button`'s `loading`, which draws the spinner for
|
|
11
|
+
you).
|
|
12
|
+
|
|
13
|
+
## Props (`IconProps`)
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `width` / `height` | `number` | `24` / `24` | Pixels. Set both. A `className` with CSS `width`/`height` overrides them. |
|
|
18
|
+
| `className` | `string` | `''` | On the `<svg>`. Use for size, colour (`color: …`) or animation. |
|
|
19
|
+
| `aria-hidden` | `boolean \| 'true' \| 'false'` | | **Not set by default.** Pass `aria-hidden` for a decorative icon next to text. |
|
|
20
|
+
| `aria-label` / `role` | `string` | | For a meaningful standalone icon: `role="img" aria-label="Warning"` (or `role="status"` for a loading spinner). |
|
|
21
|
+
| `stroke` | `string` | `'currentColor'` | Stroke icons only. |
|
|
22
|
+
| `strokeWidth` | `number` | `2` | Stroke icons only. |
|
|
23
|
+
| `fill` | `string` | `'none'` stroke / `'currentColor'` filled | Ignored by `SpinnerIcon` and the emoji icons. |
|
|
24
|
+
|
|
25
|
+
`defaultStrokeIconProps` and `defaultFilledIconProps` are exported for building
|
|
26
|
+
your own icon with the same defaults.
|
|
27
|
+
|
|
28
|
+
## Sizing and colour
|
|
29
|
+
|
|
30
|
+
- Size with `width`/`height` props (`<HomeIcon width={14} height={14} />`), or
|
|
31
|
+
with `height: '1em', width: '1em'` in a class so it scales with the text
|
|
32
|
+
(this is what `Button` does for `prefix`/`suffix`).
|
|
33
|
+
- Colour by setting `color` on the icon or any ancestor. Don't pass `stroke` or
|
|
34
|
+
`fill` colours; they bypass the theme.
|
|
35
|
+
|
|
36
|
+
## Passing icons to other components
|
|
37
|
+
|
|
38
|
+
Components take the icon **component**, never an element:
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
<Button prefix={SearchIcon}>Search</Button> // ComponentType<IconProps>
|
|
42
|
+
<ConfirmModal icon={AlertOctagonIcon} danger … />
|
|
43
|
+
const item: NavItem = { to: '/', label: 'Home', Icon: HomeIcon, active };
|
|
44
|
+
options={[{ value: 'grid', label: 'Grid', Icon: BooksIcon }]} // SegmentedControl
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Every icon
|
|
48
|
+
|
|
49
|
+
| Export | Kind | Depicts |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| `AdjustmentsHorizontalIcon` | stroke | Three horizontal sliders (general settings, filters). |
|
|
52
|
+
| `AlertOctagonIcon` | filled | Octagon with `!` (danger/warning; confirm modals). |
|
|
53
|
+
| `BookIcon` | stroke | A single book (Tabler `book-2`). |
|
|
54
|
+
| `BooksIcon` | stroke | Books standing on a shelf. |
|
|
55
|
+
| `CheckIcon` | filled | A check mark (success). |
|
|
56
|
+
| `ChevronCircleIcon` | stroke | Right chevron in a circle (Card's collapse toggle). |
|
|
57
|
+
| `ChevronIcon` | stroke | Right-pointing chevron; rotate it via `className` for other directions. |
|
|
58
|
+
| `CircleXIcon` | filled | X in a filled circle (clear, error). |
|
|
59
|
+
| `ClockIcon` | stroke | Clock face (time, pending). |
|
|
60
|
+
| `DeviceIcon` | stroke | A tablet / e-reader (Tabler `device-tablet`). |
|
|
61
|
+
| `HandLoveYouIcon` | emoji | 🤟 silhouette (rating 5, "Love"). |
|
|
62
|
+
| `HandOkIcon` | emoji | 👌 silhouette (rating 2, "Okay"). |
|
|
63
|
+
| `HandPeaceIcon` | emoji | ✌️ silhouette (rating 3, "Nice"). |
|
|
64
|
+
| `HandsClapIcon` | emoji | 👏 silhouette (rating 4, "Great"). |
|
|
65
|
+
| `HomeIcon` | stroke | A house. |
|
|
66
|
+
| `InfoCircleIcon` | filled | `i` in a filled circle (info). |
|
|
67
|
+
| `KeyIcon` | stroke | A key (passwords, credentials). |
|
|
68
|
+
| `ListCheckIcon` | stroke | Checklist (requests, tasks). |
|
|
69
|
+
| `MoreIcon` | stroke | Three horizontal dots (overflow menu). |
|
|
70
|
+
| `RowRemoveIcon` | stroke | A table row with an X under it (remove row). |
|
|
71
|
+
| `SearchIcon` | stroke | Magnifying glass. |
|
|
72
|
+
| `SettingsIcon` | stroke | Gear. |
|
|
73
|
+
| `SpinnerIcon` | stroke | A quarter arc. **Does not spin by itself**: add `theme.recipe.spinner` in a class. |
|
|
74
|
+
| `ThumbDownIcon` | emoji | 👎 silhouette (rating 1, "Bad"). |
|
|
75
|
+
| `UploadIcon` | stroke | Arrow up out of a tray. |
|
|
76
|
+
| `UserIcon` | stroke | One person. |
|
|
77
|
+
| `UsersIcon` | stroke | Two people. |
|
|
78
|
+
| `XIcon` | stroke | An X (close, dismiss, error toast). |
|
|
79
|
+
|
|
80
|
+
Filled icons ignore `stroke`/`strokeWidth`. Emoji icons draw the platform's
|
|
81
|
+
colour-emoji glyph as an alpha mask over `currentColor`, so they recolour like
|
|
82
|
+
the others but their exact shape depends on the OS emoji font; they ignore
|
|
83
|
+
`fill`, `stroke` and `strokeWidth`.
|
|
84
|
+
|
|
85
|
+
## Examples
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
// Decorative, inline with text.
|
|
89
|
+
<CheckIcon width={15} height={15} aria-hidden className={styles.checkIcon} />
|
|
90
|
+
Book is valid
|
|
91
|
+
|
|
92
|
+
// A spinning loader with an accessible name.
|
|
93
|
+
const useStyle = createUseStyles((theme: Theme) => ({ spinner: theme.recipe.spinner }));
|
|
94
|
+
<SpinnerIcon role="status" aria-label="Loading" className={styles.spinner} />
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Do / don't
|
|
98
|
+
|
|
99
|
+
- Do pass `aria-hidden` when the icon sits next to a text label.
|
|
100
|
+
- Do give a standalone meaningful icon `role` and `aria-label`.
|
|
101
|
+
- Don't pass `<Icon />` elements where a component is expected.
|
|
102
|
+
- Don't import from icon file paths; only `@korzun/design/icon` is exported.
|