@korzun/design 0.0.6 → 0.2.0
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 +11 -4
- package/dist/component/heading/index.d.ts +303 -0
- package/dist/component/heading/index.d.ts.map +1 -0
- package/dist/component/heading/index.js +21 -0
- package/dist/component/heading/index.js.map +1 -0
- package/dist/component/heading/style.d.ts +5 -0
- package/dist/component/heading/style.d.ts.map +1 -0
- package/dist/component/heading/style.js +5 -0
- package/dist/component/heading/style.js.map +1 -0
- package/dist/component/index.d.ts +4 -0
- package/dist/component/index.d.ts.map +1 -1
- package/dist/component/index.js +4 -0
- package/dist/component/index.js.map +1 -1
- package/dist/component/inline/index.d.ts +303 -0
- package/dist/component/inline/index.d.ts.map +1 -0
- package/dist/component/inline/index.js +13 -0
- package/dist/component/inline/index.js.map +1 -0
- package/dist/component/inline/style.d.ts +5 -0
- package/dist/component/inline/style.d.ts.map +1 -0
- package/dist/component/inline/style.js +18 -0
- package/dist/component/inline/style.js.map +1 -0
- package/dist/component/stack/gap.d.ts +4 -0
- package/dist/component/stack/gap.d.ts.map +1 -0
- package/dist/component/stack/gap.js +10 -0
- package/dist/component/stack/gap.js.map +1 -0
- package/dist/component/stack/index.d.ts +299 -0
- package/dist/component/stack/index.d.ts.map +1 -0
- package/dist/component/stack/index.js +13 -0
- package/dist/component/stack/index.js.map +1 -0
- package/dist/component/stack/style.d.ts +5 -0
- package/dist/component/stack/style.d.ts.map +1 -0
- package/dist/component/stack/style.js +12 -0
- package/dist/component/stack/style.js.map +1 -0
- package/dist/component/tag/index.d.ts +1 -1
- package/dist/component/tag/index.d.ts.map +1 -1
- package/dist/component/tag/index.js.map +1 -1
- package/dist/component/tag/style.d.ts +1 -1
- package/dist/component/tag/style.d.ts.map +1 -1
- package/dist/component/text/index.d.ts +307 -0
- package/dist/component/text/index.d.ts.map +1 -0
- package/dist/component/text/index.js +15 -0
- package/dist/component/text/index.js.map +1 -0
- package/dist/component/text/style.d.ts +11 -0
- package/dist/component/text/style.d.ts.map +1 -0
- package/dist/component/text/style.js +48 -0
- package/dist/component/text/style.js.map +1 -0
- package/dist/control/index.d.ts +1 -1
- package/dist/control/index.d.ts.map +1 -1
- package/dist/control/index.js +1 -1
- package/dist/control/index.js.map +1 -1
- package/dist/control/popover/index.d.ts +24 -8
- package/dist/control/popover/index.d.ts.map +1 -1
- package/dist/control/popover/index.js +60 -15
- package/dist/control/popover/index.js.map +1 -1
- package/dist/control/popover/position.d.ts +47 -0
- package/dist/control/popover/position.d.ts.map +1 -0
- package/dist/control/popover/position.js +29 -0
- package/dist/control/popover/position.js.map +1 -0
- package/dist/theme/theme.d.ts +25 -0
- package/dist/theme/theme.d.ts.map +1 -1
- package/dist/theme/theme.js +43 -1
- package/dist/theme/theme.js.map +1 -1
- package/docs/component/heading.md +85 -0
- package/docs/component/inline.md +64 -0
- package/docs/component/meta-line.md +13 -17
- package/docs/component/metadata-list.md +1 -1
- package/docs/component/stack.md +68 -0
- package/docs/component/tag.md +26 -6
- package/docs/component/text.md +94 -0
- package/docs/control/popover.md +41 -10
- package/docs/patterns.md +28 -9
- package/docs/theme.md +10 -9
- package/docs/tokens.md +4 -4
- package/package.json +1 -1
- package/src/component/heading/index.tsx +64 -0
- package/src/component/heading/style.ts +5 -0
- package/src/component/index.ts +4 -0
- package/src/component/inline/index.tsx +57 -0
- package/src/component/inline/style.ts +18 -0
- package/src/component/stack/gap.ts +16 -0
- package/src/component/stack/index.tsx +49 -0
- package/src/component/stack/style.ts +12 -0
- package/src/component/tag/index.tsx +1 -1
- package/src/component/text/index.tsx +61 -0
- package/src/component/text/style.ts +67 -0
- package/src/control/index.ts +6 -1
- package/src/control/popover/index.tsx +77 -19
- package/src/control/popover/position.ts +66 -0
- package/src/theme/theme.ts +59 -2
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Heading
|
|
2
|
+
|
|
3
|
+
`import { Heading, type HeadingProps } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A heading. `level` is the semantics (which `h1` to `h4` element renders) and
|
|
6
|
+
also picks a default look; `size`, `tone` and `weight` are the look and
|
|
7
|
+
override those defaults. Use it for a page title, a section title, a card
|
|
8
|
+
title.
|
|
9
|
+
|
|
10
|
+
Use something else for: body or meta text (`Text`), a collapsible section
|
|
11
|
+
header (`CollapsibleSection`), an empty-state title (`EmptyState`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
| ----------- | ------------------------------------------------------------------------------------------ | ------------ | ----------------------------------------------------- |
|
|
17
|
+
| `level` | `1 \| 2 \| 3 \| 4` | required | Renders `h1` to `h4`. |
|
|
18
|
+
| `size` | `keyof Theme['fontSize']` | from `level` | `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`. |
|
|
19
|
+
| `tone` | `'primary' \| 'secondary' \| 'muted' \| 'faint' \| 'description' \| 'danger' \| 'success'` | `'primary'` | Text colour. |
|
|
20
|
+
| `weight` | `keyof Theme['fontWeight']` | from `level` | `regular`, `medium`, `semibold`, `bold`, `extrabold`. |
|
|
21
|
+
| `truncate` | `boolean` | `false` | One line, clipped with an ellipsis. |
|
|
22
|
+
| `className` | `string` | | Added last on the root. |
|
|
23
|
+
| `children` | `ReactNode` | | |
|
|
24
|
+
| `ref` | `Ref<HTMLHeadingElement>` | | Ref to the root element. |
|
|
25
|
+
|
|
26
|
+
Every other HTML attribute (`id`, `aria-*`, `data-*`, event handlers) passes
|
|
27
|
+
through. There is no `style` prop and no `as` prop.
|
|
28
|
+
|
|
29
|
+
## Level defaults
|
|
30
|
+
|
|
31
|
+
| `level` | Element | `size` | `weight` |
|
|
32
|
+
| ------- | ------- | ------ | ---------- |
|
|
33
|
+
| 1 | `h1` | `xxl` | `bold` |
|
|
34
|
+
| 2 | `h2` | `xl` | `bold` |
|
|
35
|
+
| 3 | `h3` | `lg` | `semibold` |
|
|
36
|
+
| 4 | `h4` | `md` | `semibold` |
|
|
37
|
+
|
|
38
|
+
Tone is `primary` at every level. A `size` or `weight` you set wins over the
|
|
39
|
+
level default.
|
|
40
|
+
|
|
41
|
+
## Behaviour
|
|
42
|
+
|
|
43
|
+
- **Level is the semantics, props are the look.** Pick `level` for the document
|
|
44
|
+
outline (one `h1` per page, no skipped levels), then use `size`, `weight` and
|
|
45
|
+
`tone` to change how it looks. Never pick a level for its size.
|
|
46
|
+
- The margin is reset to 0 and the line height is the theme's `tight` value;
|
|
47
|
+
space headings with `Stack` `gap`.
|
|
48
|
+
- `truncate` adds `overflow: hidden`, an ellipsis, `white-space: nowrap` and
|
|
49
|
+
`min-width: 0` and `max-width: 100%`, so a truncated Heading clips inside an
|
|
50
|
+
`Inline` or `Stack` with any `align`.
|
|
51
|
+
- Override with `className` at `'&&'` specificity, never `!important`.
|
|
52
|
+
|
|
53
|
+
## Examples
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
// Page title.
|
|
57
|
+
<Heading level={1}>Library</Heading>
|
|
58
|
+
|
|
59
|
+
// Section title in a recipe.
|
|
60
|
+
<Stack gap="md">
|
|
61
|
+
<Inline justify="between">
|
|
62
|
+
<Heading level={2}>Library</Heading>
|
|
63
|
+
<Button type="primary">Add book</Button>
|
|
64
|
+
</Inline>
|
|
65
|
+
<Text as="p" size="sm" tone="muted">3 books, updated yesterday</Text>
|
|
66
|
+
</Stack>
|
|
67
|
+
|
|
68
|
+
// A small h2 inside a card: the level stays 2, the look shrinks.
|
|
69
|
+
<Heading level={2} size="sm" weight="medium" tone="muted">Details</Heading>
|
|
70
|
+
|
|
71
|
+
// A title that shrinks next to an action.
|
|
72
|
+
<Inline justify="between">
|
|
73
|
+
<Heading level={3} truncate>{book.title}</Heading>
|
|
74
|
+
<Button type="primary">Open</Button>
|
|
75
|
+
</Inline>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Do / don't
|
|
79
|
+
|
|
80
|
+
- Do keep the outline in order: `h1`, then `h2`, then `h3`.
|
|
81
|
+
- Do override `size` and `weight` for a different look at the same level.
|
|
82
|
+
- Do put `truncate` on the Heading itself, not on a wrapper.
|
|
83
|
+
- Don't pick a level to get a size; set `size`.
|
|
84
|
+
- Don't use `Heading` for body text; use `Text`.
|
|
85
|
+
- Don't add margins to space headings; use `Stack`.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Inline
|
|
2
|
+
|
|
3
|
+
`import { Inline, type InlineProps } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A horizontal flex row with a themed gap between children, vertically centred
|
|
6
|
+
by default. Use it for a button group, a header with an action on the right,
|
|
7
|
+
or a row of chips that wraps.
|
|
8
|
+
|
|
9
|
+
Use something else for: a vertical column (`Stack`), a single chip
|
|
10
|
+
(`Tag`), a line of small metadata (`MetaLine`).
|
|
11
|
+
|
|
12
|
+
## Props
|
|
13
|
+
|
|
14
|
+
| Prop | Type | Default | Notes |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `gap` | `keyof Theme['space'] \| 'none'` | `'sm'` | Space between children, from the theme's `space` tokens. |
|
|
17
|
+
| `align` | `'center' \| 'start' \| 'end' \| 'baseline' \| 'stretch'` | `'center'` | Cross-axis (vertical) alignment. `start`/`end` map to `flex-start`/`flex-end`. |
|
|
18
|
+
| `justify` | `'start' \| 'center' \| 'end' \| 'between'` | `'start'` | Main-axis distribution. `between` is `space-between`. |
|
|
19
|
+
| `wrap` | `boolean` | `false` | Wrap children onto more lines. |
|
|
20
|
+
| `as` | `'div' \| 'span' \| 'ul' \| 'ol' \| 'li' \| 'nav'` | `'div'` | The element to render. |
|
|
21
|
+
| `className` | `string` | | Added last on the root. |
|
|
22
|
+
| `children` | `ReactNode` | | |
|
|
23
|
+
| `ref` | `Ref<HTMLElement>` | | Ref to the root element. |
|
|
24
|
+
|
|
25
|
+
Every other HTML attribute (`id`, `aria-*`, `data-*`, event handlers) passes
|
|
26
|
+
through. There is no `style` prop.
|
|
27
|
+
|
|
28
|
+
## Behaviour
|
|
29
|
+
|
|
30
|
+
- `gap="none"` emits `gap: 0`.
|
|
31
|
+
- `as="ul"` and `as="ol"` also reset the list's margin, padding and bullets.
|
|
32
|
+
- Override with `className` at `'&&'` specificity, never `!important`.
|
|
33
|
+
- No `style` prop: spacing comes from tokens only.
|
|
34
|
+
- Without `wrap`, children stay on one line and may overflow or shrink.
|
|
35
|
+
|
|
36
|
+
## Examples
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
// The spread row: title on the left, action on the right.
|
|
40
|
+
<Inline justify="between">
|
|
41
|
+
<Heading level={2}>Library</Heading>
|
|
42
|
+
<Button type="primary">Add book</Button>
|
|
43
|
+
</Inline>
|
|
44
|
+
|
|
45
|
+
// Chips that wrap.
|
|
46
|
+
<Inline wrap gap="xs">
|
|
47
|
+
{subjects.map((s) => <Tag key={s}>{s}</Tag>)}
|
|
48
|
+
</Inline>
|
|
49
|
+
|
|
50
|
+
// Navigation links.
|
|
51
|
+
<Inline as="nav" gap="xl">
|
|
52
|
+
<a href="/books">Books</a>
|
|
53
|
+
<a href="/authors">Authors</a>
|
|
54
|
+
</Inline>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Do / don't
|
|
58
|
+
|
|
59
|
+
- Do use `justify="between"` for a title-and-action row.
|
|
60
|
+
- Do add `wrap` for rows of chips or buttons that may not fit on a phone.
|
|
61
|
+
- Do use `align="baseline"` to line up text of different sizes.
|
|
62
|
+
- Don't add margins to children to space them; use `gap`.
|
|
63
|
+
- Don't use an Inline for a column; use `Stack`.
|
|
64
|
+
- Don't nest `Inline` just to push one child right; use `justify="between"`.
|
|
@@ -9,7 +9,7 @@ line. The separators are CSS (`::before`), not text, so screen readers read
|
|
|
9
9
|
only the data.
|
|
10
10
|
|
|
11
11
|
Use something else for: labelled key/value pairs (`MetadataList`), a row's
|
|
12
|
-
primary title (
|
|
12
|
+
primary title (`Text` or `Heading`).
|
|
13
13
|
|
|
14
14
|
## Props
|
|
15
15
|
|
|
@@ -25,36 +25,32 @@ primary title (your own styled element).
|
|
|
25
25
|
separator with nothing (or `0`) after it; filter them yourself.
|
|
26
26
|
- A single datum wider than the line ellipsizes instead of wrapping.
|
|
27
27
|
- MetaLine sets no font size or colour of its own except the separator colour
|
|
28
|
-
(`text.muted`);
|
|
28
|
+
(`text.muted`); wrap it in `Text` to set the rest.
|
|
29
29
|
- Items are keyed by index.
|
|
30
30
|
|
|
31
31
|
## Examples
|
|
32
32
|
|
|
33
33
|
```tsx
|
|
34
34
|
// A book row's secondary line.
|
|
35
|
-
<
|
|
36
|
-
<
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
/>
|
|
35
|
+
<Text weight="semibold">{book.title}</Text>
|
|
36
|
+
<Text as="div" size="sm" tone="faint">
|
|
37
|
+
<MetaLine
|
|
38
|
+
items={[
|
|
39
|
+
book.author,
|
|
40
|
+
book.series && `${book.series.name} #${book.seriesIndex}`,
|
|
41
|
+
book.progress !== undefined && `${Math.round(book.progress * 100)}%`,
|
|
42
|
+
]}
|
|
43
|
+
/>
|
|
44
|
+
</Text>
|
|
44
45
|
|
|
45
46
|
// Elements are fine as items.
|
|
46
47
|
<MetaLine items={[<time dateTime={iso}>{formatted}</time>, device.label]} />
|
|
47
48
|
```
|
|
48
49
|
|
|
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
50
|
## Do / don't
|
|
55
51
|
|
|
56
52
|
- Do pass conditional data as `cond && value`; `false` is skipped.
|
|
57
|
-
- Do set typography
|
|
53
|
+
- Do set typography by wrapping the line in `Text` (`size`, `tone`); the items inherit it.
|
|
58
54
|
- Don't join data into one string with your own " · ": wrapping then breaks
|
|
59
55
|
inside a datum and the dots are read aloud.
|
|
60
56
|
- Don't pass empty strings; they leave a stray separator.
|
|
@@ -46,7 +46,7 @@ No `className`.
|
|
|
46
46
|
{ title: 'Slug', value: device.slug },
|
|
47
47
|
{ title: 'Cover size', value: `${device.coverWidth}×${device.coverHeight}` },
|
|
48
48
|
{ title: 'Grayscale cover', value: device.bwCover ? 'Yes' : 'No' },
|
|
49
|
-
{ title: 'Status', value: <Tag size="sm" tone="
|
|
49
|
+
{ title: 'Status', value: <Tag size="sm" tone="success">Active</Tag> },
|
|
50
50
|
]}
|
|
51
51
|
/>
|
|
52
52
|
</Card>
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Stack
|
|
2
|
+
|
|
3
|
+
`import { Stack, type StackProps } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A vertical flex column with a themed gap between children. Use it to space
|
|
6
|
+
things on a screen instead of writing a style file: a form's fields, the
|
|
7
|
+
sections of a page, the rows of a list.
|
|
8
|
+
|
|
9
|
+
Use something else for: a horizontal row (`Inline`), a bordered surface
|
|
10
|
+
(`Card`), a divider line between items (`CardDivider`), text styling (`Text`,
|
|
11
|
+
`Heading`).
|
|
12
|
+
|
|
13
|
+
## Props
|
|
14
|
+
|
|
15
|
+
| Prop | Type | Default | Notes |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `gap` | `keyof Theme['space'] \| 'none'` | `'md'` | Space between children, from the theme's `space` tokens. |
|
|
18
|
+
| `align` | `'stretch' \| 'start' \| 'center' \| 'end'` | `'stretch'` | Cross-axis (horizontal) alignment. `start`/`end` map to `flex-start`/`flex-end`. |
|
|
19
|
+
| `as` | `'div' \| 'section' \| 'ul' \| 'ol' \| 'li'` | `'div'` | The element to render. |
|
|
20
|
+
| `className` | `string` | | Added last on the root. |
|
|
21
|
+
| `children` | `ReactNode` | | |
|
|
22
|
+
| `ref` | `Ref<HTMLElement>` | | Ref to the root element. |
|
|
23
|
+
|
|
24
|
+
Every other HTML attribute (`id`, `aria-*`, `data-*`, event handlers) passes
|
|
25
|
+
through. There is no `style` prop.
|
|
26
|
+
|
|
27
|
+
## Behaviour
|
|
28
|
+
|
|
29
|
+
- `gap="none"` emits `gap: 0`, for children that supply their own spacing.
|
|
30
|
+
- `as="ul"` and `as="ol"` also reset the list's margin, padding and bullets.
|
|
31
|
+
Children should be `li` (`<Stack as="li">` works).
|
|
32
|
+
- Override with `className` at `'&&'` specificity, never `!important`.
|
|
33
|
+
- No `style` prop: spacing comes from tokens only.
|
|
34
|
+
- `as="form"` is not offered. Put a `<form>` around the Stack instead.
|
|
35
|
+
|
|
36
|
+
## Examples
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
// A form's fields.
|
|
40
|
+
<form noValidate onSubmit={onSubmit}>
|
|
41
|
+
<Stack gap="md">
|
|
42
|
+
<TextInput name="title" label="Title" value={title} onChange={setTitle} />
|
|
43
|
+
<TextInput name="author" label="Author" value={author} onChange={setAuthor} />
|
|
44
|
+
<Button type="primary" submit>Save</Button>
|
|
45
|
+
</Stack>
|
|
46
|
+
</form>
|
|
47
|
+
|
|
48
|
+
// A semantic list.
|
|
49
|
+
<Stack as="ul" gap="xs">
|
|
50
|
+
{items.map((i) => <Stack as="li" key={i.id} gap="none">{i.name}</Stack>)}
|
|
51
|
+
</Stack>
|
|
52
|
+
|
|
53
|
+
// Children sized to their content, left aligned.
|
|
54
|
+
<Stack align="start">
|
|
55
|
+
<Tag>One</Tag>
|
|
56
|
+
<Tag>Two</Tag>
|
|
57
|
+
</Stack>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Do / don't
|
|
61
|
+
|
|
62
|
+
- Do pick `gap` from the scale (`xs` tight, `md` default, `xxl` between
|
|
63
|
+
sections) so spacing is the same everywhere.
|
|
64
|
+
- Do nest a Stack in a Stack for sections with different gaps.
|
|
65
|
+
- Do use `align="start"` when children (buttons, tags) should not stretch.
|
|
66
|
+
- Don't add margins to children to space them; use `gap`.
|
|
67
|
+
- Don't reach for `className` to set a gap; use the prop.
|
|
68
|
+
- Don't use a Stack for a row; use `Inline`.
|
package/docs/component/tag.md
CHANGED
|
@@ -23,12 +23,26 @@ No `className`, no `ariaLabel`.
|
|
|
23
23
|
|
|
24
24
|
## Choosing a tone
|
|
25
25
|
|
|
26
|
-
`TagTone` is `keyof Theme['color']['chip']
|
|
27
|
-
|
|
26
|
+
`TagTone` is `keyof Theme['color']['chip']`. There are two groups: label tones
|
|
27
|
+
are **domain names** (what kind of thing the tag names) and status tones are
|
|
28
|
+
**meanings** (what state it reports). Neither group is a set of colour names:
|
|
29
|
+
never pick a tone for its colour. Pick by what the tag *is*:
|
|
30
|
+
|
|
31
|
+
Status tones report a state:
|
|
32
|
+
|
|
33
|
+
| Tone | Use for |
|
|
34
|
+
|---|---|
|
|
35
|
+
| `success` | Something went well (Published, Paid). |
|
|
36
|
+
| `warning` | Needs attention soon (Overdue, Expiring). |
|
|
37
|
+
| `danger` | Something failed or is blocked (Failed, Rejected). |
|
|
38
|
+
| `info` | Neutral news (Scheduled, New). |
|
|
39
|
+
| `neutral` | A state with no category ("no change"): quiet grey. |
|
|
40
|
+
|
|
41
|
+
Label tones name a kind of thing:
|
|
28
42
|
|
|
29
43
|
| Tone | Use for |
|
|
30
44
|
|---|---|
|
|
31
|
-
| `status` |
|
|
45
|
+
| `status` | Legacy; kept for Bookplate's existing chips. Don't pick it for new state tags. |
|
|
32
46
|
| `author` | A person who wrote something. |
|
|
33
47
|
| `series` | A series name. |
|
|
34
48
|
| `subject` | A subject / genre / keyword. The default. |
|
|
@@ -36,7 +50,8 @@ not colour names. Pick by what the tag *is*:
|
|
|
36
50
|
| `entryType` | The kind of an entry or record. |
|
|
37
51
|
| `user` | An app user / account. |
|
|
38
52
|
| `rating` | A rating value. |
|
|
39
|
-
|
|
53
|
+
|
|
54
|
+
Note the name clash: `status` is a legacy label tone despite its name; for a state use `success`/`warning`/`danger`/`info`, or `neutral` when it carries no meaning.
|
|
40
55
|
|
|
41
56
|
Each tone has its own `text`, `bg`, and `border` in both light and dark themes.
|
|
42
57
|
A consumer's theme can't add tones; the list is fixed by the `Theme` type.
|
|
@@ -52,8 +67,8 @@ A consumer's theme can't add tones; the list is fixed by the `Theme` type.
|
|
|
52
67
|
// Compact chips in a review row (inside a card).
|
|
53
68
|
{fix.toChips.map((c) => <Tag key={c} size="sm">{c}</Tag>)}
|
|
54
69
|
|
|
55
|
-
// A
|
|
56
|
-
<Tag size="sm" tone="
|
|
70
|
+
// A state with no meaning to signal: neutral.
|
|
71
|
+
<Tag size="sm" tone="neutral">{write ? 'Read & write' : 'Read only'}</Tag>
|
|
57
72
|
|
|
58
73
|
// A clickable author chip that filters the list.
|
|
59
74
|
<Tag tone="author" onClick={() => setFilter({ author: name })}>{name}</Tag>
|
|
@@ -63,7 +78,12 @@ A consumer's theme can't add tones; the list is fixed by the `Theme` type.
|
|
|
63
78
|
|
|
64
79
|
- Do choose `tone` by meaning, so the same kind of thing is the same colour
|
|
65
80
|
everywhere.
|
|
81
|
+
- Do use `tone="warning"` for "Overdue".
|
|
66
82
|
- Do use `size="sm"` inside text rows and lists.
|
|
67
83
|
- Don't use `neutral` just to make a tag grey when it has a category.
|
|
84
|
+
- Don't use `subject` or `author` to mean warning or success.
|
|
85
|
+
- Don't use `info` to look like a link (it shares a hue with links; use
|
|
86
|
+
`Button type="link"` for actions).
|
|
87
|
+
- Don't use `status` for a new state tag; it is a legacy label tone.
|
|
68
88
|
- Don't nest a clickable Tag inside another clickable element (Button, a
|
|
69
89
|
clickable Card); both would fire.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Text
|
|
2
|
+
|
|
3
|
+
`import { Text, type TextProps } from '@korzun/design/component'`
|
|
4
|
+
|
|
5
|
+
A run of text with themed size, tone and weight. Use it to set text style by
|
|
6
|
+
prop instead of a style file: a body line, a meta line, a caption, an inline
|
|
7
|
+
error.
|
|
8
|
+
|
|
9
|
+
**Unset props inherit.** A bare `<Text>` adds no size, tone or weight, so it
|
|
10
|
+
looks exactly like the text around it. This keeps the look inside a `Tag`, a
|
|
11
|
+
`Button` or an error block: set only what you want to change.
|
|
12
|
+
|
|
13
|
+
Use something else for: a heading (`Heading`), a single chip (`Tag`), a line
|
|
14
|
+
of small metadata (`MetaLine`), a boxed alert (an Alert component comes later).
|
|
15
|
+
|
|
16
|
+
## Props
|
|
17
|
+
|
|
18
|
+
| Prop | Type | Default | Notes |
|
|
19
|
+
| ----------- | ------------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------- |
|
|
20
|
+
| `as` | `'span' \| 'p' \| 'div' \| 'label' \| 'strong' \| 'em'` | `'span'` | The element to render. |
|
|
21
|
+
| `size` | `keyof Theme['fontSize']` | inherit | `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`. |
|
|
22
|
+
| `tone` | `'primary' \| 'secondary' \| 'muted' \| 'faint' \| 'description' \| 'danger' \| 'success'` | inherit | Text colour. |
|
|
23
|
+
| `weight` | `keyof Theme['fontWeight']` | inherit | `regular`, `medium`, `semibold`, `bold`, `extrabold`. |
|
|
24
|
+
| `truncate` | `boolean` | `false` | One line, clipped with an ellipsis. |
|
|
25
|
+
| `htmlFor` | `string` | | Only for `as="label"`. |
|
|
26
|
+
| `className` | `string` | | Added last on the root. |
|
|
27
|
+
| `children` | `ReactNode` | | |
|
|
28
|
+
| `ref` | `Ref<HTMLElement>` | | Ref to the root element. |
|
|
29
|
+
|
|
30
|
+
Every other HTML attribute (`id`, `aria-*`, `data-*`, event handlers) passes
|
|
31
|
+
through. There is no `style` prop.
|
|
32
|
+
|
|
33
|
+
## Behaviour
|
|
34
|
+
|
|
35
|
+
- `tone` is not `Tag`'s `TagTone` union. `primary` to `description` map to the
|
|
36
|
+
theme's `color.text.*`; `danger` and `success` use the chip text colours.
|
|
37
|
+
- `danger` and `success` are for inline error and confirmation text. A boxed
|
|
38
|
+
Alert comes later.
|
|
39
|
+
- `truncate` adds `overflow: hidden`, an ellipsis, `white-space: nowrap`,
|
|
40
|
+
`min-width: 0` and `max-width: 100%`, so a truncated Text clips inside an
|
|
41
|
+
`Inline` or `Stack` with any `align`, and a `Stack` or `Inline` nested in a
|
|
42
|
+
row shrinks too (both roots have `min-width: 0`).
|
|
43
|
+
- On `span`, `strong`, `em` and `label`, `truncate` also makes the element
|
|
44
|
+
`inline-block`, because inline elements ignore overflow. `p` and `div` keep their block display.
|
|
45
|
+
- `as="p"` has its margin reset to 0; space paragraphs with `Stack` `gap`.
|
|
46
|
+
- Override with `className` at `'&&'` specificity, never `!important`.
|
|
47
|
+
|
|
48
|
+
## Examples
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
// Body text: inherits everything.
|
|
52
|
+
<Text>Welcome back.</Text>
|
|
53
|
+
|
|
54
|
+
// Meta line.
|
|
55
|
+
<Text as="p" size="sm" tone="muted">3 books, updated yesterday</Text>
|
|
56
|
+
|
|
57
|
+
// Caption.
|
|
58
|
+
<Text as="p" size="xs" tone="faint">Cover art by the publisher</Text>
|
|
59
|
+
|
|
60
|
+
// Inline error under a field.
|
|
61
|
+
<Text as="div" size="sm" tone="danger" aria-live="polite">{error}</Text>
|
|
62
|
+
|
|
63
|
+
// A title that shrinks next to an action.
|
|
64
|
+
<Inline justify="between">
|
|
65
|
+
<Text truncate weight="semibold">{book.title}</Text>
|
|
66
|
+
<Button type="primary">Open</Button>
|
|
67
|
+
</Inline>
|
|
68
|
+
|
|
69
|
+
// A stacked title and meta line beside an action: the title truncates, the
|
|
70
|
+
// Stack shrinks with the row.
|
|
71
|
+
<Inline justify="between">
|
|
72
|
+
<Stack gap="none">
|
|
73
|
+
<Text truncate weight="semibold">{book.title}</Text>
|
|
74
|
+
<Text size="sm" tone="muted">{book.author}</Text>
|
|
75
|
+
</Stack>
|
|
76
|
+
<Button type="primary">Open</Button>
|
|
77
|
+
</Inline>
|
|
78
|
+
|
|
79
|
+
// A label for a control.
|
|
80
|
+
<Stack gap="xs">
|
|
81
|
+
<Text as="label" htmlFor="title" size="sm" weight="medium">Title</Text>
|
|
82
|
+
<input id="title" name="title" />
|
|
83
|
+
</Stack>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Do / don't
|
|
87
|
+
|
|
88
|
+
- Do set only the props you need; leave the rest to inherit.
|
|
89
|
+
- Do use the recipes: body `<Text>`, meta `size="sm" tone="muted"`, caption
|
|
90
|
+
`size="xs" tone="faint"`.
|
|
91
|
+
- Do put `truncate` on the Text itself, not on a wrapper.
|
|
92
|
+
- Don't use `Text` for headings; use `Heading`.
|
|
93
|
+
- Don't set `tone="danger"` to build a box; it only colours text.
|
|
94
|
+
- Don't add margins to space text; use `Stack`.
|
package/docs/control/popover.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
`import { Popover } from '@korzun/design/control'`
|
|
4
4
|
|
|
5
5
|
A positioning primitive: renders `children` in a portal on `document.body`,
|
|
6
|
-
`position: fixed`
|
|
6
|
+
`position: fixed` below or above an anchor element, so a dropdown can escape
|
|
7
7
|
ancestors that clip overflow (rounded cards). It paints **nothing** itself: no
|
|
8
8
|
background, border, shadow, or radius. `Select` and `ChipsInput` build their
|
|
9
9
|
dropdowns on it.
|
|
@@ -15,24 +15,53 @@ Use something else for: a modal (`useModalDialog`), page action menus
|
|
|
15
15
|
|
|
16
16
|
| Prop | Type | Default | Notes |
|
|
17
17
|
|---|---|---|---|
|
|
18
|
-
| `anchorRef` | `RefObject<HTMLElement \| null>` | (required) | Element to
|
|
18
|
+
| `anchorRef` | `RefObject<HTMLElement \| null>` | (required) | Element to place against. |
|
|
19
19
|
| `open` | `boolean` | (required) | When `false`, renders nothing. Fully controlled. |
|
|
20
20
|
| `children` | `ReactNode` | (required) | Your surface: give it its own background, border, radius. |
|
|
21
|
-
| `
|
|
21
|
+
| `side` | `'bottom' \| 'top'` | `'bottom'` | Preferred side; flips to the other side when this one has no room. |
|
|
22
|
+
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Horizontal alignment to the anchor's left edge, centre, or right edge. |
|
|
23
|
+
| `gap` | `number` | `4` | Pixels between the anchor and the popover; also the margin kept from the viewport's left and right edges when `matchWidth` is false. |
|
|
22
24
|
| `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. |
|
|
25
|
+
| `onClose` | `() => void` | | Called on a mousedown outside both anchor and content, and on Escape (see below). Omit to opt out of both. Receives no event. |
|
|
24
26
|
| `className` | `string` | | Applied to the fixed wrapper. Override with `'&&'`, never `!important`. |
|
|
25
27
|
|
|
26
28
|
## Behaviour to know
|
|
27
29
|
|
|
28
|
-
- **
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
- **Flip.** It opens on `side`. If the content does not fit on that side and
|
|
31
|
+
the other side has more room, it opens on the other side. When neither side
|
|
32
|
+
fits it keeps whichever has more room.
|
|
33
|
+
- **Clamp.** Only when `matchWidth` is false: `left` is clamped so the
|
|
34
|
+
content stays `gap` pixels inside the viewport's left and right edges;
|
|
35
|
+
content wider than the viewport pins to `gap`. With `matchWidth` (the
|
|
36
|
+
default) it lines up with the anchor exactly, edge margin or not. There is
|
|
37
|
+
no vertical clamp.
|
|
38
|
+
- **Top side is anchored by its bottom edge** (CSS `bottom`), so a popover
|
|
39
|
+
above its anchor stays attached when its content grows or shrinks.
|
|
40
|
+
- **`data-side`.** The wrapper carries `data-side="bottom"` or `"top"`: the side
|
|
41
|
+
actually used after flipping. Style against it (an arrow, an animation
|
|
42
|
+
origin) rather than against the `side` prop.
|
|
43
|
+
- It re-measures, flip decision included, on window resize, on any scroll
|
|
44
|
+
(capture phase), and when its content resizes (`ResizeObserver`, where the
|
|
45
|
+
browser has it), so it stays attached to a scrolled anchor and to content
|
|
46
|
+
that changes size.
|
|
47
|
+
- Its first render is transparent (`opacity: 0`) and is measured in a layout
|
|
48
|
+
effect before paint, so it never flashes at 0,0 or on the wrong side. It is
|
|
49
|
+
not `visibility: hidden`, so an `autoFocus` child takes focus on mount.
|
|
50
|
+
- **Escape.** With `onClose`, an Escape keydown anywhere in the document calls
|
|
51
|
+
`onClose`, unless the event is already `defaultPrevented` (a control such as
|
|
52
|
+
`Select` handled it first). It calls `preventDefault()` on the key, so an
|
|
53
|
+
enclosing native `<dialog>` does not also fire `cancel` and close.
|
|
54
|
+
- **Nested popovers.** Each open popover listens on the document, so with
|
|
55
|
+
nested popovers Escape is taken by the one opened first (the outermost),
|
|
56
|
+
not the innermost. A proper layer stack comes with `Menu`.
|
|
57
|
+
- **No focus management.** Focus stays where it was; return it yourself if
|
|
58
|
+
closing should move it.
|
|
33
59
|
- z-index is `theme.zIndex.sticky` (1000). Inside a modal `<dialog>` opened with
|
|
34
60
|
`showModal()`, a body portal sits outside the dialog's top layer, so it is
|
|
35
61
|
likely hidden behind the dialog and inert. Test before using it there.
|
|
62
|
+
The reverse also bites: an open popover left behind a `showModal()` dialog
|
|
63
|
+
still takes Escape first, so the dialog does not close. Close popovers
|
|
64
|
+
before opening a dialog.
|
|
36
65
|
- Clicking the anchor does not count as "outside", so a toggle button on the
|
|
37
66
|
anchor works without racing `onClose`.
|
|
38
67
|
|
|
@@ -71,4 +100,6 @@ const [open, setOpen] = useState(false);
|
|
|
71
100
|
|
|
72
101
|
- Do wrap a `Button` in a `<div ref>` to anchor it; `Button` takes no ref.
|
|
73
102
|
- Do give the content its own surface and radius; the wrapper is transparent.
|
|
74
|
-
-
|
|
103
|
+
- Do call `preventDefault()` in your own Escape handler if you close the
|
|
104
|
+
popover yourself, so `onClose` is not called a second time.
|
|
105
|
+
- Don't expect it to close on selection; that is your code.
|
package/docs/patterns.md
CHANGED
|
@@ -25,7 +25,7 @@ export const SettingsPage = () => (
|
|
|
25
25
|
|
|
26
26
|
## A form in a card
|
|
27
27
|
|
|
28
|
-
- Fields go in the card body, in a
|
|
28
|
+
- Fields go in the card body, in a `<Stack gap="md">`. Keep each
|
|
29
29
|
input's default `horizontal` layout (label and control on one shaded row).
|
|
30
30
|
- Every field needs a `name`. It is required, and it is the key passed to
|
|
31
31
|
`onValidChange`.
|
|
@@ -39,9 +39,11 @@ export const SettingsPage = () => (
|
|
|
39
39
|
<Button type="primary" radius="card" submit form="change-password">Save</Button>
|
|
40
40
|
}
|
|
41
41
|
>
|
|
42
|
-
<form id="change-password"
|
|
43
|
-
<
|
|
44
|
-
|
|
42
|
+
<form id="change-password" action={save}>
|
|
43
|
+
<Stack gap="md">
|
|
44
|
+
<TextInput name="current" label="Current" password value={current} onChange={setCurrent} />
|
|
45
|
+
<TextInput name="next" label="New" password value={next} onChange={setNext} />
|
|
46
|
+
</Stack>
|
|
45
47
|
</form>
|
|
46
48
|
</Card>
|
|
47
49
|
```
|
|
@@ -109,8 +111,25 @@ Never use `!important`, and never target the library's internal class names.
|
|
|
109
111
|
|
|
110
112
|
## Layout and text
|
|
111
113
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
114
|
+
Use `Stack` and `Inline` for layout and `Text` and `Heading` for text, not
|
|
115
|
+
style files. Recipes:
|
|
116
|
+
|
|
117
|
+
- Body text: a bare `<Text>`; it takes the surrounding look.
|
|
118
|
+
- Meta line: `<Text size="sm" tone="muted">`.
|
|
119
|
+
- Caption: `<Text size="xs" tone="faint">`.
|
|
120
|
+
- Section title: `<Heading level={2}>`.
|
|
121
|
+
- Spread row: `<Inline justify="between">`.
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
<Stack gap="md">
|
|
125
|
+
<Heading level={2}>Devices</Heading>
|
|
126
|
+
<Inline justify="between">
|
|
127
|
+
<Text>Kindle</Text>
|
|
128
|
+
<Text size="sm" tone="muted">Synced today</Text>
|
|
129
|
+
</Inline>
|
|
130
|
+
<Text size="xs" tone="faint">Up to five devices.</Text>
|
|
131
|
+
</Stack>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
See [stack](component/stack.md), [inline](component/inline.md),
|
|
135
|
+
[text](component/text.md), and [heading](component/heading.md).
|
package/docs/theme.md
CHANGED
|
@@ -37,17 +37,16 @@ import { applyTransparency } from '@korzun/design';
|
|
|
37
37
|
|
|
38
38
|
export const useStyle = createUseStyles((theme: Theme) => ({
|
|
39
39
|
root: {
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
gap: theme.space.md,
|
|
43
|
-
color: theme.color.text.primary,
|
|
40
|
+
padding: theme.space.md,
|
|
41
|
+
backgroundColor: theme.color.bg.card,
|
|
44
42
|
},
|
|
45
|
-
hint: { fontSize: theme.fontSize.sm, color: theme.color.text.muted },
|
|
46
43
|
highlight: { backgroundColor: applyTransparency(theme.color.brand.default, 0.12) },
|
|
47
|
-
[theme.breakpoint.mobile]: { root: {
|
|
44
|
+
[theme.breakpoint.mobile]: { root: { padding: theme.space.sm } },
|
|
48
45
|
}));
|
|
49
46
|
```
|
|
50
47
|
|
|
48
|
+
- Style files are for padding, borders, backgrounds, and one-offs (borders come from the border tokens). Lay out with
|
|
49
|
+
`Stack`/`Inline` and set text with `Text`/`Heading`.
|
|
51
50
|
- `applyTransparency(color, alpha)` turns a hex or rgb token into an `rgba()`
|
|
52
51
|
string. Use it for tints instead of writing an rgba literal.
|
|
53
52
|
- Media queries: use the `theme.breakpoint.mobile` / `.normal` strings as keys.
|
|
@@ -61,14 +60,16 @@ export const useStyle = createUseStyles((theme: Theme) => ({
|
|
|
61
60
|
| `color.border` | `default`, `strong`, `light`, `focus`, `hover`, `danger`, `glass`, `glassActive`, `faint`, `loading`, `success`, `section` | Cards and dividers use `strong`; inputs use `default` |
|
|
62
61
|
| `color.brand` | `default`, `hover`, `active`, `light`, `outline`, `loading*`, `linkHover` | The primary action colour |
|
|
63
62
|
| `color.danger` | `default`, `hover`, `active`, `light`, `outline`, `loading*` | Destructive actions and errors |
|
|
64
|
-
| `color.success` | (a string) |
|
|
65
|
-
| `color.
|
|
63
|
+
| `color.success` | (a string) | Solid green |
|
|
64
|
+
| `color.warning` | (a string) | Solid amber |
|
|
65
|
+
| `color.info` | (a string) | Solid blue, the mode's `brand.default` |
|
|
66
|
+
| `color.chip.<tone>` | `{ text, bg, border }` for 13 tones. Status tones: `success`, `warning`, `danger`, `info`, `neutral`. Label tones: `status`, `author`, `series`, `subject`, `book`, `entryType`, `user`, `rating` | Used by `Tag` |
|
|
66
67
|
| `color.overlay` | `backdrop` | Modal backdrop |
|
|
67
68
|
| `color.gray` / `blue` / `red` | primitive scales | Don't use these in app code; use the semantic tokens above |
|
|
68
69
|
| `space` | `xxxs` 0.1rem, `xxs` 0.125, `xs` 0.25, `sm` 0.375, `md` 0.5, `lg` 0.625, `xl` 0.75, `xxl` 1, `xxxl` 1.25, `xxxxl` 1.5, `xxxxxl` 2rem | `md` is the default gap between stacked fields |
|
|
69
70
|
| `radius` | `sm` 4px, `md` 8px, `lg` 16px, `circle`, `pill` | Chosen by nesting depth; see [corners](corners.md) |
|
|
70
71
|
| `fontSize` | `xxs` 0.6rem, `xs` 0.7, `sm` 0.75, `md` 0.875, `lg` 1, `xl` 1.25, `xxl` 1.75rem | Control text is `'0.80rem'`, the one sanctioned literal (already applied by `recipe.input` and Button) |
|
|
71
|
-
| `fontWeight` | `medium` 500, `semibold` 600, `bold` 700, `extrabold` 800 | |
|
|
72
|
+
| `fontWeight` | `regular` 400, `medium` 500, `semibold` 600, `bold` 700, `extrabold` 800 | |
|
|
72
73
|
| `lineHeight` | `tight` 1, `body` 1.3 | |
|
|
73
74
|
| `fontFamily` | `body`, `mono` | |
|
|
74
75
|
| `shadow` | `card`, `cardStack`, `hoverLift`, `dangerStack`, `brandStack`, `glass`, `glassActive` | Floating layers use `hoverLift` |
|