@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,64 @@
|
|
|
1
|
+
# PageActionsBar
|
|
2
|
+
|
|
3
|
+
`import { PageActionsBar } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
The **desktop** page-actions row: `primary` items render as inline Buttons and
|
|
6
|
+
the rest collapse into a "More…" overflow menu. It is hidden at 640px and
|
|
7
|
+
below, where `PageActionsMenu` shows the same items. Usually you don't render
|
|
8
|
+
it yourself: pass `headerActions` (and `actionsLabel`) to `Page`, which puts it
|
|
9
|
+
in the header row.
|
|
10
|
+
|
|
11
|
+
Use something else for: mobile (`PageActionsMenu`), bottom-of-page form actions
|
|
12
|
+
(`PageFooterActions`), a one-off button inside a card (`Button`).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `items` | `PageActionItem[]` | (required) | See [page-actions-menu](page-actions-menu.md#pageactionitem) for the item shape. |
|
|
19
|
+
| `actionsLabel` | `string` | `'More…'` | Visible text and accessible name of the overflow trigger (default accessible name: "More actions"). Pass `'Actions'` when every item is overflow. |
|
|
20
|
+
|
|
21
|
+
No `className`.
|
|
22
|
+
|
|
23
|
+
## How items are placed
|
|
24
|
+
|
|
25
|
+
- `primary: true` → an inline `Button` (`type="default"`, default
|
|
26
|
+
`radius="background"`, because the bar sits on the page background).
|
|
27
|
+
`align: 'leading'` puts it at the left; anything else is trailing, at the
|
|
28
|
+
right. `danger` and `disabled` apply.
|
|
29
|
+
- Not primary → the overflow menu (solid card surface, `radius.md`, items
|
|
30
|
+
`radius.sm`), opened by the trigger at the far right. `separatorBefore`
|
|
31
|
+
draws a divider there.
|
|
32
|
+
- No overflow items → no trigger.
|
|
33
|
+
- **`intentProps` only work on overflow items**; primary Buttons drop them.
|
|
34
|
+
- Items are keyed by `label`, so labels must be unique.
|
|
35
|
+
|
|
36
|
+
## Behaviour to know
|
|
37
|
+
|
|
38
|
+
The menu closes on item select (before `onClick` runs), Escape, or an outside
|
|
39
|
+
mousedown. The trigger is a native `<button>` with `aria-haspopup="menu"` and
|
|
40
|
+
`aria-expanded`. No arrow-key navigation in the menu.
|
|
41
|
+
|
|
42
|
+
## Example
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
<Page
|
|
46
|
+
headerActions={[
|
|
47
|
+
{ label: 'Read', onClick: read, primary: true, align: 'leading' },
|
|
48
|
+
{ label: 'Edit', onClick: edit, primary: true },
|
|
49
|
+
{ label: 'Download', onClick: download },
|
|
50
|
+
{ label: 'Delete', onClick: remove, danger: true, separatorBefore: true },
|
|
51
|
+
]}
|
|
52
|
+
>
|
|
53
|
+
…
|
|
54
|
+
</Page>
|
|
55
|
+
|
|
56
|
+
// Every action in the menu, trigger labelled "Actions".
|
|
57
|
+
<Page headerActions={uploadActions} actionsLabel="Actions">…</Page>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Do / don't
|
|
61
|
+
|
|
62
|
+
- Do mark at most two or three items `primary`; the rest belong in the menu.
|
|
63
|
+
- Do use `Page headerActions` so the mobile menu gets the same items.
|
|
64
|
+
- Don't rely on `intentProps` for a primary item.
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# PageActionsMenu
|
|
2
|
+
|
|
3
|
+
`import { PageActionsMenu, type PageActionItem, type PageActionIntentProps } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
The **mobile** page-actions control: a round glass "More actions" button (⋯)
|
|
6
|
+
that opens a glass menu listing every action. It is hidden at 641px and up,
|
|
7
|
+
where `PageActionsBar` takes over with the same items. Usually you don't render
|
|
8
|
+
it yourself: pass `headerActions` to `Page`, which renders both.
|
|
9
|
+
|
|
10
|
+
Use something else for: desktop header actions (`PageActionsBar`), bottom-of-
|
|
11
|
+
page form actions (`PageFooterActions`), a single inline action (`Button`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `items` | `PageActionItem[]` | (required) | All of them appear in the menu, in order. |
|
|
18
|
+
|
|
19
|
+
No `className`, no label prop (the trigger is always "More actions").
|
|
20
|
+
|
|
21
|
+
## PageActionItem
|
|
22
|
+
|
|
23
|
+
Shared with `PageActionsBar`, so one array drives both.
|
|
24
|
+
|
|
25
|
+
| Field | Type | Notes |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `label` | `string` | Menu text. **Must be unique**: it is the React key. |
|
|
28
|
+
| `onClick` | `() => void` | Receives no event. The menu closes first. |
|
|
29
|
+
| `danger` | `boolean` | Red text. Styling only. |
|
|
30
|
+
| `disabled` | `boolean` | |
|
|
31
|
+
| `separatorBefore` | `boolean` | Divider above this item (ignored on the first). `danger` does not add one. |
|
|
32
|
+
| `intentProps` | `{ onMouseEnter, onFocus, onTouchStart }` | Spread onto the menu item, e.g. to prefetch. |
|
|
33
|
+
| `primary` | `boolean` | **Ignored here.** Only `PageActionsBar` uses it. |
|
|
34
|
+
| `align` | `'leading' \| 'trailing'` | **Ignored here.** Only `PageActionsBar` uses it. |
|
|
35
|
+
|
|
36
|
+
## Behaviour to know
|
|
37
|
+
|
|
38
|
+
- Closes on item select, Escape, or a mousedown outside. No arrow-key
|
|
39
|
+
navigation; Tab moves through the items.
|
|
40
|
+
- The menu is a floating layer (`radius.md`, glass, items `radius.sm`),
|
|
41
|
+
absolutely positioned under the trigger, right-aligned.
|
|
42
|
+
- It doesn't place itself: `Page` puts it in the sticky controls row
|
|
43
|
+
(`margin-left: auto` keeps it at the trailing end, with or without a
|
|
44
|
+
`BackButton`).
|
|
45
|
+
|
|
46
|
+
## Example
|
|
47
|
+
|
|
48
|
+
```tsx
|
|
49
|
+
const actions: PageActionItem[] = [
|
|
50
|
+
{ label: 'Edit', onClick: edit, primary: true },
|
|
51
|
+
{ label: 'Read', onClick: read, primary: true, align: 'leading' },
|
|
52
|
+
{ label: 'Download', onClick: download, intentProps: prefetchDownload },
|
|
53
|
+
{ label: 'Delete', onClick: () => setConfirming(true), danger: true, separatorBefore: true },
|
|
54
|
+
];
|
|
55
|
+
|
|
56
|
+
// Preferred: Page renders PageActionsMenu (mobile) and PageActionsBar (desktop).
|
|
57
|
+
<Page back="/library" headerActions={actions}>…</Page>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Do / don't
|
|
61
|
+
|
|
62
|
+
- Do pass the same `items` you give `PageActionsBar` (or just use `Page`).
|
|
63
|
+
- Do put destructive items last with `separatorBefore`.
|
|
64
|
+
- Don't render it on its own and expect it on desktop; it is hidden there.
|
|
65
|
+
- Don't give two items the same `label`; they collide as React keys.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# PageFooterActions
|
|
2
|
+
|
|
3
|
+
`import { PageFooterActions, type FooterAction } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A row of Buttons for the bottom of a page, typically Cancel / Save for a form
|
|
6
|
+
that spans several cards. Leading items sit left, trailing items right. It is
|
|
7
|
+
a plain flex row (not sticky, shown at every width). `Page` renders it after
|
|
8
|
+
its children when you pass `footerActions`; you can also render it directly
|
|
9
|
+
after your form.
|
|
10
|
+
|
|
11
|
+
Use something else for: header actions (`PageActionsBar` / `PageActionsMenu`
|
|
12
|
+
via `Page headerActions`), a Card's own submit (`Button` in the Card `footer`),
|
|
13
|
+
modal buttons (`Button radius="modal"`).
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Default | Notes |
|
|
18
|
+
|---|---|---|---|
|
|
19
|
+
| `items` | `FooterAction[]` | (required) | Rendered in order within each side. |
|
|
20
|
+
|
|
21
|
+
No `className`.
|
|
22
|
+
|
|
23
|
+
## FooterAction
|
|
24
|
+
|
|
25
|
+
| Field | Type | Notes |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `label` | `string` | Button text; may change between renders (`Save` → `Saving…`) without remounting. |
|
|
28
|
+
| `onClick` | `() => void` | **Required even for a submit item, and ignored there** (the form submits). Pass `() => {}`. Receives no event. |
|
|
29
|
+
| `emphasis` | `boolean` | `type="primary"`; otherwise `type="default"`. |
|
|
30
|
+
| `danger` | `boolean` | Red treatment. |
|
|
31
|
+
| `disabled` | `boolean` | |
|
|
32
|
+
| `loading` | `boolean` | Spinner; blocks clicks. |
|
|
33
|
+
| `align` | `'leading' \| 'trailing'` | Default trailing. |
|
|
34
|
+
| `submit` | `boolean` | Native submit button. |
|
|
35
|
+
| `form` | `string` | Id of the `<form>` to submit; needed because the row sits outside the form. |
|
|
36
|
+
|
|
37
|
+
Buttons use the default `radius` (`background`, `radius.lg`), correct because
|
|
38
|
+
the row sits on the page background below the cards; see
|
|
39
|
+
[corners](../corners.md). Don't put PageFooterActions inside a `Card`.
|
|
40
|
+
|
|
41
|
+
## Example
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
<form id={formId} action={save}>
|
|
45
|
+
<Card title="Details">…</Card>
|
|
46
|
+
<Card title="Identifiers">…</Card>
|
|
47
|
+
</form>
|
|
48
|
+
<PageFooterActions
|
|
49
|
+
items={[
|
|
50
|
+
{ label: 'Cancel', onClick: () => navigate(path.book(book.id)), disabled: isPending },
|
|
51
|
+
{
|
|
52
|
+
label: isPending ? 'Saving…' : 'Save',
|
|
53
|
+
onClick: () => {},
|
|
54
|
+
submit: true,
|
|
55
|
+
form: formId,
|
|
56
|
+
emphasis: true,
|
|
57
|
+
loading: isPending,
|
|
58
|
+
disabled: hasInvalidFields,
|
|
59
|
+
},
|
|
60
|
+
]}
|
|
61
|
+
/>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Do / don't
|
|
65
|
+
|
|
66
|
+
- Do give exactly one item `emphasis`.
|
|
67
|
+
- Do pair `submit` with `form` when the row is outside the `<form>`.
|
|
68
|
+
- Don't put a destructive action beside Save without `danger` and
|
|
69
|
+
`align: 'leading'`.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Popover
|
|
2
|
+
|
|
3
|
+
`import { Popover } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A positioning primitive: renders `children` in a portal on `document.body`,
|
|
6
|
+
`position: fixed` directly beneath an anchor element, so a dropdown can escape
|
|
7
|
+
ancestors that clip overflow (rounded cards). It paints **nothing** itself: no
|
|
8
|
+
background, border, shadow, or radius. `Select` and `ChipsInput` build their
|
|
9
|
+
dropdowns on it.
|
|
10
|
+
|
|
11
|
+
Use something else for: a modal (`useModalDialog`), page action menus
|
|
12
|
+
(`PageActionsMenu`, `PageActionsBar`), choosing from a list (`Select`).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `anchorRef` | `RefObject<HTMLElement \| null>` | (required) | Element to sit under. Left edges align. |
|
|
19
|
+
| `open` | `boolean` | (required) | When `false`, renders nothing. Fully controlled. |
|
|
20
|
+
| `children` | `ReactNode` | (required) | Your surface: give it its own background, border, radius. |
|
|
21
|
+
| `gap` | `number` | `4` | Pixels between the anchor's bottom and the popover. |
|
|
22
|
+
| `matchWidth` | `boolean` | `true` | Width = anchor width. `false` lets content size itself. |
|
|
23
|
+
| `onClose` | `() => void` | | Called on a mousedown outside both anchor and content. Omit to opt out. Receives no event. |
|
|
24
|
+
| `className` | `string` | | Applied to the fixed wrapper. Override with `'&&'`, never `!important`. |
|
|
25
|
+
|
|
26
|
+
## Behaviour to know
|
|
27
|
+
|
|
28
|
+
- **No Escape handling and no focus management.** Add your own keydown handler
|
|
29
|
+
if Escape should close it.
|
|
30
|
+
- Always opens below the anchor; it does not flip up or clamp to the viewport.
|
|
31
|
+
It repositions on window resize and on any scroll (capture phase).
|
|
32
|
+
- First paint is skipped until the anchor is measured, so it never flashes at 0,0.
|
|
33
|
+
- z-index is `theme.zIndex.sticky` (1000). Inside a modal `<dialog>` opened with
|
|
34
|
+
`showModal()`, a body portal sits outside the dialog's top layer, so it is
|
|
35
|
+
likely hidden behind the dialog and inert. Test before using it there.
|
|
36
|
+
- Clicking the anchor does not count as "outside", so a toggle button on the
|
|
37
|
+
anchor works without racing `onClose`.
|
|
38
|
+
|
|
39
|
+
## Styling the surface
|
|
40
|
+
|
|
41
|
+
A popover is a floating layer: corners `radius.md` with `shadow.hoverLift` (or
|
|
42
|
+
`recipe.glass`), and the items inside it `radius.sm`. See
|
|
43
|
+
[corners](../corners.md).
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
menu: {
|
|
47
|
+
backgroundColor: theme.color.bg.card,
|
|
48
|
+
border: `1px solid ${theme.color.border.strong}`,
|
|
49
|
+
borderRadius: theme.radius.md,
|
|
50
|
+
boxShadow: theme.shadow.hoverLift,
|
|
51
|
+
padding: theme.space.xs,
|
|
52
|
+
},
|
|
53
|
+
item: { borderRadius: theme.radius.sm, padding: theme.space.md },
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Example
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
const anchor = useRef<HTMLDivElement>(null);
|
|
60
|
+
const [open, setOpen] = useState(false);
|
|
61
|
+
|
|
62
|
+
<div ref={anchor} className={styles.anchor}>
|
|
63
|
+
<Button onClick={() => setOpen((o) => !o)}>Filters</Button>
|
|
64
|
+
</div>
|
|
65
|
+
<Popover anchorRef={anchor} open={open} matchWidth={false} onClose={() => setOpen(false)}>
|
|
66
|
+
<div className={styles.menu}>…</div>
|
|
67
|
+
</Popover>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Do / don't
|
|
71
|
+
|
|
72
|
+
- Do wrap a `Button` in a `<div ref>` to anchor it; `Button` takes no ref.
|
|
73
|
+
- Do give the content its own surface and radius; the wrapper is transparent.
|
|
74
|
+
- Don't expect it to close on Escape or on selection; that is your code.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# SegmentedControl
|
|
2
|
+
|
|
3
|
+
`import { SegmentedControl } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A row of equal-width radio segments in a track, with a lens that slides to the
|
|
6
|
+
checked one. Options can be text, or an icon over a small caption. Optionally
|
|
7
|
+
clearable, and read-only when `onChange` is omitted. Generic over the value
|
|
8
|
+
type: `V extends string`.
|
|
9
|
+
|
|
10
|
+
Use something else for: many options or long labels (`Select`), on/off
|
|
11
|
+
(`Switch`), actions (`Button`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `label` | `string` | (required) | The group's accessible name (`aria-label`). **Not rendered visibly**; put a visible label beside it yourself. |
|
|
18
|
+
| `options` | `ReadonlyArray<{ value: V; label: string; Icon?: (props: IconProps) => JSX.Element }>` | (required) | `label` is each segment's accessible name. `Icon` is a component (`Icon: SearchIcon`). |
|
|
19
|
+
| `value` | `V \| null` | (required) | `null`, or a value no option has, checks nothing and draws no lens. |
|
|
20
|
+
| `onChange` | `(value: V) => void`, or `(value: V \| null) => void` with `clearable` | | **Omit for read-only**: segments get `aria-disabled` and ignore clicks and keys. |
|
|
21
|
+
| `clearable` | `boolean` | `false` | Clicking the checked segment, Backspace or Delete call `onChange(null)`. Without it, clicking the checked segment does nothing. |
|
|
22
|
+
| `showLabels` | `boolean` | `true` | `false` hides captions, **only for options with an `Icon`**; text-only options always show their label. |
|
|
23
|
+
| `surface` | `'card' \| 'row'` | `'card'` | `card`: paints its own `bg.track` rail. `row`: transparent, for a control sitting inside a shaded field row. |
|
|
24
|
+
|
|
25
|
+
No `className`, no `name` (not a form field). The segment type is not exported;
|
|
26
|
+
declare options `as const` or type them inline.
|
|
27
|
+
|
|
28
|
+
## Keyboard
|
|
29
|
+
|
|
30
|
+
On the group: ArrowRight/ArrowUp and ArrowLeft/ArrowDown step one option and do
|
|
31
|
+
not wrap; Home/End jump to the ends; digits 1–9 pick that option; Backspace and
|
|
32
|
+
Delete clear when `clearable`. Modified keys (Ctrl/Cmd/Alt) are left alone.
|
|
33
|
+
|
|
34
|
+
## Choosing a surface
|
|
35
|
+
|
|
36
|
+
The track and lens are always `radius.md` (see [corners](../corners.md)), so the
|
|
37
|
+
control belongs inside a card or modal.
|
|
38
|
+
|
|
39
|
+
- Directly in a `Card` body: omit `surface` (`'card'`).
|
|
40
|
+
- Inside a shaded `bg.cardHeader` row you built (label left, control right):
|
|
41
|
+
`surface="row"`, so the row itself is the track and the lens is flush with it.
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
const SORTS = [
|
|
47
|
+
{ value: 'title', label: 'Title' },
|
|
48
|
+
{ value: 'author', label: 'Author' },
|
|
49
|
+
{ value: 'added', label: 'Added' },
|
|
50
|
+
] as const;
|
|
51
|
+
|
|
52
|
+
<SegmentedControl label="Sort by" options={SORTS} value={sort} onChange={setSort} />
|
|
53
|
+
|
|
54
|
+
// Icon segments, clearable, captions hidden; onChange receives null on clear.
|
|
55
|
+
<SegmentedControl
|
|
56
|
+
label="Rating"
|
|
57
|
+
options={RATINGS /* { value: '1', label: 'Bad', Icon: ThumbDownIcon }, … */}
|
|
58
|
+
value={rating}
|
|
59
|
+
onChange={setRating}
|
|
60
|
+
clearable
|
|
61
|
+
showLabels={false}
|
|
62
|
+
/>
|
|
63
|
+
|
|
64
|
+
// Read-only display.
|
|
65
|
+
<SegmentedControl label="Rating" options={RATINGS} value={rating} />
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Do / don't
|
|
69
|
+
|
|
70
|
+
- Do keep it to a handful of short options; segments are equal columns.
|
|
71
|
+
- Do pass `clearable` whenever `null` is a valid answer, or the user can never
|
|
72
|
+
get back to it.
|
|
73
|
+
- Don't pass `onChange={() => {}}` to show a value; omit `onChange` for read-only.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Select
|
|
2
|
+
|
|
3
|
+
`import { Select, type SelectOption, type SelectProps } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A single-value dropdown with type-to-search (on by default), an optional "Add:
|
|
6
|
+
…" entry for new values, a clear button, and a loading state. The dropdown is a
|
|
7
|
+
`Popover`, so it escapes clipping cards.
|
|
8
|
+
|
|
9
|
+
Use something else for: 2–5 options that fit in one row (`SegmentedControl`),
|
|
10
|
+
several values (`ChipsInput`), on/off (`Switch`).
|
|
11
|
+
|
|
12
|
+
## Props
|
|
13
|
+
|
|
14
|
+
| Prop | Type | Default | Notes |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `name` | `string` | (required) | Only lands on the search box while it is open; see "Forms". |
|
|
17
|
+
| `value` | `string \| undefined` | (required) | Controlled. A value not in `options` displays as the raw string. |
|
|
18
|
+
| `options` | `SelectOption[]` | (required) | `string`, or `{ label, value, description? }`. Mix freely. |
|
|
19
|
+
| `onChange` | `(value: string \| undefined) => void` | no-op | Receives the option's `value`, `undefined` from the clear button, or the trimmed typed text from "Add:". Not an event. |
|
|
20
|
+
| `surface` | `'card' \| 'page'` | `'card'` | Sets radius **and** elevation together; see "Choosing a surface". |
|
|
21
|
+
| `label` | `string` | | Visible label. |
|
|
22
|
+
| `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row. |
|
|
23
|
+
| `placeholder` | `string` | `'Select…'` | Shown when nothing is selected. |
|
|
24
|
+
| `searchable` | `boolean` | `true` | Opening swaps the trigger for a search box. `false`: a plain list, arrow keys only. |
|
|
25
|
+
| `allowCreate` | `boolean` | `false` | With a search query that matches no label exactly, adds an "Add: *query*" option. |
|
|
26
|
+
| `clearable` | `boolean` | `true` | Shows a ✕ when a value is set. Pass `false` for required fields. |
|
|
27
|
+
| `loading` | `boolean` | `false` | Shows a spinner and "Loading…"; can't open. |
|
|
28
|
+
| `disabled` | `boolean` | `false` | Faded to 50%; can't open; no clear button. |
|
|
29
|
+
|
|
30
|
+
No `className`.
|
|
31
|
+
|
|
32
|
+
## Choosing a surface
|
|
33
|
+
|
|
34
|
+
Follow [corners](../corners.md):
|
|
35
|
+
|
|
36
|
+
- Inside a `Card` or a modal: omit it (`'card'`, `radius.md`, no shadow).
|
|
37
|
+
- Directly on the page background (e.g. a global picker above the cards):
|
|
38
|
+
`surface="page"` (`radius.lg` + `shadow.cardStack`, like a card).
|
|
39
|
+
- There is no `sm` option for a select nested inside an inset box.
|
|
40
|
+
|
|
41
|
+
## Forms
|
|
42
|
+
|
|
43
|
+
There is no hidden input carrying `value`: native `FormData` will not contain
|
|
44
|
+
the selection (only the search text while open). Keep `value` in state and
|
|
45
|
+
submit that. The `<label>` targets the search box, so it is not the closed
|
|
46
|
+
trigger's accessible name; the trigger announces the selected label or
|
|
47
|
+
placeholder.
|
|
48
|
+
|
|
49
|
+
## Keyboard
|
|
50
|
+
|
|
51
|
+
Closed: Enter, Space or ArrowDown open it. Open: ArrowUp/ArrowDown move (and
|
|
52
|
+
wrap), Enter selects, Escape or Tab close. The highlight starts on the first
|
|
53
|
+
option, not the current value.
|
|
54
|
+
|
|
55
|
+
## Examples
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
// In a Card form: a fixed list, required.
|
|
59
|
+
<Select
|
|
60
|
+
name="coverFit"
|
|
61
|
+
label="Fit"
|
|
62
|
+
value={coverFit}
|
|
63
|
+
options={[
|
|
64
|
+
{ label: 'Contain', value: 'contain', description: 'Letterbox the cover' },
|
|
65
|
+
{ label: 'Cover', value: 'cover' },
|
|
66
|
+
]}
|
|
67
|
+
onChange={setCoverFit}
|
|
68
|
+
searchable={false}
|
|
69
|
+
clearable={false}
|
|
70
|
+
/>
|
|
71
|
+
|
|
72
|
+
// A creatable field with async options.
|
|
73
|
+
<Select name="seriesName" label="Name" value={series || undefined}
|
|
74
|
+
options={seriesNames} loading={seriesLoading} allowCreate onChange={setSeries} />
|
|
75
|
+
|
|
76
|
+
// On the page background, no label.
|
|
77
|
+
<Select name="library" surface="page" value={libraryId} options={libraries}
|
|
78
|
+
onChange={setLibraryId} placeholder="Select user…" />
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Do / don't
|
|
82
|
+
|
|
83
|
+
- Do pass `clearable={false}` when an empty value is invalid.
|
|
84
|
+
- Do test before using inside a modal `<dialog>`: the dropdown portals outside
|
|
85
|
+
the dialog's top layer (see [popover](popover.md)).
|
|
86
|
+
- Don't pass `surface="page"` inside a card.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Switch
|
|
2
|
+
|
|
3
|
+
`import { Switch } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
An on/off toggle (`role="switch"`) with an optional label and description, a
|
|
6
|
+
full-row `horizontal` layout for forms, and a `loading` state for saves in
|
|
7
|
+
flight. Controlled: you own `checked`.
|
|
8
|
+
|
|
9
|
+
Use something else for: one of several options (`SegmentedControl`, `Select`),
|
|
10
|
+
an action that happens on click (`Button`).
|
|
11
|
+
|
|
12
|
+
## Props
|
|
13
|
+
|
|
14
|
+
| Prop | Type | Default | Notes |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `name` | `string` | (required) | **Not a form field**: there is no hidden input. Only the last-resort accessible name. |
|
|
17
|
+
| `checked` | `boolean` | (required) | Controlled. |
|
|
18
|
+
| `onChange` | `(checked: boolean) => void` | (required) | Receives the new value, not an event. Not called while `disabled` or `loading`. |
|
|
19
|
+
| `label` | `string` | | Visible label and accessible name. |
|
|
20
|
+
| `ariaLabel` | `string` | | Accessible name when the visible label lives elsewhere (a grid's row and column headers). Wins over `label`. Without either, `name` is announced. |
|
|
21
|
+
| `description` | `ReactNode` | | Helper text under the label, linked by `aria-describedby`. |
|
|
22
|
+
| `layout` | `'default' \| 'horizontal'` | `'default'` | `default`: track, then label, inline. `horizontal`: full-width `bg.cardHeader` row (`radius.md`), label and description left, track right; **the whole row toggles**, description included. |
|
|
23
|
+
| `radius` | `'inset' \| 'pill'` | `'inset'` | Track shape; see "Choosing a radius". |
|
|
24
|
+
| `loading` | `boolean` | `false` | Ignores clicks immediately and sets `aria-busy`; the thumb becomes a spinner only after 150ms, so fast saves don't flash. Keeps its colour. |
|
|
25
|
+
| `disabled` | `boolean` | `false` | Fades to 40%, removes it from the tab order. |
|
|
26
|
+
|
|
27
|
+
No `className`. Keyboard: Enter and Space toggle. Clicks and those keys stop
|
|
28
|
+
propagation, so a switch inside a clickable card row won't trigger the row.
|
|
29
|
+
|
|
30
|
+
## Choosing a radius
|
|
31
|
+
|
|
32
|
+
See [corners](../corners.md).
|
|
33
|
+
|
|
34
|
+
- In a shaded row (`layout="horizontal"`, or inside any field row): omit it
|
|
35
|
+
(`inset`, a 4px track concentric with the row's 8px corner).
|
|
36
|
+
- In a `Card` header (`headerAction`), or anywhere with no nearby corner to
|
|
37
|
+
echo: `radius="pill"`.
|
|
38
|
+
|
|
39
|
+
## Examples
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
// A form setting inside a Card.
|
|
43
|
+
<Switch
|
|
44
|
+
name="bwCover"
|
|
45
|
+
label="Grayscale"
|
|
46
|
+
layout="horizontal"
|
|
47
|
+
description="Convert cover to grayscale for monochrome screens."
|
|
48
|
+
checked={bwCover}
|
|
49
|
+
onChange={setBwCover}
|
|
50
|
+
/>
|
|
51
|
+
|
|
52
|
+
// In a Card header: pill.
|
|
53
|
+
<Card
|
|
54
|
+
title="Series"
|
|
55
|
+
headerAction={
|
|
56
|
+
<Switch name="isSeries" ariaLabel="Part of a series" radius="pill"
|
|
57
|
+
checked={isSeries} onChange={setIsSeries} />
|
|
58
|
+
}
|
|
59
|
+
>…</Card>
|
|
60
|
+
|
|
61
|
+
// Saving straight to the server.
|
|
62
|
+
<Switch name="push-device" label="This device" checked={subscribed}
|
|
63
|
+
loading={busy} disabled={!supported} onChange={toggleSubscription} />
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Do / don't
|
|
67
|
+
|
|
68
|
+
- Do pass `loading` while the save runs instead of `disabled`; `disabled` means
|
|
69
|
+
"you may not change this".
|
|
70
|
+
- Do give a label-less switch an `ariaLabel`; `name` is a machine key.
|
|
71
|
+
- Don't expect a switch to submit with a `<form>`; send `checked` from state.
|
|
72
|
+
- Don't put an interactive element in `description` of a `horizontal` switch:
|
|
73
|
+
clicking it toggles the switch.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# TextArea
|
|
2
|
+
|
|
3
|
+
`import { TextArea } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A multi-line text field with an optional label, validation, an optional
|
|
6
|
+
auto-grow mode, and a character counter near `maxLength`. Same label/layout
|
|
7
|
+
system as `TextInput`.
|
|
8
|
+
|
|
9
|
+
Use something else for: single-line text (`TextInput`), tags (`ChipsInput`).
|
|
10
|
+
|
|
11
|
+
## Props
|
|
12
|
+
|
|
13
|
+
| Prop | Type | Default | Notes |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| `name` | `string` | (required) | The textarea's `name` and the key passed to `onValidChange`. |
|
|
16
|
+
| `value` | `string \| undefined` | `''` | Typed as required. Re-syncs into the field only when the prop changes. |
|
|
17
|
+
| `onChange` | `(value: string \| undefined) => void` | no-op | Receives the string, **`undefined` when emptied**, not an event. **Not called while `validate` fails.** |
|
|
18
|
+
| `label` | `string` | | Not linked to the textarea (no `htmlFor`). |
|
|
19
|
+
| `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row with `radius.md`. |
|
|
20
|
+
| `variant` | `'outlined' \| 'borderless'` | `'outlined'` | `outlined` uses the input recipe (border, `bg.input`); `borderless` drops the border (keeps `radius.md`) and sets no background of its own, so the browser's default textarea background shows; check it in dark mode. |
|
|
21
|
+
| `autoResize` | `boolean` | `false` | Grows to fit content (no scrollbar). Min height 7rem with it, 10rem without; set inline, so a class can't lower it. |
|
|
22
|
+
| `maxLength` | `number` | | Native limit, plus a `n/max` counter once within `max(10% of max, 50)` characters; red at the limit. |
|
|
23
|
+
| `placeholder` | `string` | | |
|
|
24
|
+
| `validate` | `(value: string) => boolean` | `() => true` | `false` turns the label red. |
|
|
25
|
+
| `onValidChange` | `(name: string, valid: boolean) => void` | no-op | Fires only when validity flips. |
|
|
26
|
+
|
|
27
|
+
No `className`, no `disabled`, no `rows`, never resizable by the user
|
|
28
|
+
(`resize: none`).
|
|
29
|
+
|
|
30
|
+
## Examples
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
// A note field in a Card form (default horizontal layout).
|
|
34
|
+
<TextArea name="note" label="Note" value={note} onChange={setNote} />
|
|
35
|
+
|
|
36
|
+
// A long description that grows as the user types, label above.
|
|
37
|
+
<TextArea
|
|
38
|
+
name="description"
|
|
39
|
+
layout="vertical"
|
|
40
|
+
autoResize
|
|
41
|
+
maxLength={3000}
|
|
42
|
+
value={description}
|
|
43
|
+
onChange={setDescription}
|
|
44
|
+
/>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Do / don't
|
|
48
|
+
|
|
49
|
+
- Do use `autoResize` for long free text so the card doesn't scroll inside itself.
|
|
50
|
+
- Do set `maxLength` when the server has a limit; the counter only appears near it.
|
|
51
|
+
- Don't expect `onChange('')`; an empty field reports `undefined`.
|
|
52
|
+
- Don't try to shrink it below 7rem / 10rem with CSS; the min height is inline.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# TextInput
|
|
2
|
+
|
|
3
|
+
`import { TextInput } from '@korzun/design/control'`
|
|
4
|
+
|
|
5
|
+
A single-line text (or password) field with an optional label, optional
|
|
6
|
+
validation, and a character counter that appears near `maxLength`. The default
|
|
7
|
+
`horizontal` layout puts the label and field on one shaded row, which is how
|
|
8
|
+
form fields look inside a `Card`.
|
|
9
|
+
|
|
10
|
+
Use something else for: multi-line text (`TextArea`), numbers (`NumberInput`),
|
|
11
|
+
picking from a list (`Select`), a list of tags (`ChipsInput`), dates
|
|
12
|
+
(`DateTimeInput`).
|
|
13
|
+
|
|
14
|
+
## Props
|
|
15
|
+
|
|
16
|
+
| Prop | Type | Default | Notes |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| `name` | `string` | (required) | The input's `name` (form data) and the key passed to `onValidChange`. |
|
|
19
|
+
| `value` | `string \| undefined` | `''` | Typed as required: pass it, even as `undefined`. See "Controlled-ish" below. |
|
|
20
|
+
| `onChange` | `(value: string \| undefined) => void` | no-op | Receives the string, **`undefined` when the field is emptied**, not an event. **Not called while `validate` fails.** |
|
|
21
|
+
| `label` | `string` | | Visible label. Not linked to the input (`<label>` has no `htmlFor`). |
|
|
22
|
+
| `layout` | `'horizontal' \| 'vertical' \| 'inline'` | `'horizontal'` | `horizontal`/`vertical` paint a `bg.cardHeader` row with `radius.md`; `inline` paints nothing. |
|
|
23
|
+
| `placeholder` | `string` | | |
|
|
24
|
+
| `password` | `boolean` | `false` | Renders `type="password"`. |
|
|
25
|
+
| `maxLength` | `number` | | Native limit, plus a `n/max` counter once within `max(10% of max, 10)` characters; red at the limit. |
|
|
26
|
+
| `validate` | `(value: string) => boolean` | `() => true` | Runs on each keystroke. `false` turns the label and border red. |
|
|
27
|
+
| `onValidChange` | `(name: string, valid: boolean) => void` | no-op | Fires only when validity flips. |
|
|
28
|
+
| `onKeyDown` | `(event: KeyboardEvent<HTMLInputElement>) => void` | | Passed through; this one does receive the event. |
|
|
29
|
+
| `autoComplete` | `HTMLInputAutoCompleteAttribute` | | Passed through. |
|
|
30
|
+
| `autoCapitalize` | `'none' \| 'sentences' \| 'words' \| 'characters'` | | Passed through. |
|
|
31
|
+
| `action` | `{ icon, action, danger? }` | | **Broken: do not use.** The icon button is drawn but its `action` callback is never wired up, so clicking does nothing. |
|
|
32
|
+
|
|
33
|
+
No `className`, no `disabled`, no `id`.
|
|
34
|
+
|
|
35
|
+
## Controlled-ish
|
|
36
|
+
|
|
37
|
+
The field keeps its own text. It re-syncs from `value` only when the `value`
|
|
38
|
+
prop changes. While `validate` fails, the field shows the invalid text but
|
|
39
|
+
`onChange` is not called, so your state keeps the last valid value. Track
|
|
40
|
+
`onValidChange` to block submit.
|
|
41
|
+
|
|
42
|
+
## Examples
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
// Inside a Card form: default horizontal layout.
|
|
46
|
+
<TextInput
|
|
47
|
+
name="new-password"
|
|
48
|
+
label="New"
|
|
49
|
+
password
|
|
50
|
+
autoComplete="new-password"
|
|
51
|
+
value={newPassword}
|
|
52
|
+
onChange={(v) => setNewPassword(v ?? '')}
|
|
53
|
+
/>
|
|
54
|
+
|
|
55
|
+
// Validated, reporting validity to the form.
|
|
56
|
+
<TextInput
|
|
57
|
+
name="name"
|
|
58
|
+
label="Name"
|
|
59
|
+
maxLength={64}
|
|
60
|
+
validate={(v) => v.length <= 64}
|
|
61
|
+
onValidChange={(field, ok) => setValid((s) => ({ ...s, [field]: ok }))}
|
|
62
|
+
value={name}
|
|
63
|
+
onChange={setName}
|
|
64
|
+
/>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Do / don't
|
|
68
|
+
|
|
69
|
+
- Do keep the default `horizontal` layout for fields in a `Card` body; use
|
|
70
|
+
`vertical` when the label is long or the field is wide.
|
|
71
|
+
- Do coalesce `undefined` (`v ?? ''`) if your state is a plain string.
|
|
72
|
+
- Don't pass an `action`; render a separate `Button` beside the field instead.
|
|
73
|
+
- Don't rely on clicking the label to focus the field; it isn't associated.
|