@korzun/design 0.0.3 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +78 -0
- package/README.md +8 -0
- package/docs/component/card-divider.md +67 -0
- package/docs/component/card-row.md +58 -0
- package/docs/component/card.md +82 -0
- package/docs/component/collapsible-section.md +57 -0
- package/docs/component/empty-state.md +49 -0
- package/docs/component/meta-line.md +60 -0
- package/docs/component/metadata-list.md +60 -0
- package/docs/component/nav-desktop.md +62 -0
- package/docs/component/nav-mobile.md +82 -0
- package/docs/component/page.md +81 -0
- package/docs/component/progress-indicator.md +53 -0
- package/docs/component/tag.md +69 -0
- package/docs/component/theme-setting.md +58 -0
- package/docs/component/top-fade.md +60 -0
- package/docs/control/back-button.md +55 -0
- package/docs/control/button.md +78 -0
- package/docs/control/chips-input.md +77 -0
- package/docs/control/confirm-modal.md +68 -0
- package/docs/control/date-time-input.md +56 -0
- package/docs/control/field-list.md +66 -0
- package/docs/control/number-input.md +62 -0
- package/docs/control/page-actions-bar.md +64 -0
- package/docs/control/page-actions-menu.md +65 -0
- package/docs/control/page-footer-actions.md +69 -0
- package/docs/control/popover.md +74 -0
- package/docs/control/segmented-control.md +73 -0
- package/docs/control/select.md +86 -0
- package/docs/control/switch.md +73 -0
- package/docs/control/text-area.md +52 -0
- package/docs/control/text-input.md +73 -0
- package/docs/control/use-modal-dialog.md +76 -0
- package/docs/corners.md +68 -0
- package/docs/hooks.md +104 -0
- package/docs/icon.md +102 -0
- package/docs/patterns.md +116 -0
- package/docs/philosophy.md +91 -0
- package/docs/theme.md +96 -0
- package/docs/toast.md +85 -0
- package/docs/tokens.md +95 -0
- package/package.json +4 -1
package/AGENTS.md
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# @korzun/design: guide for coding agents
|
|
2
|
+
|
|
3
|
+
This package's API is **not in your training data**. Don't guess props from
|
|
4
|
+
other libraries such as MUI, Chakra, or shadcn. Before using a module, read its
|
|
5
|
+
doc in `docs/`. The doc paths below are relative to this file, so in a
|
|
6
|
+
consuming app they are under `node_modules/@korzun/design/`.
|
|
7
|
+
|
|
8
|
+
To load this guide in a consuming app, add this line to its `CLAUDE.md` or
|
|
9
|
+
`AGENTS.md`:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
@node_modules/@korzun/design/AGENTS.md
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Setup
|
|
16
|
+
|
|
17
|
+
- React 19 with react-jss. Peers: `react`, `react-dom`, `react-jss`, `classnames`,
|
|
18
|
+
`react-router`.
|
|
19
|
+
- Wrap the app once: `<ThemeProvider identity={userIdOrNull}><ToastProvider>…`.
|
|
20
|
+
`ThemeProvider` renders the global styles itself.
|
|
21
|
+
- Routing components (`BackButton`, `Page back`, the navs) need a react-router
|
|
22
|
+
router above them.
|
|
23
|
+
|
|
24
|
+
## Imports
|
|
25
|
+
|
|
26
|
+
| Import | Contents |
|
|
27
|
+
|---|---|
|
|
28
|
+
| `@korzun/design/theme` | `ThemeProvider`, `useTheme`, `useThemeSetting`, `createUseStyles`, `Theme`, `lightTheme`, `darkTheme` |
|
|
29
|
+
| `@korzun/design/control` | buttons, inputs, select, switch, segmented control, popover, `ConfirmModal`, `useModalDialog`, page actions |
|
|
30
|
+
| `@korzun/design/component` | `Page`, `Card` family, `EmptyState`, `Tag`, metadata, navs, `ThemeSetting`, `TopFade` |
|
|
31
|
+
| `@korzun/design/icon` | `*Icon` components, `IconProps` |
|
|
32
|
+
| `@korzun/design/toast` | `ToastProvider`, `useToast` |
|
|
33
|
+
| `@korzun/design/hooks` | `useMinimizeOnScroll`, `usePullToRefresh`, `isStandalone` |
|
|
34
|
+
| `@korzun/design` | everything above, flat, plus `applyTransparency`; the `ThemeSetting` type is renamed `ThemeSettingValue` here |
|
|
35
|
+
|
|
36
|
+
Import only from these entry points, never from `dist/…` or `src/…` paths.
|
|
37
|
+
|
|
38
|
+
## Rules
|
|
39
|
+
|
|
40
|
+
1. **Style with tokens only.** Use `createUseStyles((theme: Theme) => …)` in a
|
|
41
|
+
sibling `style.ts`. Colours, spacing, font sizes, radii, shadows, and z-index
|
|
42
|
+
all come from `theme.*`; use `applyTransparency(token, alpha)` for tints. No
|
|
43
|
+
literal hex, px, or rem values, no inline `style={{…}}` with literals, and no
|
|
44
|
+
other CSS-in-JS or Tailwind. See [theme](docs/theme.md).
|
|
45
|
+
2. **Corners follow depth.** On the page background use `lg`. Inside a card or
|
|
46
|
+
modal use `md`. Inside one of those use `sm`. A flush child takes its
|
|
47
|
+
parent's radius. Popovers, menus, and toasts use `md`, and their items `sm`.
|
|
48
|
+
Step down one token per level; don't subtract padding. Never write a
|
|
49
|
+
literal `borderRadius`. See [corners](docs/corners.md).
|
|
50
|
+
3. **Buttons take the surface they sit on:** `radius="card"` inside a Card,
|
|
51
|
+
`radius="modal"` in a modal footer, no `radius` on the page background.
|
|
52
|
+
4. **Button `type` is a visual variant** (`default`, `primary`, `text`, `link`,
|
|
53
|
+
`dashed`), not the HTML attribute. For a submit button use `submit` (and
|
|
54
|
+
`form="id"` when the button is outside its form). `onClick` is ignored on a
|
|
55
|
+
submit button. `danger` and `success` can't both be set.
|
|
56
|
+
5. **Icon props take components:** `prefix={SearchIcon}`, not
|
|
57
|
+
`prefix={<SearchIcon />}`.
|
|
58
|
+
6. **Screens are a `Page` holding a stack of `Card`s,** one per feature. Form
|
|
59
|
+
fields keep their default `horizontal` layout, and every field needs a
|
|
60
|
+
`name`. See [patterns](docs/patterns.md).
|
|
61
|
+
7. **Modals:** use `ConfirmModal` for yes/no. Build anything else on
|
|
62
|
+
`useModalDialog(isOpen, onDismiss, canDismiss)` with a native `<dialog>`
|
|
63
|
+
that stays mounted, and pass `canDismiss={!loading}`.
|
|
64
|
+
8. **Accessibility:** give repeated row actions an `ariaLabel` ("Remove
|
|
65
|
+
Kindle"). Don't wrap library controls in `<button>` or `<a>`; they are
|
|
66
|
+
already interactive.
|
|
67
|
+
9. **Overrides:** pass `className` where the module doc says it is accepted,
|
|
68
|
+
and win specificity with `'&&'`. Never use `!important`, and never target
|
|
69
|
+
internal class names.
|
|
70
|
+
10. **Missing pieces:** there is no `Stack`, `Text`, `Heading`, general
|
|
71
|
+
`Dialog`, `Tabs`, `Tooltip`, `Checkbox`, or `Alert` yet. Build them in app
|
|
72
|
+
code from tokens following these rules, and don't pull in another UI library.
|
|
73
|
+
|
|
74
|
+
## Docs index
|
|
75
|
+
|
|
76
|
+
[docs]|theme.md: provider, createUseStyles, token summary, recipes|corners.md: radius by nesting depth|patterns.md: screens, forms in cards, modals, overrides|tokens.md: every token key in detail|philosophy.md: design rules and why|icon.md|toast.md|hooks.md
|
|
77
|
+
[docs/control]|{back-button,button,chips-input,confirm-modal,date-time-input,field-list,number-input,page-actions-bar,page-actions-menu,page-footer-actions,popover,segmented-control,select,switch,text-area,text-input,use-modal-dialog}.md
|
|
78
|
+
[docs/component]|{card,card-divider,card-row,collapsible-section,empty-state,meta-line,metadata-list,nav-desktop,nav-mobile,page,progress-indicator,tag,theme-setting,top-fade}.md
|
package/README.md
CHANGED
|
@@ -58,6 +58,14 @@ export const Providers = ({ children }: { children: React.ReactNode }) => {
|
|
|
58
58
|
|
|
59
59
|
The root export is everything, flat. The `ThemeSetting` type is exported from the root as `ThemeSettingValue`, because the `ThemeSetting` component takes the name; from `@korzun/design/theme` it is still `ThemeSetting`.
|
|
60
60
|
|
|
61
|
+
## Coding agents
|
|
62
|
+
|
|
63
|
+
The package ships `AGENTS.md` and per-module docs in `docs/`, written for LLM coding agents. Point your app's agent at them by adding this line to its `CLAUDE.md` or `AGENTS.md`:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
@node_modules/@korzun/design/AGENTS.md
|
|
67
|
+
```
|
|
68
|
+
|
|
61
69
|
## Gallery
|
|
62
70
|
|
|
63
71
|
`npm run gallery` starts the story explorer on the LAN; `npm run gallery:build` writes a static copy to `gallery-dist/`. Every push to `main` deploys it to https://korzun.github.io/korzun-design/. It is for development only and is not published to npm.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# CardDivider
|
|
2
|
+
|
|
3
|
+
`import { CardDivider } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A horizontal rule that splits one `Card` body into sections, optionally with a
|
|
6
|
+
label ("Devices", "Validation") and/or actions sitting on the line. It is
|
|
7
|
+
full-bleed: it cancels the card body's padding so the line meets the card
|
|
8
|
+
borders. Renders `role="separator"`.
|
|
9
|
+
|
|
10
|
+
Use something else for: separating whole features (use separate `Card`s),
|
|
11
|
+
separating menu items (`PageActionItem.separatorBefore`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `children` | `ReactNode` | | Optional label. Without a label and without actions it is a plain full-width line. |
|
|
18
|
+
| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Label position. `left`/`right` hug that edge with a short stub of line poking past it; `center` leaves equal line on both sides. |
|
|
19
|
+
| `actions` | `ReactNode` | | Optional controls rendered on the line (e.g. a bulk-action button). |
|
|
20
|
+
| `actionsAlign` | `'left' \| 'center' \| 'right'` | `'right'` | Actions position. If it equals `align`, label and actions share one group, label first. |
|
|
21
|
+
|
|
22
|
+
No `className`. `null`, `undefined` and `false` count as absent for both
|
|
23
|
+
`children` and `actions`.
|
|
24
|
+
|
|
25
|
+
## Surprising behaviour
|
|
26
|
+
|
|
27
|
+
- **Assumes a `space.xl` parent padding.** The full-bleed is a fixed
|
|
28
|
+
`margin: 0 -space.xl`, which matches a `size="large"` Card body. Inside
|
|
29
|
+
`Card size="small"` (1px padding) or any other container it overhangs.
|
|
30
|
+
- It always reserves one label line of height, labelled or not, so swapping a
|
|
31
|
+
plain divider for a labelled one does not shift the layout.
|
|
32
|
+
- The label does not wrap (`white-space: nowrap`); keep it to a word or two.
|
|
33
|
+
- The exported type names `CardDividerProps` / `CardDividerAlign` are not
|
|
34
|
+
re-exported from the `component` barrel.
|
|
35
|
+
|
|
36
|
+
## Examples
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
// A plain rule between a form's fields and its submit button.
|
|
40
|
+
<Card title="New request">
|
|
41
|
+
<form action={create}>
|
|
42
|
+
<TextInput … />
|
|
43
|
+
<CardDivider />
|
|
44
|
+
<Button type="primary" radius="card" submit>Request</Button>
|
|
45
|
+
</form>
|
|
46
|
+
</Card>
|
|
47
|
+
|
|
48
|
+
// A labelled section inside a card.
|
|
49
|
+
<Card title="Notifications">
|
|
50
|
+
…
|
|
51
|
+
<CardDivider>Devices</CardDivider>
|
|
52
|
+
<ul>{devices.map(…)}</ul>
|
|
53
|
+
</Card>
|
|
54
|
+
|
|
55
|
+
// Label left, an action on the right end of the same line.
|
|
56
|
+
<CardDivider actions={<Button type="link" onClick={clearAll}>Clear all</Button>}>
|
|
57
|
+
Pending
|
|
58
|
+
</CardDivider>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Do / don't
|
|
62
|
+
|
|
63
|
+
- Do use it directly inside a large Card body, not wrapped in a padded `div`
|
|
64
|
+
(the negative margin would then overshoot your wrapper instead).
|
|
65
|
+
- Do use `type="link"` Buttons or small `Tag`s as `actions`; the line is one
|
|
66
|
+
text line tall.
|
|
67
|
+
- Don't use it for the gap between Cards on a page; `Page` already spaces them.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# CardRow
|
|
2
|
+
|
|
3
|
+
`import { CardRow, type CardRowProps } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A compact bordered row (card background, 6px padding) for stacking items inside
|
|
6
|
+
a `Card` body. Optionally clickable.
|
|
7
|
+
|
|
8
|
+
Use something else for: a list of rows each sitting on the page background
|
|
9
|
+
(Bookplate uses `<Card size="small" onClick>` per row), a section split
|
|
10
|
+
(`CardDivider`), a key/value line (`MetadataList`).
|
|
11
|
+
|
|
12
|
+
## Props
|
|
13
|
+
|
|
14
|
+
| Prop | Type | Default | Notes |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `children` | `ReactNode` | | Row content. |
|
|
17
|
+
| `onClick` | `() => void` | | Adds a pointer cursor; fires on click and on Enter/Space. See the keyboard caveat. |
|
|
18
|
+
|
|
19
|
+
No `className`, no `ariaLabel`, no `role`.
|
|
20
|
+
|
|
21
|
+
## Surprising behaviour
|
|
22
|
+
|
|
23
|
+
- **Not keyboard-reachable.** With `onClick` it still gets no `role="button"`
|
|
24
|
+
and no `tabIndex`, so it cannot be focused; the Enter/Space handler only
|
|
25
|
+
fires for keys bubbling from a focused child, and Space is not
|
|
26
|
+
`preventDefault`ed (the page scrolls). For a keyboard-accessible clickable
|
|
27
|
+
row, put a real control (`Button type="link"`) inside it.
|
|
28
|
+
- Bookplate itself does not use `CardRow`; it is the least-exercised layout
|
|
29
|
+
primitive here.
|
|
30
|
+
|
|
31
|
+
## Corners
|
|
32
|
+
|
|
33
|
+
Hard-codes `borderRadius: '12px'` (its own source comment says "10px"), off
|
|
34
|
+
the radius scale. By the [corner rule](../corners.md) a row inside a card
|
|
35
|
+
should be `radius.md`. Known inconsistency, don't copy the value.
|
|
36
|
+
|
|
37
|
+
## Examples
|
|
38
|
+
|
|
39
|
+
```tsx
|
|
40
|
+
<Card title="Recent uploads">
|
|
41
|
+
{uploads.map((u) => (
|
|
42
|
+
<CardRow key={u.id} onClick={() => open(u.id)}>
|
|
43
|
+
{u.fileName}
|
|
44
|
+
</CardRow>
|
|
45
|
+
))}
|
|
46
|
+
</Card>
|
|
47
|
+
|
|
48
|
+
// Accessible alternative: the action is a real control.
|
|
49
|
+
<CardRow>
|
|
50
|
+
{u.fileName} <Button type="link" onClick={() => open(u.id)} ariaLabel={`Open ${u.fileName}`}>Open</Button>
|
|
51
|
+
</CardRow>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Do / don't
|
|
55
|
+
|
|
56
|
+
- Do use it only inside a `Card` body.
|
|
57
|
+
- Don't rely on `onClick` as the only way to reach an action from the keyboard.
|
|
58
|
+
- Don't copy its 12px radius into your own styles; use `theme.radius.md`.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Card
|
|
2
|
+
|
|
3
|
+
`import { Card } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
The bordered surface every feature on a screen lives in: an optional header
|
|
6
|
+
(title, subtitle, header actions), a padded body, and an optional footer. A
|
|
7
|
+
screen is a `<Page>` holding a vertical stack of Cards, one per feature. It can
|
|
8
|
+
also be a whole clickable list row (`size="small"` with `onClick`).
|
|
9
|
+
|
|
10
|
+
Use something else for: a "nothing here" block on the bare page (`EmptyState`),
|
|
11
|
+
a disclosure section with no card chrome (`CollapsibleSection`), a modal
|
|
12
|
+
(`ConfirmModal` / `useModalDialog` in `@korzun/design/control`).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `children` | `ReactNode` | | Body. |
|
|
19
|
+
| `title` | `string \| ReactNode` | | Header title. |
|
|
20
|
+
| `subTitle` | `string` | | Small faint text after the title. |
|
|
21
|
+
| `headerAction` | `ReactNode \| ReactElement[]` | | Right side of the header. Clicks and keys here do **not** bubble to `onClick` / the collapse toggle. |
|
|
22
|
+
| `footer` | `ReactNode` | | Grey footer bar, children right-aligned. Clicks do not bubble to `onClick`. Hidden while a collapsible card is collapsed. |
|
|
23
|
+
| `size` | `'small' \| 'large'` | `'large'` | `large`: body padding `space.xl`. `small`: body padding `1px` and a 9px corner (see below). |
|
|
24
|
+
| `isCollapsible` | `boolean` | `false` | Header becomes a `role="button"` toggle (Enter/Space) with a rotating chevron before the title. |
|
|
25
|
+
| `defaultCollapsed` | `boolean` | **`true`** | **A collapsible card starts collapsed unless you pass `defaultCollapsed={false}`.** Uncontrolled; there is no `open` prop. |
|
|
26
|
+
| `onClick` | `() => void` | | Whole-card click; adds a pointer cursor. See the keyboard caveat below. |
|
|
27
|
+
| `onClickHeader` | `() => void` | | Header click. **Ignored when `isCollapsible`** (the header toggles instead). Its presence alone renders a header. |
|
|
28
|
+
| `className` | `string` | | On the outer element. Override with `'&&'` specificity in your sheet, never `!important`. |
|
|
29
|
+
|
|
30
|
+
The header renders only if one of `title`, `subTitle`, `headerAction`,
|
|
31
|
+
`onClickHeader`, or `isCollapsible` is set.
|
|
32
|
+
|
|
33
|
+
## Surprising behaviour
|
|
34
|
+
|
|
35
|
+
- **Keyboard on `onClick` is incomplete.** The root gets no `role` or
|
|
36
|
+
`tabIndex`, so it is not focusable; its `onKeyDown` fires `onClick` on
|
|
37
|
+
Enter/Space bubbling up from *any* focused child (an input inside a clickable
|
|
38
|
+
card triggers it). Don't put form fields inside a clickable card.
|
|
39
|
+
- A header click on a collapsible card bubbles to the root, so `isCollapsible`
|
|
40
|
+
together with `onClick` fires both.
|
|
41
|
+
- Collapsed content is unmounted, not hidden: child state resets on reopen.
|
|
42
|
+
|
|
43
|
+
## Corners
|
|
44
|
+
|
|
45
|
+
The shell uses `radius.lg`: a Card sits on the page background. Buttons inside
|
|
46
|
+
(body or footer) take `radius="card"`. See [corners](../corners.md).
|
|
47
|
+
`size="small"` hard-codes `borderRadius: '9px'`, off the radius scale: known
|
|
48
|
+
inconsistency, don't copy the value.
|
|
49
|
+
|
|
50
|
+
## Examples
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
// A settings feature: title, a header action, a form submitted from the footer.
|
|
54
|
+
<Card
|
|
55
|
+
title="Device password"
|
|
56
|
+
headerAction={<Button type="link" onClick={regenerate}>Regenerate</Button>}
|
|
57
|
+
footer={<Button type="primary" radius="card" submit form="device-pw">Save</Button>}
|
|
58
|
+
>
|
|
59
|
+
<form id="device-pw" action={save}>…</form>
|
|
60
|
+
</Card>
|
|
61
|
+
|
|
62
|
+
// A collapsible row whose destructive actions only show once opened.
|
|
63
|
+
<Card isCollapsible title={user.username} footer={<Button type="link" danger onClick={remove}>Delete user</Button>}>
|
|
64
|
+
<MetaLine items={[user.email, user.role]} />
|
|
65
|
+
</Card>
|
|
66
|
+
|
|
67
|
+
// A list row: one small clickable card per item.
|
|
68
|
+
<Card size="small" onClick={() => navigate(`/book/${book.id}`)}>
|
|
69
|
+
<BookSummary book={book} />
|
|
70
|
+
</Card>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Do / don't
|
|
74
|
+
|
|
75
|
+
- Do give each feature on a screen its own Card, stacked directly in `<Page>`.
|
|
76
|
+
- Do set `radius="card"` on Buttons inside a Card, except `type="link"`.
|
|
77
|
+
- Do put row actions that must not fire by accident in `footer` of a
|
|
78
|
+
collapsible card; they are unreachable while it is collapsed.
|
|
79
|
+
- Don't nest Cards; use `CardDivider` to split one card into sections.
|
|
80
|
+
- Don't expect `isCollapsible` cards to start open; pass `defaultCollapsed={false}`.
|
|
81
|
+
- Don't use the `Props` type from the module file; it is not exported from the
|
|
82
|
+
`component` barrel. Use `ComponentProps<typeof Card>`.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# CollapsibleSection
|
|
2
|
+
|
|
3
|
+
`import { CollapsibleSection } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A disclosure section with no card chrome: an uppercase, muted header row with a
|
|
6
|
+
text chevron (▶ / ▼), an optional count-style subtitle, optional trailing
|
|
7
|
+
actions, and children shown only while open. The header is a
|
|
8
|
+
`role="button"` (`tabIndex=0`, Enter/Space).
|
|
9
|
+
|
|
10
|
+
Use something else for: a collapsible feature on a screen (`Card` with
|
|
11
|
+
`isCollapsible`, which also hides its footer while collapsed).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `title` | `string` | required | Rendered uppercase via CSS. |
|
|
18
|
+
| `subTitle` | `string` | | Faint text after the title, e.g. a count ("3 items"). |
|
|
19
|
+
| `children` | `ReactNode` | | Rendered only while open (unmounted when closed). |
|
|
20
|
+
| `actions` | `ReactNode[]` | `[]` | Rendered at the right end of the header. **An array**, not a single node. |
|
|
21
|
+
| `open` | `boolean` | | Controlled open state. Omit for uncontrolled (starts closed). |
|
|
22
|
+
| `onOpenToggle` | `() => void` | no-op | Called on every header click/Enter/Space. **Receives no value**; flip your own state. |
|
|
23
|
+
|
|
24
|
+
No `className`.
|
|
25
|
+
|
|
26
|
+
## Surprising behaviour
|
|
27
|
+
|
|
28
|
+
- **Actions toggle the section.** They are rendered inside the header button
|
|
29
|
+
with no `stopPropagation`, so clicking an action also opens/closes the
|
|
30
|
+
section. Stop propagation in your action's handler if that is unwanted.
|
|
31
|
+
- Actions in the array need their own `key`s (they are rendered as a bare
|
|
32
|
+
array).
|
|
33
|
+
- The header has no `aria-expanded`.
|
|
34
|
+
- When controlled, `open` wins but internal state still flips on every click;
|
|
35
|
+
if you later stop passing `open`, the section shows that stale internal state.
|
|
36
|
+
- Uncontrolled sections always start closed; there is no `defaultOpen`.
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
// Uncontrolled.
|
|
42
|
+
<CollapsibleSection title="Archived" subTitle={`${archived.length}`}>
|
|
43
|
+
{archived.map((a) => <ArchivedRow key={a.id} item={a} />)}
|
|
44
|
+
</CollapsibleSection>
|
|
45
|
+
|
|
46
|
+
// Controlled.
|
|
47
|
+
const [open, setOpen] = useState(false);
|
|
48
|
+
<CollapsibleSection title="Advanced" open={open} onOpenToggle={() => setOpen((o) => !o)}>
|
|
49
|
+
…
|
|
50
|
+
</CollapsibleSection>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Do / don't
|
|
54
|
+
|
|
55
|
+
- Do pass `actions` as an array of keyed elements.
|
|
56
|
+
- Do stop click propagation inside actions that must not toggle the section.
|
|
57
|
+
- Don't use it as a screen's top-level feature container; that is `Card`.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# EmptyState
|
|
2
|
+
|
|
3
|
+
`import { EmptyState } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
The centred "nothing here" block a screen shows in place of a list: a title
|
|
6
|
+
line and an optional faint second line, with generous vertical padding
|
|
7
|
+
(`4rem`). Also used for a list's loading and error states.
|
|
8
|
+
|
|
9
|
+
Use something else for: an empty message *inside* a `Card` (a plain
|
|
10
|
+
left-aligned line of card content reads right there), transient feedback
|
|
11
|
+
(`useToast`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `title` | `string` | required | The one line that says what is not here. |
|
|
18
|
+
| `children` | `ReactNode` | | Optional second line: what to do about it, or why it is empty. Rendered only when not `undefined`. |
|
|
19
|
+
| `danger` | `boolean` | `false` | Tints the title red. For a load **failure**, not for an honestly empty list. |
|
|
20
|
+
|
|
21
|
+
No `className`. Renders plain `div`s with no `role`; it is not a live region.
|
|
22
|
+
|
|
23
|
+
## Examples
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
let list;
|
|
27
|
+
if (loading) {
|
|
28
|
+
list = <EmptyState title="Loading..." />;
|
|
29
|
+
} else if (error && rows.length === 0) {
|
|
30
|
+
list = <EmptyState title="Error loading requests" danger />;
|
|
31
|
+
} else if (rows.length === 0) {
|
|
32
|
+
list = <EmptyState title="No requests yet">Fill in the form above to ask for a book.</EmptyState>;
|
|
33
|
+
} else {
|
|
34
|
+
list = rows.map((r) => <RequestRow key={r.id} row={r} />);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
<Page>
|
|
38
|
+
<Card title="New request">…</Card>
|
|
39
|
+
{list}
|
|
40
|
+
</Page>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Do / don't
|
|
44
|
+
|
|
45
|
+
- Do use it directly on the page background, as a sibling of the Cards.
|
|
46
|
+
- Do keep `title` short; put the explanation or next step in `children`.
|
|
47
|
+
- Don't set `danger` for "no results"; that is not an error.
|
|
48
|
+
- Don't pass `null` as `children` expecting no second line: only `undefined`
|
|
49
|
+
omits it (`null` renders an empty second line).
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# MetaLine
|
|
2
|
+
|
|
3
|
+
`import { MetaLine, type MetaLineProps } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A row's secondary line: a few short data ("Frank Herbert", "Book 3", "42%")
|
|
6
|
+
separated by middots. When too narrow, it wraps *between* data, never inside
|
|
7
|
+
one, and never leaves a separator dangling at a line end or leading the next
|
|
8
|
+
line. The separators are CSS (`::before`), not text, so screen readers read
|
|
9
|
+
only the data.
|
|
10
|
+
|
|
11
|
+
Use something else for: labelled key/value pairs (`MetadataList`), a row's
|
|
12
|
+
primary title (your own styled element).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `items` | `ReactNode[]` | required | The data, in order. `null`, `undefined` and `false` entries are skipped. |
|
|
19
|
+
| `className` | `string` | | On the outer element; the font size and colour you set there reach every item and the separators scale with it (`1em` cells). Override with `'&&'` specificity, never `!important`. |
|
|
20
|
+
|
|
21
|
+
## Surprising behaviour
|
|
22
|
+
|
|
23
|
+
- **Renders `null`** when every item is skipped: no empty line is left behind.
|
|
24
|
+
- Only `null`/`undefined`/`false` are skipped. `''` and `0` are kept and draw a
|
|
25
|
+
separator with nothing (or `0`) after it; filter them yourself.
|
|
26
|
+
- A single datum wider than the line ellipsizes instead of wrapping.
|
|
27
|
+
- MetaLine sets no font size or colour of its own except the separator colour
|
|
28
|
+
(`text.muted`); style the line via `className`.
|
|
29
|
+
- Items are keyed by index.
|
|
30
|
+
|
|
31
|
+
## Examples
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
// A book row's secondary line.
|
|
35
|
+
<div className={styles.title}>{book.title}</div>
|
|
36
|
+
<MetaLine
|
|
37
|
+
items={[
|
|
38
|
+
book.author,
|
|
39
|
+
book.series && `${book.series.name} #${book.seriesIndex}`,
|
|
40
|
+
book.progress !== undefined && `${Math.round(book.progress * 100)}%`,
|
|
41
|
+
]}
|
|
42
|
+
className={styles.meta}
|
|
43
|
+
/>
|
|
44
|
+
|
|
45
|
+
// Elements are fine as items.
|
|
46
|
+
<MetaLine items={[<time dateTime={iso}>{formatted}</time>, device.label]} />
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
// The sheet for `className`: size and colour for the whole line.
|
|
51
|
+
meta: { fontSize: theme.fontSize.sm, color: theme.color.text.faint },
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Do / don't
|
|
55
|
+
|
|
56
|
+
- Do pass conditional data as `cond && value`; `false` is skipped.
|
|
57
|
+
- Do set typography through `className`.
|
|
58
|
+
- Don't join data into one string with your own " · ": wrapping then breaks
|
|
59
|
+
inside a datum and the dots are read aloud.
|
|
60
|
+
- Don't pass empty strings; they leave a stray separator.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# MetadataList
|
|
2
|
+
|
|
3
|
+
`import { MetadataList, type Metadata } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A wrapping row of small labelled values ("Slug my-kindle", "Cover fit
|
|
6
|
+
Contain"): each pair is a faint, capitalized title followed by its value, laid
|
|
7
|
+
out inline with `space.lg` between pairs and `space.sm` between wrapped lines.
|
|
8
|
+
Typically the body of a `Card` describing one record.
|
|
9
|
+
|
|
10
|
+
Use something else for: unlabelled secondary data on a row (`MetaLine`),
|
|
11
|
+
editable fields (controls in `@korzun/design/control`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `metadata` | `Metadata[]` | required | `Metadata` is `{ title: string; value: string \| ReactNode }`. |
|
|
18
|
+
|
|
19
|
+
No `className`.
|
|
20
|
+
|
|
21
|
+
## Surprising behaviour
|
|
22
|
+
|
|
23
|
+
- **Title is CSS `text-transform: capitalize`:** "cover fit" displays as
|
|
24
|
+
"Cover Fit". Write titles in the case you want only if that agrees.
|
|
25
|
+
- **Each value is truncated** to `theme.size.metadataValue` (`15rem`) with an
|
|
26
|
+
ellipsis and never wraps (`white-space: nowrap`). Long values are cut off;
|
|
27
|
+
there is no tooltip.
|
|
28
|
+
- **Keys are `title + value`.** With an element as `value` the key becomes
|
|
29
|
+
`"Title[object Object]"`, so two entries with the same title and element
|
|
30
|
+
values collide (React key warning, possible wrong reconciliation). Keep
|
|
31
|
+
titles unique.
|
|
32
|
+
- Every entry renders, including ones whose value is `null`/`undefined`
|
|
33
|
+
(title with an empty value). Filter the array first.
|
|
34
|
+
- Its building block (`Metadata` component) is internal; only the `Metadata`
|
|
35
|
+
**type** is exported.
|
|
36
|
+
|
|
37
|
+
## Examples
|
|
38
|
+
|
|
39
|
+
```tsx
|
|
40
|
+
<Card
|
|
41
|
+
title={device.name}
|
|
42
|
+
headerAction={<Button type="link" onClick={edit}>Edit</Button>}
|
|
43
|
+
>
|
|
44
|
+
<MetadataList
|
|
45
|
+
metadata={[
|
|
46
|
+
{ title: 'Slug', value: device.slug },
|
|
47
|
+
{ title: 'Cover size', value: `${device.coverWidth}×${device.coverHeight}` },
|
|
48
|
+
{ title: 'Grayscale cover', value: device.bwCover ? 'Yes' : 'No' },
|
|
49
|
+
{ title: 'Status', value: <Tag size="sm" tone="status">Active</Tag> },
|
|
50
|
+
]}
|
|
51
|
+
/>
|
|
52
|
+
</Card>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Do / don't
|
|
56
|
+
|
|
57
|
+
- Do keep values short (a word, a number, a small `Tag size="sm"`).
|
|
58
|
+
- Do keep `title`s unique within one list.
|
|
59
|
+
- Don't use it for long text such as descriptions; it truncates at 15rem.
|
|
60
|
+
- Don't include entries with missing values; filter them out.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# NavDesktop
|
|
2
|
+
|
|
3
|
+
`import { NavDesktop, type NavDesktopProps, type NavItem } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
The app's top navigation on wide screens: a centred row of icon + label links
|
|
6
|
+
on the page background, the active one underlined. Hidden below the mobile
|
|
7
|
+
breakpoint (`max-width: 640px`), so render it alongside `NavMobile` and let CSS
|
|
8
|
+
pick. Each item is a react-router `<Link>`, so it **must render inside a
|
|
9
|
+
router**.
|
|
10
|
+
|
|
11
|
+
Use something else for: mobile navigation (`NavMobile`), in-page tabs or a
|
|
12
|
+
mode switch (`SegmentedControl`), page-level actions (`Page` `headerActions`).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `items` | `NavItem[]` | required | Rendered in order; keyed by `to`, so `to` must be unique. |
|
|
19
|
+
|
|
20
|
+
`NavItem` (shared with `NavMobile`):
|
|
21
|
+
|
|
22
|
+
| Field | Type | Notes |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `to` | `string` | Route path passed to `<Link to>`. |
|
|
25
|
+
| `label` | `string` | Visible text. |
|
|
26
|
+
| `Icon` | `(props: IconProps) => ReactElement` | An icon **component** (`HomeIcon`), drawn at 14×14. |
|
|
27
|
+
| `active` | `boolean` | **You compute this** (e.g. from `useLocation().pathname`); the nav does not match routes. Sets `aria-current="page"` and the underline. |
|
|
28
|
+
| `badge` | `number \| 'dot'` | Optional. A positive number draws a red count on the icon's corner; `'dot'` a red dot ("active, nothing to decide yet"). `0` draws nothing. |
|
|
29
|
+
|
|
30
|
+
No `className`.
|
|
31
|
+
|
|
32
|
+
## Surprising behaviour
|
|
33
|
+
|
|
34
|
+
- It is **not** fixed or sticky (despite its source comment); it is a normal
|
|
35
|
+
`<header>` in flow at the top of the document, so render it before your
|
|
36
|
+
routes' content.
|
|
37
|
+
- Badges are visual only: the count has no accessible label, and a dot has no
|
|
38
|
+
text at all. Put the meaning in `label` if it matters to screen readers.
|
|
39
|
+
|
|
40
|
+
## Examples
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
const { pathname } = useLocation();
|
|
44
|
+
const items: NavItem[] = [
|
|
45
|
+
{ to: '/library', label: 'Library', Icon: BookIcon, active: pathname.startsWith('/library') },
|
|
46
|
+
{ to: '/upload', label: 'Upload', Icon: UploadIcon, active: pathname === '/upload', badge: pendingFixes || undefined },
|
|
47
|
+
{ to: '/settings', label: 'Settings', Icon: SettingsIcon, active: pathname === '/settings' },
|
|
48
|
+
];
|
|
49
|
+
|
|
50
|
+
// In the layout route, above <Outlet />.
|
|
51
|
+
<NavDesktop items={items} />
|
|
52
|
+
<NavMobile main={{ items, collapsed: items[0] }} settings={…} expanded="main" />
|
|
53
|
+
<Outlet />
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Do / don't
|
|
57
|
+
|
|
58
|
+
- Do render both `NavDesktop` and `NavMobile`; each hides itself at the other's
|
|
59
|
+
breakpoint.
|
|
60
|
+
- Do derive `active` from the current route in one place and share the items.
|
|
61
|
+
- Don't pass an element as `Icon` (`Icon: <HomeIcon />`); pass the component.
|
|
62
|
+
- Don't render it outside a react-router `Router`.
|