@korzun/design 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +8 -0
  3. package/docs/component/card-divider.md +67 -0
  4. package/docs/component/card-row.md +58 -0
  5. package/docs/component/card.md +82 -0
  6. package/docs/component/collapsible-section.md +57 -0
  7. package/docs/component/empty-state.md +49 -0
  8. package/docs/component/meta-line.md +60 -0
  9. package/docs/component/metadata-list.md +60 -0
  10. package/docs/component/nav-desktop.md +62 -0
  11. package/docs/component/nav-mobile.md +82 -0
  12. package/docs/component/page.md +81 -0
  13. package/docs/component/progress-indicator.md +53 -0
  14. package/docs/component/tag.md +69 -0
  15. package/docs/component/theme-setting.md +58 -0
  16. package/docs/component/top-fade.md +60 -0
  17. package/docs/control/back-button.md +55 -0
  18. package/docs/control/button.md +78 -0
  19. package/docs/control/chips-input.md +77 -0
  20. package/docs/control/confirm-modal.md +68 -0
  21. package/docs/control/date-time-input.md +56 -0
  22. package/docs/control/field-list.md +66 -0
  23. package/docs/control/number-input.md +62 -0
  24. package/docs/control/page-actions-bar.md +64 -0
  25. package/docs/control/page-actions-menu.md +65 -0
  26. package/docs/control/page-footer-actions.md +69 -0
  27. package/docs/control/popover.md +74 -0
  28. package/docs/control/segmented-control.md +73 -0
  29. package/docs/control/select.md +86 -0
  30. package/docs/control/switch.md +73 -0
  31. package/docs/control/text-area.md +52 -0
  32. package/docs/control/text-input.md +73 -0
  33. package/docs/control/use-modal-dialog.md +76 -0
  34. package/docs/corners.md +68 -0
  35. package/docs/hooks.md +104 -0
  36. package/docs/icon.md +102 -0
  37. package/docs/patterns.md +116 -0
  38. package/docs/philosophy.md +91 -0
  39. package/docs/theme.md +96 -0
  40. package/docs/toast.md +85 -0
  41. package/docs/tokens.md +95 -0
  42. package/package.json +4 -1
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`.