@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.
- package/AGENTS.md +78 -0
- package/README.md +11 -1
- package/dist/component/index.d.ts +1 -1
- package/dist/component/index.d.ts.map +1 -1
- package/dist/component/index.js.map +1 -1
- package/dist/component/tag/index.d.ts +5 -2
- package/dist/component/tag/index.d.ts.map +1 -1
- package/dist/component/tag/index.js +2 -2
- package/dist/component/tag/index.js.map +1 -1
- package/dist/component/tag/style.d.ts +2 -1
- package/dist/component/tag/style.d.ts.map +1 -1
- package/dist/component/tag/style.js +21 -7
- package/dist/component/tag/style.js.map +1 -1
- package/dist/theme/theme.d.ts +5 -0
- package/dist/theme/theme.d.ts.map +1 -1
- package/dist/theme/theme.js +13 -1
- package/dist/theme/theme.js.map +1 -1
- 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 +7 -1
- package/src/component/index.ts +1 -1
- package/src/component/tag/index.tsx +7 -2
- package/src/component/tag/style.ts +27 -7
- 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.
|