@korzun/design 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +11 -1
  3. package/dist/component/index.d.ts +1 -1
  4. package/dist/component/index.d.ts.map +1 -1
  5. package/dist/component/index.js.map +1 -1
  6. package/dist/component/tag/index.d.ts +5 -2
  7. package/dist/component/tag/index.d.ts.map +1 -1
  8. package/dist/component/tag/index.js +2 -2
  9. package/dist/component/tag/index.js.map +1 -1
  10. package/dist/component/tag/style.d.ts +2 -1
  11. package/dist/component/tag/style.d.ts.map +1 -1
  12. package/dist/component/tag/style.js +21 -7
  13. package/dist/component/tag/style.js.map +1 -1
  14. package/dist/theme/theme.d.ts +5 -0
  15. package/dist/theme/theme.d.ts.map +1 -1
  16. package/dist/theme/theme.js +13 -1
  17. package/dist/theme/theme.js.map +1 -1
  18. package/docs/component/card-divider.md +67 -0
  19. package/docs/component/card-row.md +58 -0
  20. package/docs/component/card.md +82 -0
  21. package/docs/component/collapsible-section.md +57 -0
  22. package/docs/component/empty-state.md +49 -0
  23. package/docs/component/meta-line.md +60 -0
  24. package/docs/component/metadata-list.md +60 -0
  25. package/docs/component/nav-desktop.md +62 -0
  26. package/docs/component/nav-mobile.md +82 -0
  27. package/docs/component/page.md +81 -0
  28. package/docs/component/progress-indicator.md +53 -0
  29. package/docs/component/tag.md +69 -0
  30. package/docs/component/theme-setting.md +58 -0
  31. package/docs/component/top-fade.md +60 -0
  32. package/docs/control/back-button.md +55 -0
  33. package/docs/control/button.md +78 -0
  34. package/docs/control/chips-input.md +77 -0
  35. package/docs/control/confirm-modal.md +68 -0
  36. package/docs/control/date-time-input.md +56 -0
  37. package/docs/control/field-list.md +66 -0
  38. package/docs/control/number-input.md +62 -0
  39. package/docs/control/page-actions-bar.md +64 -0
  40. package/docs/control/page-actions-menu.md +65 -0
  41. package/docs/control/page-footer-actions.md +69 -0
  42. package/docs/control/popover.md +74 -0
  43. package/docs/control/segmented-control.md +73 -0
  44. package/docs/control/select.md +86 -0
  45. package/docs/control/switch.md +73 -0
  46. package/docs/control/text-area.md +52 -0
  47. package/docs/control/text-input.md +73 -0
  48. package/docs/control/use-modal-dialog.md +76 -0
  49. package/docs/corners.md +68 -0
  50. package/docs/hooks.md +104 -0
  51. package/docs/icon.md +102 -0
  52. package/docs/patterns.md +116 -0
  53. package/docs/philosophy.md +91 -0
  54. package/docs/theme.md +96 -0
  55. package/docs/toast.md +85 -0
  56. package/docs/tokens.md +95 -0
  57. package/package.json +7 -1
  58. package/src/component/index.ts +1 -1
  59. package/src/component/tag/index.tsx +7 -2
  60. package/src/component/tag/style.ts +27 -7
  61. package/src/theme/theme.ts +16 -1
@@ -0,0 +1,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`.
@@ -0,0 +1,82 @@
1
+ # NavMobile
2
+
3
+ `import { NavMobile, type NavMobileProps, type NavPill, type NavItem } from '@korzun/design/component'`
4
+
5
+ The app's bottom navigation on phones: a `position: fixed` bar floating above
6
+ the bottom edge, holding two frosted-glass pills. The **expanded** side is a
7
+ capsule of tabs with a glass lens sliding to the active one; the other side is
8
+ a circle that links to a single destination. Scrolling down fast minimizes the
9
+ expanded side to a circle too (iOS-tab-bar style); scrolling up, reaching the
10
+ top, tapping the circle, or a route change brings it back. Hidden at
11
+ `min-width: 641px`, so render it alongside `NavDesktop`. Uses react-router
12
+ `Link` and `useLocation`, so it **must render inside a router**.
13
+
14
+ Use something else for: desktop navigation (`NavDesktop`), page actions
15
+ (`Page` `headerActions` / `footerActions`).
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Notes |
20
+ |---|---|---|---|
21
+ | `main` | `NavPill` | required | Left side: the app's main destinations. |
22
+ | `settings` | `NavPill` | required | Right side: settings (or an account/admin group). |
23
+ | `expanded` | `'main' \| 'settings'` | required | Which side is the capsule; the other is a circle. Derive it from the route. |
24
+
25
+ `NavPill` is `{ items: NavItem[]; collapsed: NavItem }`:
26
+
27
+ - `items`: the tabs shown while that side is expanded. `[]` makes the side
28
+ permanently a circle (Bookplate does this for a non-admin's settings side).
29
+ - `collapsed`: the one destination the circle links to. Its `label` becomes the
30
+ circle's `aria-label`, its `Icon` is drawn at 18px, its `badge` shows only
31
+ while the side is actually collapsed, and its `active` lights the circle.
32
+
33
+ `NavItem` fields (`to`, `label`, `Icon`, `active`, `badge`) are documented in
34
+ [NavDesktop](nav-desktop.md); tab icons are drawn at 14px. No `className`.
35
+
36
+ ## Surprising behaviour
37
+
38
+ - **The page must make room for it:** pass `bottomNav` to every `<Page>` that
39
+ shows this bar, or the last rows sit under it. Toasts already clear it on
40
+ mobile.
41
+ - Tabs are equal-width columns sized to the widest label. Five short labels fit
42
+ at 320px; six do not (Bookplate measured "Library"/"Settings" clipping), so
43
+ move extra destinations into the other side.
44
+ - The minimized circle is a `<button aria-label="Show navigation">`, not a
45
+ link: tapping it only re-expands the bar. It shows the active tab's icon (or
46
+ `collapsed.Icon` when no tab is active) and the active tab's badge, else a
47
+ dot if any hidden sibling has a badge.
48
+ - Minimizing only reacts to user-driven scroll (after a touch or wheel on this
49
+ route), so scroll restoration on navigation never minimizes it. Tuning
50
+ constants live in [hooks](../hooks.md) (`MINIMIZE_SPEED`, `EXPAND_AFTER`).
51
+ - Hidden shapes are `inert` and `aria-hidden`; only what is on screen is in
52
+ the tab order.
53
+
54
+ ## Examples
55
+
56
+ ```tsx
57
+ const { pathname } = useLocation();
58
+ const main: NavItem[] = [
59
+ { to: '/library', label: 'Library', Icon: BookIcon, active: pathname.startsWith('/library') },
60
+ { to: '/upload', label: 'Upload', Icon: UploadIcon, active: pathname === '/upload', badge: count || undefined },
61
+ { to: '/request', label: 'Request', Icon: ListCheckIcon, active: pathname === '/request' },
62
+ ];
63
+ const settingsItems: NavItem[] = [
64
+ { to: '/settings', label: 'General', Icon: AdjustmentsHorizontalIcon, active: pathname === '/settings' },
65
+ { to: '/users', label: 'Users', Icon: UsersIcon, active: pathname === '/users' },
66
+ ];
67
+ const inSettings = pathname === '/settings' || pathname === '/users';
68
+
69
+ <NavMobile
70
+ main={{ items: main, collapsed: { to: '/library', label: 'Back to library', Icon: HomeIcon, active: false } }}
71
+ settings={{ items: settingsItems, collapsed: { to: '/settings', label: 'Settings', Icon: SettingsIcon, active: pathname === '/settings' } }}
72
+ expanded={inSettings ? 'settings' : 'main'}
73
+ />
74
+ ```
75
+
76
+ ## Do / don't
77
+
78
+ - Do render it once, in the layout route, next to `NavDesktop`.
79
+ - Do set `bottomNav` on each `Page` under that layout.
80
+ - Do drive `expanded` from the URL so Back behaves.
81
+ - Don't keep more than about five tabs on one side.
82
+ - Don't also call `useMinimizeOnScroll` for the same bar; NavMobile owns it.
@@ -0,0 +1,81 @@
1
+ # Page
2
+
3
+ `import { Page } from '@korzun/design/component'`
4
+
5
+ The `<main>` of every screen: a centred 800px column (gutter `space.xxl`) that
6
+ stacks its children vertically with a fixed gap. A screen is a `Page` holding a
7
+ vertical stack of `Card`s, one per feature. Page also owns the screen's chrome:
8
+ the mobile back button, the header actions (a bar on desktop, a floating `⋯`
9
+ menu on mobile), and sticky footer actions.
10
+
11
+ Use something else for: a sign-in or splash screen with no chrome
12
+ (`type="minimal"` here, then lay it out yourself), a section inside a screen
13
+ (`Card`).
14
+
15
+ ## Props
16
+
17
+ | Prop | Type | Default | Notes |
18
+ |---|---|---|---|
19
+ | `children` | `ReactNode` | | The Card stack. Direct children get the column gap. |
20
+ | `type` | `'default' \| 'minimal'` | `'default'` | `minimal` drops all layout styles (no width, margin, padding, gap) and the header row. |
21
+ | `back` | `string` | | Route path for the back button. **Mobile only**: there is no back button on desktop. Navigates with `state: { restoreScroll: true }` (needs a react-router router). |
22
+ | `headerActions` | `PageActionItem[]` | | Page-level actions (type from `@korzun/design/control`). Desktop: items with `primary: true` render as buttons, the rest in a "More…" overflow menu. Mobile: all in a floating menu. |
23
+ | `actionsLabel` | `string` | `'More…'` | Label of the desktop overflow trigger. |
24
+ | `header` | `ReactNode` | | Page's own header-row content (a search bar, a mode toggle), leading the desktop actions bar in the same row. Ignored on `minimal`. |
25
+ | `footerActions` | `FooterAction[]` | | Sticky footer buttons (type from `@korzun/design/control`): `{ label, onClick, disabled?, loading?, danger?, emphasis?, align?, submit?, form? }`. |
26
+ | `documentTitle` | `string` | | Sets `document.title`. **Not restored on unmount.** Omit when the app manages titles. |
27
+ | `bottomNav` | `boolean` | `false` | Mobile: extra bottom padding to clear a floating `NavMobile`. |
28
+
29
+ No `className`.
30
+
31
+ ## Surprising behaviour
32
+
33
+ - **The header row is always reserved on default pages**, even with no actions
34
+ and no `header` (min-height `2.25rem` on desktop), so content starts at the
35
+ same height on every page. On mobile the row collapses (`display: contents`).
36
+ - On mobile the back button and the actions menu sit in a **sticky** row at the
37
+ top that rides up with the page and then pins (at
38
+ `theme.layout.floatingControlTopBase`); it also renders on `minimal` pages
39
+ if you pass `back` or `headerActions`.
40
+ - The column gap is `theme.fontSize.md` (0.875rem), a historical value, not a
41
+ `space` token.
42
+ - `PageActionItem` and `FooterAction` are exported from
43
+ `@korzun/design/control`, not from `component`.
44
+
45
+ ## Examples
46
+
47
+ ```tsx
48
+ // A settings screen: one Card per feature, plus a page-level button.
49
+ <Page bottomNav documentTitle="Settings">
50
+ <ThemeSetting />
51
+ <Card title="Device password">…</Card>
52
+ <Card title="Change password">…</Card>
53
+ <Button danger onClick={logOut}>Log out</Button>
54
+ </Page>
55
+
56
+ // A detail screen with back, actions and a search-style header slot.
57
+ <Page
58
+ bottomNav
59
+ back="/library"
60
+ header={<LibrarySearch value={q} onChange={setQ} />} // your own component
61
+ headerActions={[
62
+ { label: 'Edit', onClick: edit, primary: true },
63
+ { label: 'Delete', onClick: confirmDelete, danger: true, separatorBefore: true },
64
+ ]}
65
+ >
66
+ <Card title={book.title}>…</Card>
67
+ </Page>
68
+
69
+ // Sign-in: no chrome.
70
+ <Page type="minimal"><LoginLayout /></Page>
71
+ ```
72
+
73
+ ## Do / don't
74
+
75
+ - Do make each feature its own `Card`, as direct children of `Page`.
76
+ - Do pass `bottomNav` on every page shown under `NavMobile`.
77
+ - Do mark the one or two main actions `primary: true` so desktop shows them as
78
+ buttons rather than burying them in "More…".
79
+ - Don't render your own search bar as the first child; use `header`.
80
+ - Don't wrap Page in another `<main>`; it is the `<main>`.
81
+ - Don't rely on `back` for desktop navigation.
@@ -0,0 +1,53 @@
1
+ # ProgressIndicator
2
+
3
+ `import { ProgressIndicator } from '@korzun/design/component'`
4
+
5
+ A small pie-style progress mark (a brand-coloured sector inside a ring) followed
6
+ by a text label: "Not started" at 0, "N%" in between, "Completed" at 100%. The
7
+ SVG is a `role="progressbar"` with `aria-valuenow` 0–100.
8
+
9
+ Use something else for: an indeterminate wait (`SpinnerIcon`, or `loading` on
10
+ a `Button`), a pull-to-refresh indicator (`usePullToRefresh`).
11
+
12
+ ## Props
13
+
14
+ | Prop | Type | Default | Notes |
15
+ |---|---|---|---|
16
+ | `value` | `number` | required | **A fraction from 0 to 1, not a percentage.** `0.42` shows "42%". Clamped to 0–1. |
17
+ | `ariaLabel` | `string` | required | Accessible name of the progressbar: say what progress it is (`Reading progress for ${title}`). A bare "42%" means nothing out of context. |
18
+ | `size` | `number` | `40` | Width and height of the SVG in px. The label's font size is fixed (`fontSize.sm`) regardless. |
19
+
20
+ No `className`.
21
+
22
+ ## Surprising behaviour
23
+
24
+ - **No SVG at exactly 0 or 1**: only the text label renders, so there is then
25
+ no `role="progressbar"` and `ariaLabel` is not used. The visible text
26
+ ("Not started" / "Completed") carries the meaning.
27
+ - The label is `Math.round`ed, so values just inside the range show "0%" or
28
+ "100%" next to a sliver or near-full pie (e.g. `0.996` shows "100%", not
29
+ "Completed").
30
+ - Passing a percentage (`42`) clamps to 1 and shows "Completed".
31
+
32
+ ## Examples
33
+
34
+ ```tsx
35
+ // In a row, inline with text: Bookplate draws it at 14px.
36
+ <div className={styles.progress}>
37
+ <ProgressIndicator
38
+ value={row.percentage} // 0..1
39
+ ariaLabel={`Reading progress for ${bookTitle}`}
40
+ size={14}
41
+ />
42
+ </div>
43
+
44
+ // Converting from a 0–100 API value.
45
+ <ProgressIndicator value={api.percent / 100} ariaLabel="Upload progress" />
46
+ ```
47
+
48
+ ## Do / don't
49
+
50
+ - Do pass a 0–1 fraction.
51
+ - Do write an `ariaLabel` that names the thing in progress.
52
+ - Don't render your own "42%" next to it; it already prints the label.
53
+ - Don't use it for indeterminate loading.