@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.
Files changed (89) hide show
  1. package/AGENTS.md +11 -4
  2. package/dist/component/heading/index.d.ts +303 -0
  3. package/dist/component/heading/index.d.ts.map +1 -0
  4. package/dist/component/heading/index.js +21 -0
  5. package/dist/component/heading/index.js.map +1 -0
  6. package/dist/component/heading/style.d.ts +5 -0
  7. package/dist/component/heading/style.d.ts.map +1 -0
  8. package/dist/component/heading/style.js +5 -0
  9. package/dist/component/heading/style.js.map +1 -0
  10. package/dist/component/index.d.ts +4 -0
  11. package/dist/component/index.d.ts.map +1 -1
  12. package/dist/component/index.js +4 -0
  13. package/dist/component/index.js.map +1 -1
  14. package/dist/component/inline/index.d.ts +303 -0
  15. package/dist/component/inline/index.d.ts.map +1 -0
  16. package/dist/component/inline/index.js +13 -0
  17. package/dist/component/inline/index.js.map +1 -0
  18. package/dist/component/inline/style.d.ts +5 -0
  19. package/dist/component/inline/style.d.ts.map +1 -0
  20. package/dist/component/inline/style.js +18 -0
  21. package/dist/component/inline/style.js.map +1 -0
  22. package/dist/component/stack/gap.d.ts +4 -0
  23. package/dist/component/stack/gap.d.ts.map +1 -0
  24. package/dist/component/stack/gap.js +10 -0
  25. package/dist/component/stack/gap.js.map +1 -0
  26. package/dist/component/stack/index.d.ts +299 -0
  27. package/dist/component/stack/index.d.ts.map +1 -0
  28. package/dist/component/stack/index.js +13 -0
  29. package/dist/component/stack/index.js.map +1 -0
  30. package/dist/component/stack/style.d.ts +5 -0
  31. package/dist/component/stack/style.d.ts.map +1 -0
  32. package/dist/component/stack/style.js +12 -0
  33. package/dist/component/stack/style.js.map +1 -0
  34. package/dist/component/tag/index.d.ts +1 -1
  35. package/dist/component/tag/index.d.ts.map +1 -1
  36. package/dist/component/tag/index.js.map +1 -1
  37. package/dist/component/tag/style.d.ts +1 -1
  38. package/dist/component/tag/style.d.ts.map +1 -1
  39. package/dist/component/text/index.d.ts +307 -0
  40. package/dist/component/text/index.d.ts.map +1 -0
  41. package/dist/component/text/index.js +15 -0
  42. package/dist/component/text/index.js.map +1 -0
  43. package/dist/component/text/style.d.ts +11 -0
  44. package/dist/component/text/style.d.ts.map +1 -0
  45. package/dist/component/text/style.js +48 -0
  46. package/dist/component/text/style.js.map +1 -0
  47. package/dist/control/index.d.ts +1 -1
  48. package/dist/control/index.d.ts.map +1 -1
  49. package/dist/control/index.js +1 -1
  50. package/dist/control/index.js.map +1 -1
  51. package/dist/control/popover/index.d.ts +24 -8
  52. package/dist/control/popover/index.d.ts.map +1 -1
  53. package/dist/control/popover/index.js +60 -15
  54. package/dist/control/popover/index.js.map +1 -1
  55. package/dist/control/popover/position.d.ts +47 -0
  56. package/dist/control/popover/position.d.ts.map +1 -0
  57. package/dist/control/popover/position.js +29 -0
  58. package/dist/control/popover/position.js.map +1 -0
  59. package/dist/theme/theme.d.ts +25 -0
  60. package/dist/theme/theme.d.ts.map +1 -1
  61. package/dist/theme/theme.js +43 -1
  62. package/dist/theme/theme.js.map +1 -1
  63. package/docs/component/heading.md +85 -0
  64. package/docs/component/inline.md +64 -0
  65. package/docs/component/meta-line.md +13 -17
  66. package/docs/component/metadata-list.md +1 -1
  67. package/docs/component/stack.md +68 -0
  68. package/docs/component/tag.md +26 -6
  69. package/docs/component/text.md +94 -0
  70. package/docs/control/popover.md +41 -10
  71. package/docs/patterns.md +28 -9
  72. package/docs/theme.md +10 -9
  73. package/docs/tokens.md +4 -4
  74. package/package.json +1 -1
  75. package/src/component/heading/index.tsx +64 -0
  76. package/src/component/heading/style.ts +5 -0
  77. package/src/component/index.ts +4 -0
  78. package/src/component/inline/index.tsx +57 -0
  79. package/src/component/inline/style.ts +18 -0
  80. package/src/component/stack/gap.ts +16 -0
  81. package/src/component/stack/index.tsx +49 -0
  82. package/src/component/stack/style.ts +12 -0
  83. package/src/component/tag/index.tsx +1 -1
  84. package/src/component/text/index.tsx +61 -0
  85. package/src/component/text/style.ts +67 -0
  86. package/src/control/index.ts +6 -1
  87. package/src/control/popover/index.tsx +77 -19
  88. package/src/control/popover/position.ts +66 -0
  89. 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 (your own styled element).
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`); style the line via `className`.
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
- <div className={styles.title}>{book.title}</div>
36
- <MetaLine
37
- items={[
38
- book.author,
39
- book.series && `${book.series.name} #${book.seriesIndex}`,
40
- book.progress !== undefined && `${Math.round(book.progress * 100)}%`,
41
- ]}
42
- className={styles.meta}
43
- />
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 through `className`.
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="status">Active</Tag> },
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`.
@@ -23,12 +23,26 @@ No `className`, no `ariaLabel`.
23
23
 
24
24
  ## Choosing a tone
25
25
 
26
- `TagTone` is `keyof Theme['color']['chip']`, so the tones are **domain names**,
27
- not colour names. Pick by what the tag *is*:
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` | A state (Pending, Active, Read only). |
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
- | `neutral` | A state with no category ("no change"): quiet grey. |
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 status, in neutral or status tone.
56
- <Tag size="sm" tone="status">{write ? 'Read & write' : 'Read only'}</Tag>
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`.
@@ -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` directly beneath an anchor element, so a dropdown can escape
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 sit under. Left edges align. |
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
- | `gap` | `number` | `4` | Pixels between the anchor's bottom and the popover. |
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
- - **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.
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
- - Don't expect it to close on Escape or on selection; that is your code.
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 column with `gap: theme.space.md`. Keep each
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" className={styles.fields} action={save}>
43
- <TextInput name="current" label="Current" password value={current} onChange={setCurrent} />
44
- <TextInput name="next" label="New" password value={next} onChange={setNext} />
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
- There are no `Stack`, `Text`, or `Heading` components yet. Write a small
113
- `createUseStyles` rule using tokens: `display: 'flex'`, `gap: theme.space.*`,
114
- `fontSize: theme.fontSize.*`, `fontWeight: theme.fontWeight.*`,
115
- `color: theme.color.text.*`. Don't use inline `style={{…}}` objects with
116
- literal values.
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
- display: 'flex',
41
- flexDirection: 'column',
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: { gap: theme.space.sm } },
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) | There are no warning or info colours yet |
65
- | `color.chip.<tone>` | `{ text, bg, border }` for `status`, `author`, `series`, `subject`, `book`, `entryType`, `user`, `rating`, `neutral` | Used by `Tag` |
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` |