@korzun/design 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +11 -1
  3. package/dist/component/index.d.ts +1 -1
  4. package/dist/component/index.d.ts.map +1 -1
  5. package/dist/component/index.js.map +1 -1
  6. package/dist/component/tag/index.d.ts +5 -2
  7. package/dist/component/tag/index.d.ts.map +1 -1
  8. package/dist/component/tag/index.js +2 -2
  9. package/dist/component/tag/index.js.map +1 -1
  10. package/dist/component/tag/style.d.ts +2 -1
  11. package/dist/component/tag/style.d.ts.map +1 -1
  12. package/dist/component/tag/style.js +21 -7
  13. package/dist/component/tag/style.js.map +1 -1
  14. package/dist/theme/theme.d.ts +5 -0
  15. package/dist/theme/theme.d.ts.map +1 -1
  16. package/dist/theme/theme.js +13 -1
  17. package/dist/theme/theme.js.map +1 -1
  18. package/docs/component/card-divider.md +67 -0
  19. package/docs/component/card-row.md +58 -0
  20. package/docs/component/card.md +82 -0
  21. package/docs/component/collapsible-section.md +57 -0
  22. package/docs/component/empty-state.md +49 -0
  23. package/docs/component/meta-line.md +60 -0
  24. package/docs/component/metadata-list.md +60 -0
  25. package/docs/component/nav-desktop.md +62 -0
  26. package/docs/component/nav-mobile.md +82 -0
  27. package/docs/component/page.md +81 -0
  28. package/docs/component/progress-indicator.md +53 -0
  29. package/docs/component/tag.md +69 -0
  30. package/docs/component/theme-setting.md +58 -0
  31. package/docs/component/top-fade.md +60 -0
  32. package/docs/control/back-button.md +55 -0
  33. package/docs/control/button.md +78 -0
  34. package/docs/control/chips-input.md +77 -0
  35. package/docs/control/confirm-modal.md +68 -0
  36. package/docs/control/date-time-input.md +56 -0
  37. package/docs/control/field-list.md +66 -0
  38. package/docs/control/number-input.md +62 -0
  39. package/docs/control/page-actions-bar.md +64 -0
  40. package/docs/control/page-actions-menu.md +65 -0
  41. package/docs/control/page-footer-actions.md +69 -0
  42. package/docs/control/popover.md +74 -0
  43. package/docs/control/segmented-control.md +73 -0
  44. package/docs/control/select.md +86 -0
  45. package/docs/control/switch.md +73 -0
  46. package/docs/control/text-area.md +52 -0
  47. package/docs/control/text-input.md +73 -0
  48. package/docs/control/use-modal-dialog.md +76 -0
  49. package/docs/corners.md +68 -0
  50. package/docs/hooks.md +104 -0
  51. package/docs/icon.md +102 -0
  52. package/docs/patterns.md +116 -0
  53. package/docs/philosophy.md +91 -0
  54. package/docs/theme.md +96 -0
  55. package/docs/toast.md +85 -0
  56. package/docs/tokens.md +95 -0
  57. package/package.json +7 -1
  58. package/src/component/index.ts +1 -1
  59. package/src/component/tag/index.tsx +7 -2
  60. package/src/component/tag/style.ts +27 -7
  61. package/src/theme/theme.ts +16 -1
@@ -0,0 +1,69 @@
1
+ # Tag
2
+
3
+ `import { Tag, type TagTone } from '@korzun/design/component'`
4
+
5
+ A small coloured chip (an inline `<span>`) for a category, status, or value:
6
+ an author, a subject, "Read only". Optionally clickable, in which case it
7
+ becomes `role="button"` with `tabIndex=0` and Enter/Space.
8
+
9
+ Use something else for: an editable list of chips (`ChipsInput` in
10
+ `@korzun/design/control`), an action (`Button`), a count on a nav tab
11
+ (`NavItem.badge`).
12
+
13
+ ## Props
14
+
15
+ | Prop | Type | Default | Notes |
16
+ |---|---|---|---|
17
+ | `children` | `ReactNode` | required | Label. |
18
+ | `tone` | `TagTone` | `'subject'` | Colour, from `theme.color.chip`. See below. |
19
+ | `size` | `'sm' \| 'md'` | `'md'` | `sm` is compact (tight line height) and fits inside a normal text line, so rows keep the same height with or without chips. |
20
+ | `onClick` | `() => void` | | Makes it a button: pointer cursor, focusable, hover deepens the tone. Receives no event. |
21
+
22
+ No `className`, no `ariaLabel`.
23
+
24
+ ## Choosing a tone
25
+
26
+ `TagTone` is `keyof Theme['color']['chip']`, so the tones are **domain names**,
27
+ not colour names. Pick by what the tag *is*:
28
+
29
+ | Tone | Use for |
30
+ |---|---|
31
+ | `status` | A state (Pending, Active, Read only). |
32
+ | `author` | A person who wrote something. |
33
+ | `series` | A series name. |
34
+ | `subject` | A subject / genre / keyword. The default. |
35
+ | `book` | A book or title. |
36
+ | `entryType` | The kind of an entry or record. |
37
+ | `user` | An app user / account. |
38
+ | `rating` | A rating value. |
39
+ | `neutral` | A state with no category ("no change"): quiet grey. |
40
+
41
+ Each tone has its own `text`, `bg`, and `border` in both light and dark themes.
42
+ A consumer's theme can't add tones; the list is fixed by the `Theme` type.
43
+
44
+ ## Corners
45
+
46
+ `radius.md` at both sizes, which is right inside a Card or modal; see
47
+ [corners](../corners.md).
48
+
49
+ ## Examples
50
+
51
+ ```tsx
52
+ // Compact chips in a review row (inside a card).
53
+ {fix.toChips.map((c) => <Tag key={c} size="sm">{c}</Tag>)}
54
+
55
+ // A status, in neutral or status tone.
56
+ <Tag size="sm" tone="status">{write ? 'Read & write' : 'Read only'}</Tag>
57
+
58
+ // A clickable author chip that filters the list.
59
+ <Tag tone="author" onClick={() => setFilter({ author: name })}>{name}</Tag>
60
+ ```
61
+
62
+ ## Do / don't
63
+
64
+ - Do choose `tone` by meaning, so the same kind of thing is the same colour
65
+ everywhere.
66
+ - Do use `size="sm"` inside text rows and lists.
67
+ - Don't use `neutral` just to make a tag grey when it has a category.
68
+ - Don't nest a clickable Tag inside another clickable element (Button, a
69
+ clickable Card); both would fire.
@@ -0,0 +1,58 @@
1
+ # ThemeSetting
2
+
3
+ `import { ThemeSetting } from '@korzun/design/component'`
4
+
5
+ A ready-made settings feature: a `Card` titled "Appearance" holding a
6
+ three-option `SegmentedControl` (Light / Dark / Auto) bound to the theme. A
7
+ choice applies immediately and is persisted by `ThemeProvider`.
8
+
9
+ Use something else for: reading the current choice or the resolved mode in
10
+ your own code (`useThemeSetting` from `@korzun/design/theme`), a custom
11
+ appearance UI (build it on `useThemeSetting`).
12
+
13
+ ## Props
14
+
15
+ None. No `className`, no title override.
16
+
17
+ ## How it works
18
+
19
+ - Reads and writes through `useThemeSetting()`, i.e. the context provided by
20
+ `ThemeProvider` from `@korzun/design/theme`.
21
+ - `ThemeProvider` stores the choice in `localStorage` under
22
+ `theme-setting:<identity>`, where `identity` is the provider's prop (for
23
+ example the signed-in username). Switching identity restores that user's
24
+ choice; `identity={null}` (the default) **stores nothing** and the
25
+ setting resets to `'auto'` on reload.
26
+ - `'auto'` follows the OS `prefers-color-scheme` live.
27
+
28
+ ## Surprising behaviour
29
+
30
+ - **Without a `ThemeProvider` above it, it renders but does nothing**: the
31
+ default context's setter is a no-op.
32
+ - **Name clash at the package root:** `@korzun/design` (root entry) exports
33
+ this component as `ThemeSetting` and the `'light' | 'dark' | 'auto'` type as
34
+ `ThemeSettingValue`. From `@korzun/design/theme` the type is named
35
+ `ThemeSetting`. Import the component from `/component` to avoid confusion.
36
+
37
+ ## Examples
38
+
39
+ ```tsx
40
+ // App root: give the provider an identity so the choice persists per user.
41
+ <ThemeProvider identity={viewer?.username ?? null}>
42
+ <ToastProvider>
43
+ <AppRouter />
44
+ </ToastProvider>
45
+ </ThemeProvider>
46
+
47
+ // The settings screen: it is one Card in the stack.
48
+ <Page bottomNav>
49
+ <ThemeSetting />
50
+ <Card title="Change password">…</Card>
51
+ </Page>
52
+ ```
53
+
54
+ ## Do / don't
55
+
56
+ - Do place it directly in a `Page`, like any other Card.
57
+ - Do pass `identity` to `ThemeProvider` if the choice should survive a reload.
58
+ - Don't wrap it in another `Card`; it already is one.
@@ -0,0 +1,60 @@
1
+ # TopFade
2
+
3
+ `import { TopFade } from '@korzun/design/component'`
4
+
5
+ A decorative, mobile-only scrim: a `position: fixed` frosted-glass band at the
6
+ top of the viewport, as tall as the status-bar safe-area inset plus
7
+ `space.md`, that blurs content scrolling under the device status bar and fades
8
+ to nothing below it (Safari style). It is `aria-hidden`,
9
+ `pointer-events: none`, and hidden at `min-width: 641px`.
10
+
11
+ Use something else for: a header or toolbar (`Page` header row / actions),
12
+ dimming behind a modal (the modal's own backdrop).
13
+
14
+ ## Props
15
+
16
+ None. No `className`.
17
+
18
+ ## When to render it
19
+
20
+ - **Only in the installed (standalone) app**, gated with `isStandalone()` from
21
+ `@korzun/design/hooks`. In a browser tab the OS status bar is not drawn over
22
+ the page, `env(safe-area-inset-top)` is 0, and the band would be a thin
23
+ blurred strip with no purpose.
24
+ - Once, in the layout route, not per page.
25
+ - It sits at `theme.zIndex.header`: above page content, below the floating
26
+ controls and nav (`zIndex.sticky`).
27
+
28
+ ## Surprising behaviour
29
+
30
+ - Its height comes from `env(safe-area-inset-top)`, which is non-zero only when
31
+ the page opts into the safe area (`<meta name="viewport"
32
+ content="…, viewport-fit=cover">`). Without that it is `space.md` tall.
33
+ - The tail is deliberately short so chrome resting near the top edge
34
+ (`theme.layout.floatingControlTopBase`) is never drawn through the blur.
35
+ Don't place your own content in the first `space.md` below the inset.
36
+
37
+ ## Examples
38
+
39
+ ```tsx
40
+ // Layout route for nav-bearing pages.
41
+ export const NavLayout = () => (
42
+ <>
43
+ <NavDesktop items={items} />
44
+ <NavMobile main={…} settings={…} expanded={…} />
45
+ {isStandalone() && (
46
+ <>
47
+ <TopFade />
48
+ <PullToRefreshIndicator /> {/* your own, built on usePullToRefresh */}
49
+ </>
50
+ )}
51
+ <Outlet />
52
+ </>
53
+ );
54
+ ```
55
+
56
+ ## Do / don't
57
+
58
+ - Do gate it on `isStandalone()`.
59
+ - Do render it once per app layout.
60
+ - Don't use it as a visual header; it carries no content and ignores clicks.
@@ -0,0 +1,55 @@
1
+ # BackButton
2
+
3
+ `import { BackButton } from '@korzun/design/control'`
4
+
5
+ A round glass "Back" button that navigates to a fixed path. It is mobile-only:
6
+ at widths of 641px and up it renders `display: none`, because desktop has its
7
+ own navigation. Usually you don't render it yourself: pass `back` to `Page`.
8
+
9
+ Use something else for: any other action (`Button`), header actions
10
+ (`PageActionsMenu` / `PageActionsBar`, also via `Page`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `to` | `string` | (required) | Path to navigate to. |
17
+
18
+ That is the whole API. No `className`, no label, no `onClick`.
19
+
20
+ ## Behaviour to know
21
+
22
+ - **It pushes `to`, it does not go back in history.** Click (or Enter / Space)
23
+ calls `navigate(to, { state: { restoreScroll: true } })`: a new history entry,
24
+ with a state flag asking the destination's scroll manager to restore its
25
+ remembered position instead of jumping to the top.
26
+ - Requires a `react-router` (v8, a peer dependency) router above it; it calls
27
+ `useNavigate()` and throws without one.
28
+ - Renders a `<div role="button" tabIndex={0} aria-label="Back">` with a
29
+ left-pointing chevron, 46×46px, `radius.circle`, `recipe.glass`.
30
+ - It does not position itself. `Page` puts it in its sticky controls row; if
31
+ you render it elsewhere, you place it.
32
+
33
+ ## Examples
34
+
35
+ ```tsx
36
+ // Preferred: let Page render it (and PageActionsMenu beside it on mobile).
37
+ <Page back="/library" headerActions={actions}>
38
+ …
39
+ </Page>
40
+
41
+ // Standalone, inside your own row.
42
+ <div className={styles.controls}>
43
+ <BackButton to={path.book(book.id)} />
44
+ </div>
45
+ ```
46
+
47
+ ## Do / don't
48
+
49
+ - Do use `Page back="…"` instead of rendering `BackButton` directly, so it lines
50
+ up with the mobile actions menu.
51
+ - Do pass the logical parent route (`/library`, the book page), not a guess at
52
+ the previous URL: it always goes to `to`.
53
+ - Don't expect it on desktop; it is hidden at 641px and up.
54
+ - Don't wrap it in a `<button>` or `<a>`, or try to restyle it: there is no
55
+ `className`.
@@ -0,0 +1,78 @@
1
+ # Button
2
+
3
+ `import { Button } from '@korzun/design/control'`
4
+
5
+ A clickable action with a visual variant, optional icons, and a loading state.
6
+ Renders a `<div role="button">` (keyboard: Enter and Space) unless `submit` is
7
+ set, in which case it renders a native `<button type="submit">`.
8
+
9
+ Use something else for: navigating back (`BackButton`), page-level actions in
10
+ the header (`PageActionsBar`, `PageActionsMenu`), sticky footer actions
11
+ (`PageFooterActions`), picking one of several options (`SegmentedControl`).
12
+
13
+ ## Props
14
+
15
+ | Prop | Type | Default | Notes |
16
+ |---|---|---|---|
17
+ | `children` | `ReactNode` | | Label. |
18
+ | `type` | `'default' \| 'primary' \| 'text' \| 'link' \| 'dashed'` | `'default'` | **Visual variant, not the HTML `type`.** Use `submit` for a submit button. |
19
+ | `radius` | `'background' \| 'card' \| 'inset' \| 'modal'` | `'background'` | The surface the button sits on; see [corners](../corners.md). |
20
+ | `danger` | `boolean` | `false` | Red treatment. Mutually exclusive with `success` (type error). |
21
+ | `success` | `boolean` | `false` | Green treatment. Mutually exclusive with `danger`. |
22
+ | `loading` | `boolean` | `false` | Shows a spinner in place of the icons; blocks clicks. |
23
+ | `disabled` | `boolean` | `false` | |
24
+ | `onClick` | `() => void` | no-op | **Ignored when `submit` is set**; the form submits instead. Receives no event. |
25
+ | `submit` | `boolean` | `false` | Render a native submit button. Also shows the spinner while the enclosing form action is pending (`useFormStatus`). |
26
+ | `form` | `string` | | Id of the `<form>` to submit, for a submit button outside its form (e.g. in a `Card` footer). |
27
+ | `prefix` / `suffix` | `ComponentType<IconProps>` | | An icon **component** (`prefix={SearchIcon}`), not an element. |
28
+ | `ariaLabel` | `string` | | Required when the label alone is ambiguous, e.g. repeated "Remove" buttons in a list. |
29
+ | `ariaExpanded` / `ariaControls` | `boolean` / `string` | | For disclosure buttons. |
30
+ | `className` | `string` | | Override with `'&&'` specificity in your sheet, never `!important`. |
31
+ | `title`, `tabIndex` | | | Passed through. |
32
+
33
+ ## Choosing a variant
34
+
35
+ - `primary`: the one main action of a card, modal, or page (Save, Confirm).
36
+ - `default`: secondary actions; bordered.
37
+ - `text`: Cancel in a modal footer.
38
+ - `link`: inline row actions (Remove, Load more). It has no padding, so `radius`
39
+ doesn't matter for it.
40
+ - `dashed`: an "add a row" affordance (as in `FieldList`).
41
+ - Add `danger` for destructive actions (Delete, Log out), on `primary` in a
42
+ confirm or on `default` otherwise.
43
+
44
+ ## Examples
45
+
46
+ ```tsx
47
+ // On the page background: omit radius (defaults to 'background').
48
+ <Button danger onClick={logOut}>Log out</Button>
49
+
50
+ // In a Card footer, submitting a form that lives in the card body.
51
+ <Card
52
+ title="Change password"
53
+ footer={
54
+ <Button type="primary" radius="card" submit form="change-password">
55
+ Save
56
+ </Button>
57
+ }
58
+ >
59
+ <form id="change-password" action={save}>…</form>
60
+ </Card>
61
+
62
+ // A modal footer.
63
+ <Button type="text" radius="modal" onClick={onCancel}>Cancel</Button>
64
+ <Button type="primary" danger radius="modal" loading={deleting} onClick={onConfirm}>
65
+ Delete
66
+ </Button>
67
+ ```
68
+
69
+ ## Do / don't
70
+
71
+ - Do set `radius="card"` on every Button inside a `Card` (body or footer) and
72
+ `radius="modal"` inside a modal, except `type="link"`.
73
+ - Do give repeated row actions a distinguishing `ariaLabel` ("Remove Kindle").
74
+ - Don't pass `type="submit"`: it is not a valid variant. Use `submit`.
75
+ - Don't pass `onClick` to a submit button and expect it to run.
76
+ - Don't pass an element to `prefix`/`suffix` (`prefix={<SearchIcon />}`); pass
77
+ the component.
78
+ - Don't wrap Button in a `<button>` or `<a>`: it is already interactive.
@@ -0,0 +1,77 @@
1
+ # ChipsInput
2
+
3
+ `import { ChipsInput } from '@korzun/design/control'`
4
+
5
+ A tag field: the current values render as coloured chips inside an input box,
6
+ typing filters a suggestion dropdown (a `Popover`), and Enter adds a chip. Fully
7
+ controlled: you own the `string[]`.
8
+
9
+ Use something else for: one value from a list (`Select`), one of a few fixed
10
+ options (`SegmentedControl`), free text (`TextInput`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `value` | `string[]` | (required) | The chips. Controlled. |
17
+ | `suggestions` | `string[]` | (required) | Pass `[]` for none. Already-chosen values are hidden; matching is case-insensitive substring. |
18
+ | `onChange` | `(values: string[]) => void` | (required) | Receives the whole new array, not an event. |
19
+ | `allowCustom` | `boolean` | `true` | Enter (or Tab) adds the typed text as a chip. `false`: only suggestions can be added. |
20
+ | `label` | `string` | | **Ignored in the default `block` layout.** Set `layout="horizontal"` or `"vertical"` to show it. |
21
+ | `layout` | `'block' \| 'horizontal' \| 'vertical'` | `'block'` | `block` = the bare box, no label. `horizontal`/`vertical` add a label on a `bg.cardHeader` row (`radius.md`), like the other fields. |
22
+ | `placeholder` | `string` | | Shown only while there are no chips. |
23
+ | `chipColor` | `keyof theme.color.chip` | `'subject'` | `status`, `author`, `series`, `subject`, `book`, `entryType`, `user`, `rating`, `neutral`. |
24
+ | `dense` | `boolean` | `false` | Matches a standard input's height, so it lines up with `TextInput`/`Select` rows. Leave off for a roomy standalone tag box. |
25
+ | `disabled` | `boolean` | `false` | Disables typing and the chip remove buttons. |
26
+ | `name` | `string` | | Set on the text input only: form data gets the **half-typed text, not the chips**. Submit `value` yourself. |
27
+
28
+ No `className`. The label is linked to the input with a generated id.
29
+
30
+ ## Keyboard
31
+
32
+ - ArrowDown / ArrowUp move the highlight; Enter or Tab adds the highlighted
33
+ suggestion, else (with `allowCustom`) the trimmed typed text.
34
+ - **Tab with text typed adds a chip and keeps focus in the field** (it calls
35
+ `preventDefault`); Tab on an empty field moves focus normally.
36
+ - Enter never submits the surrounding form while text is typed, even when
37
+ nothing could be added.
38
+ - Backspace on an empty field removes the last chip.
39
+ - A value that matches an existing chip case-insensitively is not added.
40
+
41
+ ## Examples
42
+
43
+ ```tsx
44
+ // A standalone subjects box in its own Card.
45
+ <Card title="Subjects">
46
+ <ChipsInput
47
+ value={subjects}
48
+ suggestions={allSubjects}
49
+ onChange={setSubjects}
50
+ placeholder="Add subject…"
51
+ />
52
+ </Card>
53
+
54
+ // A labelled row in a form, restricted to known users.
55
+ <ChipsInput
56
+ name="users"
57
+ label="Users"
58
+ layout="horizontal"
59
+ dense
60
+ value={selectedUsers}
61
+ suggestions={userNames}
62
+ onChange={setSelectedUsers}
63
+ allowCustom={false}
64
+ chipColor="user"
65
+ disabled={loadingUsers}
66
+ placeholder={loadingUsers ? 'Loading…' : 'Add users…'}
67
+ />
68
+ ```
69
+
70
+ ## Do / don't
71
+
72
+ - Do set `layout="horizontal"` and `dense` when it sits among other form fields
73
+ in a `Card`; otherwise the label silently disappears.
74
+ - Do pick a `chipColor` that matches how the same values are tagged elsewhere.
75
+ - Don't rely on `name` for form submission.
76
+ - Don't use it inside a modal `<dialog>` without testing: the dropdown portals
77
+ outside the dialog's top layer (see [popover](popover.md)).
@@ -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.