@korzun/design 0.0.3 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +78 -0
- package/README.md +8 -0
- package/docs/component/card-divider.md +67 -0
- package/docs/component/card-row.md +58 -0
- package/docs/component/card.md +82 -0
- package/docs/component/collapsible-section.md +57 -0
- package/docs/component/empty-state.md +49 -0
- package/docs/component/meta-line.md +60 -0
- package/docs/component/metadata-list.md +60 -0
- package/docs/component/nav-desktop.md +62 -0
- package/docs/component/nav-mobile.md +82 -0
- package/docs/component/page.md +81 -0
- package/docs/component/progress-indicator.md +53 -0
- package/docs/component/tag.md +69 -0
- package/docs/component/theme-setting.md +58 -0
- package/docs/component/top-fade.md +60 -0
- package/docs/control/back-button.md +55 -0
- package/docs/control/button.md +78 -0
- package/docs/control/chips-input.md +77 -0
- package/docs/control/confirm-modal.md +68 -0
- package/docs/control/date-time-input.md +56 -0
- package/docs/control/field-list.md +66 -0
- package/docs/control/number-input.md +62 -0
- package/docs/control/page-actions-bar.md +64 -0
- package/docs/control/page-actions-menu.md +65 -0
- package/docs/control/page-footer-actions.md +69 -0
- package/docs/control/popover.md +74 -0
- package/docs/control/segmented-control.md +73 -0
- package/docs/control/select.md +86 -0
- package/docs/control/switch.md +73 -0
- package/docs/control/text-area.md +52 -0
- package/docs/control/text-input.md +73 -0
- package/docs/control/use-modal-dialog.md +76 -0
- package/docs/corners.md +68 -0
- package/docs/hooks.md +104 -0
- package/docs/icon.md +102 -0
- package/docs/patterns.md +116 -0
- package/docs/philosophy.md +91 -0
- package/docs/theme.md +96 -0
- package/docs/toast.md +85 -0
- package/docs/tokens.md +95 -0
- package/package.json +4 -1
|
@@ -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.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Tag
|
|
2
|
+
|
|
3
|
+
`import { Tag, type TagTone } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A small coloured chip (an inline `<span>`) for a category, status, or value:
|
|
6
|
+
an author, a subject, "Read only". Optionally clickable, in which case it
|
|
7
|
+
becomes `role="button"` with `tabIndex=0` and Enter/Space.
|
|
8
|
+
|
|
9
|
+
Use something else for: an editable list of chips (`ChipsInput` in
|
|
10
|
+
`@korzun/design/control`), an action (`Button`), a count on a nav tab
|
|
11
|
+
(`NavItem.badge`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `children` | `ReactNode` | required | Label. |
|
|
18
|
+
| `tone` | `TagTone` | `'subject'` | Colour, from `theme.color.chip`. See below. |
|
|
19
|
+
| `size` | `'sm' \| 'md'` | `'md'` | `sm` is compact (tight line height) and fits inside a normal text line, so rows keep the same height with or without chips. |
|
|
20
|
+
| `onClick` | `() => void` | | Makes it a button: pointer cursor, focusable, hover deepens the tone. Receives no event. |
|
|
21
|
+
|
|
22
|
+
No `className`, no `ariaLabel`.
|
|
23
|
+
|
|
24
|
+
## Choosing a tone
|
|
25
|
+
|
|
26
|
+
`TagTone` is `keyof Theme['color']['chip']`, so the tones are **domain names**,
|
|
27
|
+
not colour names. Pick by what the tag *is*:
|
|
28
|
+
|
|
29
|
+
| Tone | Use for |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `status` | A state (Pending, Active, Read only). |
|
|
32
|
+
| `author` | A person who wrote something. |
|
|
33
|
+
| `series` | A series name. |
|
|
34
|
+
| `subject` | A subject / genre / keyword. The default. |
|
|
35
|
+
| `book` | A book or title. |
|
|
36
|
+
| `entryType` | The kind of an entry or record. |
|
|
37
|
+
| `user` | An app user / account. |
|
|
38
|
+
| `rating` | A rating value. |
|
|
39
|
+
| `neutral` | A state with no category ("no change"): quiet grey. |
|
|
40
|
+
|
|
41
|
+
Each tone has its own `text`, `bg`, and `border` in both light and dark themes.
|
|
42
|
+
A consumer's theme can't add tones; the list is fixed by the `Theme` type.
|
|
43
|
+
|
|
44
|
+
## Corners
|
|
45
|
+
|
|
46
|
+
`radius.md` at both sizes, which is right inside a Card or modal; see
|
|
47
|
+
[corners](../corners.md).
|
|
48
|
+
|
|
49
|
+
## Examples
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
// Compact chips in a review row (inside a card).
|
|
53
|
+
{fix.toChips.map((c) => <Tag key={c} size="sm">{c}</Tag>)}
|
|
54
|
+
|
|
55
|
+
// A status, in neutral or status tone.
|
|
56
|
+
<Tag size="sm" tone="status">{write ? 'Read & write' : 'Read only'}</Tag>
|
|
57
|
+
|
|
58
|
+
// A clickable author chip that filters the list.
|
|
59
|
+
<Tag tone="author" onClick={() => setFilter({ author: name })}>{name}</Tag>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Do / don't
|
|
63
|
+
|
|
64
|
+
- Do choose `tone` by meaning, so the same kind of thing is the same colour
|
|
65
|
+
everywhere.
|
|
66
|
+
- Do use `size="sm"` inside text rows and lists.
|
|
67
|
+
- Don't use `neutral` just to make a tag grey when it has a category.
|
|
68
|
+
- Don't nest a clickable Tag inside another clickable element (Button, a
|
|
69
|
+
clickable Card); both would fire.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# ThemeSetting
|
|
2
|
+
|
|
3
|
+
`import { ThemeSetting } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A ready-made settings feature: a `Card` titled "Appearance" holding a
|
|
6
|
+
three-option `SegmentedControl` (Light / Dark / Auto) bound to the theme. A
|
|
7
|
+
choice applies immediately and is persisted by `ThemeProvider`.
|
|
8
|
+
|
|
9
|
+
Use something else for: reading the current choice or the resolved mode in
|
|
10
|
+
your own code (`useThemeSetting` from `@korzun/design/theme`), a custom
|
|
11
|
+
appearance UI (build it on `useThemeSetting`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
None. No `className`, no title override.
|
|
16
|
+
|
|
17
|
+
## How it works
|
|
18
|
+
|
|
19
|
+
- Reads and writes through `useThemeSetting()`, i.e. the context provided by
|
|
20
|
+
`ThemeProvider` from `@korzun/design/theme`.
|
|
21
|
+
- `ThemeProvider` stores the choice in `localStorage` under
|
|
22
|
+
`theme-setting:<identity>`, where `identity` is the provider's prop (for
|
|
23
|
+
example the signed-in username). Switching identity restores that user's
|
|
24
|
+
choice; `identity={null}` (the default) **stores nothing** and the
|
|
25
|
+
setting resets to `'auto'` on reload.
|
|
26
|
+
- `'auto'` follows the OS `prefers-color-scheme` live.
|
|
27
|
+
|
|
28
|
+
## Surprising behaviour
|
|
29
|
+
|
|
30
|
+
- **Without a `ThemeProvider` above it, it renders but does nothing**: the
|
|
31
|
+
default context's setter is a no-op.
|
|
32
|
+
- **Name clash at the package root:** `@korzun/design` (root entry) exports
|
|
33
|
+
this component as `ThemeSetting` and the `'light' | 'dark' | 'auto'` type as
|
|
34
|
+
`ThemeSettingValue`. From `@korzun/design/theme` the type is named
|
|
35
|
+
`ThemeSetting`. Import the component from `/component` to avoid confusion.
|
|
36
|
+
|
|
37
|
+
## Examples
|
|
38
|
+
|
|
39
|
+
```tsx
|
|
40
|
+
// App root: give the provider an identity so the choice persists per user.
|
|
41
|
+
<ThemeProvider identity={viewer?.username ?? null}>
|
|
42
|
+
<ToastProvider>
|
|
43
|
+
<AppRouter />
|
|
44
|
+
</ToastProvider>
|
|
45
|
+
</ThemeProvider>
|
|
46
|
+
|
|
47
|
+
// The settings screen: it is one Card in the stack.
|
|
48
|
+
<Page bottomNav>
|
|
49
|
+
<ThemeSetting />
|
|
50
|
+
<Card title="Change password">…</Card>
|
|
51
|
+
</Page>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Do / don't
|
|
55
|
+
|
|
56
|
+
- Do place it directly in a `Page`, like any other Card.
|
|
57
|
+
- Do pass `identity` to `ThemeProvider` if the choice should survive a reload.
|
|
58
|
+
- Don't wrap it in another `Card`; it already is one.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# TopFade
|
|
2
|
+
|
|
3
|
+
`import { TopFade } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A decorative, mobile-only scrim: a `position: fixed` frosted-glass band at the
|
|
6
|
+
top of the viewport, as tall as the status-bar safe-area inset plus
|
|
7
|
+
`space.md`, that blurs content scrolling under the device status bar and fades
|
|
8
|
+
to nothing below it (Safari style). It is `aria-hidden`,
|
|
9
|
+
`pointer-events: none`, and hidden at `min-width: 641px`.
|
|
10
|
+
|
|
11
|
+
Use something else for: a header or toolbar (`Page` header row / actions),
|
|
12
|
+
dimming behind a modal (the modal's own backdrop).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
None. No `className`.
|
|
17
|
+
|
|
18
|
+
## When to render it
|
|
19
|
+
|
|
20
|
+
- **Only in the installed (standalone) app**, gated with `isStandalone()` from
|
|
21
|
+
`@korzun/design/hooks`. In a browser tab the OS status bar is not drawn over
|
|
22
|
+
the page, `env(safe-area-inset-top)` is 0, and the band would be a thin
|
|
23
|
+
blurred strip with no purpose.
|
|
24
|
+
- Once, in the layout route, not per page.
|
|
25
|
+
- It sits at `theme.zIndex.header`: above page content, below the floating
|
|
26
|
+
controls and nav (`zIndex.sticky`).
|
|
27
|
+
|
|
28
|
+
## Surprising behaviour
|
|
29
|
+
|
|
30
|
+
- Its height comes from `env(safe-area-inset-top)`, which is non-zero only when
|
|
31
|
+
the page opts into the safe area (`<meta name="viewport"
|
|
32
|
+
content="…, viewport-fit=cover">`). Without that it is `space.md` tall.
|
|
33
|
+
- The tail is deliberately short so chrome resting near the top edge
|
|
34
|
+
(`theme.layout.floatingControlTopBase`) is never drawn through the blur.
|
|
35
|
+
Don't place your own content in the first `space.md` below the inset.
|
|
36
|
+
|
|
37
|
+
## Examples
|
|
38
|
+
|
|
39
|
+
```tsx
|
|
40
|
+
// Layout route for nav-bearing pages.
|
|
41
|
+
export const NavLayout = () => (
|
|
42
|
+
<>
|
|
43
|
+
<NavDesktop items={items} />
|
|
44
|
+
<NavMobile main={…} settings={…} expanded={…} />
|
|
45
|
+
{isStandalone() && (
|
|
46
|
+
<>
|
|
47
|
+
<TopFade />
|
|
48
|
+
<PullToRefreshIndicator /> {/* your own, built on usePullToRefresh */}
|
|
49
|
+
</>
|
|
50
|
+
)}
|
|
51
|
+
<Outlet />
|
|
52
|
+
</>
|
|
53
|
+
);
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Do / don't
|
|
57
|
+
|
|
58
|
+
- Do gate it on `isStandalone()`.
|
|
59
|
+
- Do render it once per app layout.
|
|
60
|
+
- Don't use it as a visual header; it carries no content and ignores clicks.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# BackButton
|
|
2
|
+
|
|
3
|
+
`import { BackButton } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A round glass "Back" button that navigates to a fixed path. It is mobile-only:
|
|
6
|
+
at widths of 641px and up it renders `display: none`, because desktop has its
|
|
7
|
+
own navigation. Usually you don't render it yourself: pass `back` to `Page`.
|
|
8
|
+
|
|
9
|
+
Use something else for: any other action (`Button`), header actions
|
|
10
|
+
(`PageActionsMenu` / `PageActionsBar`, also via `Page`).
|
|
11
|
+
|
|
12
|
+
## Props
|
|
13
|
+
|
|
14
|
+
| Prop | Type | Default | Notes |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `to` | `string` | (required) | Path to navigate to. |
|
|
17
|
+
|
|
18
|
+
That is the whole API. No `className`, no label, no `onClick`.
|
|
19
|
+
|
|
20
|
+
## Behaviour to know
|
|
21
|
+
|
|
22
|
+
- **It pushes `to`, it does not go back in history.** Click (or Enter / Space)
|
|
23
|
+
calls `navigate(to, { state: { restoreScroll: true } })`: a new history entry,
|
|
24
|
+
with a state flag asking the destination's scroll manager to restore its
|
|
25
|
+
remembered position instead of jumping to the top.
|
|
26
|
+
- Requires a `react-router` (v8, a peer dependency) router above it; it calls
|
|
27
|
+
`useNavigate()` and throws without one.
|
|
28
|
+
- Renders a `<div role="button" tabIndex={0} aria-label="Back">` with a
|
|
29
|
+
left-pointing chevron, 46×46px, `radius.circle`, `recipe.glass`.
|
|
30
|
+
- It does not position itself. `Page` puts it in its sticky controls row; if
|
|
31
|
+
you render it elsewhere, you place it.
|
|
32
|
+
|
|
33
|
+
## Examples
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
// Preferred: let Page render it (and PageActionsMenu beside it on mobile).
|
|
37
|
+
<Page back="/library" headerActions={actions}>
|
|
38
|
+
…
|
|
39
|
+
</Page>
|
|
40
|
+
|
|
41
|
+
// Standalone, inside your own row.
|
|
42
|
+
<div className={styles.controls}>
|
|
43
|
+
<BackButton to={path.book(book.id)} />
|
|
44
|
+
</div>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Do / don't
|
|
48
|
+
|
|
49
|
+
- Do use `Page back="…"` instead of rendering `BackButton` directly, so it lines
|
|
50
|
+
up with the mobile actions menu.
|
|
51
|
+
- Do pass the logical parent route (`/library`, the book page), not a guess at
|
|
52
|
+
the previous URL: it always goes to `to`.
|
|
53
|
+
- Don't expect it on desktop; it is hidden at 641px and up.
|
|
54
|
+
- Don't wrap it in a `<button>` or `<a>`, or try to restyle it: there is no
|
|
55
|
+
`className`.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Button
|
|
2
|
+
|
|
3
|
+
`import { Button } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A clickable action with a visual variant, optional icons, and a loading state.
|
|
6
|
+
Renders a `<div role="button">` (keyboard: Enter and Space) unless `submit` is
|
|
7
|
+
set, in which case it renders a native `<button type="submit">`.
|
|
8
|
+
|
|
9
|
+
Use something else for: navigating back (`BackButton`), page-level actions in
|
|
10
|
+
the header (`PageActionsBar`, `PageActionsMenu`), sticky footer actions
|
|
11
|
+
(`PageFooterActions`), picking one of several options (`SegmentedControl`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `children` | `ReactNode` | | Label. |
|
|
18
|
+
| `type` | `'default' \| 'primary' \| 'text' \| 'link' \| 'dashed'` | `'default'` | **Visual variant, not the HTML `type`.** Use `submit` for a submit button. |
|
|
19
|
+
| `radius` | `'background' \| 'card' \| 'inset' \| 'modal'` | `'background'` | The surface the button sits on; see [corners](../corners.md). |
|
|
20
|
+
| `danger` | `boolean` | `false` | Red treatment. Mutually exclusive with `success` (type error). |
|
|
21
|
+
| `success` | `boolean` | `false` | Green treatment. Mutually exclusive with `danger`. |
|
|
22
|
+
| `loading` | `boolean` | `false` | Shows a spinner in place of the icons; blocks clicks. |
|
|
23
|
+
| `disabled` | `boolean` | `false` | |
|
|
24
|
+
| `onClick` | `() => void` | no-op | **Ignored when `submit` is set**; the form submits instead. Receives no event. |
|
|
25
|
+
| `submit` | `boolean` | `false` | Render a native submit button. Also shows the spinner while the enclosing form action is pending (`useFormStatus`). |
|
|
26
|
+
| `form` | `string` | | Id of the `<form>` to submit, for a submit button outside its form (e.g. in a `Card` footer). |
|
|
27
|
+
| `prefix` / `suffix` | `ComponentType<IconProps>` | | An icon **component** (`prefix={SearchIcon}`), not an element. |
|
|
28
|
+
| `ariaLabel` | `string` | | Required when the label alone is ambiguous, e.g. repeated "Remove" buttons in a list. |
|
|
29
|
+
| `ariaExpanded` / `ariaControls` | `boolean` / `string` | | For disclosure buttons. |
|
|
30
|
+
| `className` | `string` | | Override with `'&&'` specificity in your sheet, never `!important`. |
|
|
31
|
+
| `title`, `tabIndex` | | | Passed through. |
|
|
32
|
+
|
|
33
|
+
## Choosing a variant
|
|
34
|
+
|
|
35
|
+
- `primary`: the one main action of a card, modal, or page (Save, Confirm).
|
|
36
|
+
- `default`: secondary actions; bordered.
|
|
37
|
+
- `text`: Cancel in a modal footer.
|
|
38
|
+
- `link`: inline row actions (Remove, Load more). It has no padding, so `radius`
|
|
39
|
+
doesn't matter for it.
|
|
40
|
+
- `dashed`: an "add a row" affordance (as in `FieldList`).
|
|
41
|
+
- Add `danger` for destructive actions (Delete, Log out), on `primary` in a
|
|
42
|
+
confirm or on `default` otherwise.
|
|
43
|
+
|
|
44
|
+
## Examples
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
// On the page background: omit radius (defaults to 'background').
|
|
48
|
+
<Button danger onClick={logOut}>Log out</Button>
|
|
49
|
+
|
|
50
|
+
// In a Card footer, submitting a form that lives in the card body.
|
|
51
|
+
<Card
|
|
52
|
+
title="Change password"
|
|
53
|
+
footer={
|
|
54
|
+
<Button type="primary" radius="card" submit form="change-password">
|
|
55
|
+
Save
|
|
56
|
+
</Button>
|
|
57
|
+
}
|
|
58
|
+
>
|
|
59
|
+
<form id="change-password" action={save}>…</form>
|
|
60
|
+
</Card>
|
|
61
|
+
|
|
62
|
+
// A modal footer.
|
|
63
|
+
<Button type="text" radius="modal" onClick={onCancel}>Cancel</Button>
|
|
64
|
+
<Button type="primary" danger radius="modal" loading={deleting} onClick={onConfirm}>
|
|
65
|
+
Delete
|
|
66
|
+
</Button>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Do / don't
|
|
70
|
+
|
|
71
|
+
- Do set `radius="card"` on every Button inside a `Card` (body or footer) and
|
|
72
|
+
`radius="modal"` inside a modal, except `type="link"`.
|
|
73
|
+
- Do give repeated row actions a distinguishing `ariaLabel` ("Remove Kindle").
|
|
74
|
+
- Don't pass `type="submit"`: it is not a valid variant. Use `submit`.
|
|
75
|
+
- Don't pass `onClick` to a submit button and expect it to run.
|
|
76
|
+
- Don't pass an element to `prefix`/`suffix` (`prefix={<SearchIcon />}`); pass
|
|
77
|
+
the component.
|
|
78
|
+
- Don't wrap Button in a `<button>` or `<a>`: it is already interactive.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# ChipsInput
|
|
2
|
+
|
|
3
|
+
`import { ChipsInput } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A tag field: the current values render as coloured chips inside an input box,
|
|
6
|
+
typing filters a suggestion dropdown (a `Popover`), and Enter adds a chip. Fully
|
|
7
|
+
controlled: you own the `string[]`.
|
|
8
|
+
|
|
9
|
+
Use something else for: one value from a list (`Select`), one of a few fixed
|
|
10
|
+
options (`SegmentedControl`), free text (`TextInput`).
|
|
11
|
+
|
|
12
|
+
## Props
|
|
13
|
+
|
|
14
|
+
| Prop | Type | Default | Notes |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `value` | `string[]` | (required) | The chips. Controlled. |
|
|
17
|
+
| `suggestions` | `string[]` | (required) | Pass `[]` for none. Already-chosen values are hidden; matching is case-insensitive substring. |
|
|
18
|
+
| `onChange` | `(values: string[]) => void` | (required) | Receives the whole new array, not an event. |
|
|
19
|
+
| `allowCustom` | `boolean` | `true` | Enter (or Tab) adds the typed text as a chip. `false`: only suggestions can be added. |
|
|
20
|
+
| `label` | `string` | | **Ignored in the default `block` layout.** Set `layout="horizontal"` or `"vertical"` to show it. |
|
|
21
|
+
| `layout` | `'block' \| 'horizontal' \| 'vertical'` | `'block'` | `block` = the bare box, no label. `horizontal`/`vertical` add a label on a `bg.cardHeader` row (`radius.md`), like the other fields. |
|
|
22
|
+
| `placeholder` | `string` | | Shown only while there are no chips. |
|
|
23
|
+
| `chipColor` | `keyof theme.color.chip` | `'subject'` | `status`, `author`, `series`, `subject`, `book`, `entryType`, `user`, `rating`, `neutral`. |
|
|
24
|
+
| `dense` | `boolean` | `false` | Matches a standard input's height, so it lines up with `TextInput`/`Select` rows. Leave off for a roomy standalone tag box. |
|
|
25
|
+
| `disabled` | `boolean` | `false` | Disables typing and the chip remove buttons. |
|
|
26
|
+
| `name` | `string` | | Set on the text input only: form data gets the **half-typed text, not the chips**. Submit `value` yourself. |
|
|
27
|
+
|
|
28
|
+
No `className`. The label is linked to the input with a generated id.
|
|
29
|
+
|
|
30
|
+
## Keyboard
|
|
31
|
+
|
|
32
|
+
- ArrowDown / ArrowUp move the highlight; Enter or Tab adds the highlighted
|
|
33
|
+
suggestion, else (with `allowCustom`) the trimmed typed text.
|
|
34
|
+
- **Tab with text typed adds a chip and keeps focus in the field** (it calls
|
|
35
|
+
`preventDefault`); Tab on an empty field moves focus normally.
|
|
36
|
+
- Enter never submits the surrounding form while text is typed, even when
|
|
37
|
+
nothing could be added.
|
|
38
|
+
- Backspace on an empty field removes the last chip.
|
|
39
|
+
- A value that matches an existing chip case-insensitively is not added.
|
|
40
|
+
|
|
41
|
+
## Examples
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
// A standalone subjects box in its own Card.
|
|
45
|
+
<Card title="Subjects">
|
|
46
|
+
<ChipsInput
|
|
47
|
+
value={subjects}
|
|
48
|
+
suggestions={allSubjects}
|
|
49
|
+
onChange={setSubjects}
|
|
50
|
+
placeholder="Add subject…"
|
|
51
|
+
/>
|
|
52
|
+
</Card>
|
|
53
|
+
|
|
54
|
+
// A labelled row in a form, restricted to known users.
|
|
55
|
+
<ChipsInput
|
|
56
|
+
name="users"
|
|
57
|
+
label="Users"
|
|
58
|
+
layout="horizontal"
|
|
59
|
+
dense
|
|
60
|
+
value={selectedUsers}
|
|
61
|
+
suggestions={userNames}
|
|
62
|
+
onChange={setSelectedUsers}
|
|
63
|
+
allowCustom={false}
|
|
64
|
+
chipColor="user"
|
|
65
|
+
disabled={loadingUsers}
|
|
66
|
+
placeholder={loadingUsers ? 'Loading…' : 'Add users…'}
|
|
67
|
+
/>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Do / don't
|
|
71
|
+
|
|
72
|
+
- Do set `layout="horizontal"` and `dense` when it sits among other form fields
|
|
73
|
+
in a `Card`; otherwise the label silently disappears.
|
|
74
|
+
- Do pick a `chipColor` that matches how the same values are tagged elsewhere.
|
|
75
|
+
- Don't rely on `name` for form submission.
|
|
76
|
+
- Don't use it inside a modal `<dialog>` without testing: the dropdown portals
|
|
77
|
+
outside the dialog's top layer (see [popover](popover.md)).
|