@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,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)).
@@ -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.