@korzun/design 0.0.2 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +78 -0
- package/README.md +11 -1
- package/dist/component/index.d.ts +1 -1
- package/dist/component/index.d.ts.map +1 -1
- package/dist/component/index.js.map +1 -1
- package/dist/component/tag/index.d.ts +5 -2
- package/dist/component/tag/index.d.ts.map +1 -1
- package/dist/component/tag/index.js +2 -2
- package/dist/component/tag/index.js.map +1 -1
- package/dist/component/tag/style.d.ts +2 -1
- package/dist/component/tag/style.d.ts.map +1 -1
- package/dist/component/tag/style.js +21 -7
- package/dist/component/tag/style.js.map +1 -1
- package/dist/theme/theme.d.ts +5 -0
- package/dist/theme/theme.d.ts.map +1 -1
- package/dist/theme/theme.js +13 -1
- package/dist/theme/theme.js.map +1 -1
- package/docs/component/card-divider.md +67 -0
- package/docs/component/card-row.md +58 -0
- package/docs/component/card.md +82 -0
- package/docs/component/collapsible-section.md +57 -0
- package/docs/component/empty-state.md +49 -0
- package/docs/component/meta-line.md +60 -0
- package/docs/component/metadata-list.md +60 -0
- package/docs/component/nav-desktop.md +62 -0
- package/docs/component/nav-mobile.md +82 -0
- package/docs/component/page.md +81 -0
- package/docs/component/progress-indicator.md +53 -0
- package/docs/component/tag.md +69 -0
- package/docs/component/theme-setting.md +58 -0
- package/docs/component/top-fade.md +60 -0
- package/docs/control/back-button.md +55 -0
- package/docs/control/button.md +78 -0
- package/docs/control/chips-input.md +77 -0
- package/docs/control/confirm-modal.md +68 -0
- package/docs/control/date-time-input.md +56 -0
- package/docs/control/field-list.md +66 -0
- package/docs/control/number-input.md +62 -0
- package/docs/control/page-actions-bar.md +64 -0
- package/docs/control/page-actions-menu.md +65 -0
- package/docs/control/page-footer-actions.md +69 -0
- package/docs/control/popover.md +74 -0
- package/docs/control/segmented-control.md +73 -0
- package/docs/control/select.md +86 -0
- package/docs/control/switch.md +73 -0
- package/docs/control/text-area.md +52 -0
- package/docs/control/text-input.md +73 -0
- package/docs/control/use-modal-dialog.md +76 -0
- package/docs/corners.md +68 -0
- package/docs/hooks.md +104 -0
- package/docs/icon.md +102 -0
- package/docs/patterns.md +116 -0
- package/docs/philosophy.md +91 -0
- package/docs/theme.md +96 -0
- package/docs/toast.md +85 -0
- package/docs/tokens.md +95 -0
- package/package.json +7 -1
- package/src/component/index.ts +1 -1
- package/src/component/tag/index.tsx +7 -2
- package/src/component/tag/style.ts +27 -7
- package/src/theme/theme.ts +16 -1
|
@@ -0,0 +1,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.
|