@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.
Files changed (61) hide show
  1. package/AGENTS.md +78 -0
  2. package/README.md +11 -1
  3. package/dist/component/index.d.ts +1 -1
  4. package/dist/component/index.d.ts.map +1 -1
  5. package/dist/component/index.js.map +1 -1
  6. package/dist/component/tag/index.d.ts +5 -2
  7. package/dist/component/tag/index.d.ts.map +1 -1
  8. package/dist/component/tag/index.js +2 -2
  9. package/dist/component/tag/index.js.map +1 -1
  10. package/dist/component/tag/style.d.ts +2 -1
  11. package/dist/component/tag/style.d.ts.map +1 -1
  12. package/dist/component/tag/style.js +21 -7
  13. package/dist/component/tag/style.js.map +1 -1
  14. package/dist/theme/theme.d.ts +5 -0
  15. package/dist/theme/theme.d.ts.map +1 -1
  16. package/dist/theme/theme.js +13 -1
  17. package/dist/theme/theme.js.map +1 -1
  18. package/docs/component/card-divider.md +67 -0
  19. package/docs/component/card-row.md +58 -0
  20. package/docs/component/card.md +82 -0
  21. package/docs/component/collapsible-section.md +57 -0
  22. package/docs/component/empty-state.md +49 -0
  23. package/docs/component/meta-line.md +60 -0
  24. package/docs/component/metadata-list.md +60 -0
  25. package/docs/component/nav-desktop.md +62 -0
  26. package/docs/component/nav-mobile.md +82 -0
  27. package/docs/component/page.md +81 -0
  28. package/docs/component/progress-indicator.md +53 -0
  29. package/docs/component/tag.md +69 -0
  30. package/docs/component/theme-setting.md +58 -0
  31. package/docs/component/top-fade.md +60 -0
  32. package/docs/control/back-button.md +55 -0
  33. package/docs/control/button.md +78 -0
  34. package/docs/control/chips-input.md +77 -0
  35. package/docs/control/confirm-modal.md +68 -0
  36. package/docs/control/date-time-input.md +56 -0
  37. package/docs/control/field-list.md +66 -0
  38. package/docs/control/number-input.md +62 -0
  39. package/docs/control/page-actions-bar.md +64 -0
  40. package/docs/control/page-actions-menu.md +65 -0
  41. package/docs/control/page-footer-actions.md +69 -0
  42. package/docs/control/popover.md +74 -0
  43. package/docs/control/segmented-control.md +73 -0
  44. package/docs/control/select.md +86 -0
  45. package/docs/control/switch.md +73 -0
  46. package/docs/control/text-area.md +52 -0
  47. package/docs/control/text-input.md +73 -0
  48. package/docs/control/use-modal-dialog.md +76 -0
  49. package/docs/corners.md +68 -0
  50. package/docs/hooks.md +104 -0
  51. package/docs/icon.md +102 -0
  52. package/docs/patterns.md +116 -0
  53. package/docs/philosophy.md +91 -0
  54. package/docs/theme.md +96 -0
  55. package/docs/toast.md +85 -0
  56. package/docs/tokens.md +95 -0
  57. package/package.json +7 -1
  58. package/src/component/index.ts +1 -1
  59. package/src/component/tag/index.tsx +7 -2
  60. package/src/component/tag/style.ts +27 -7
  61. package/src/theme/theme.ts +16 -1
package/docs/toast.md ADDED
@@ -0,0 +1,85 @@
1
+ # Toast
2
+
3
+ `import { ToastProvider, useToast } from '@korzun/design/toast'`
4
+
5
+ Short, transient confirmations and errors ("Password changed", "Failed to reset
6
+ password") that appear in a corner, stay four seconds, and slide away. Mount
7
+ `ToastProvider` once; call the function `useToast()` returns from anywhere
8
+ below it.
9
+
10
+ Use something else for: an error that must stay until the user acts (inline
11
+ text near the field, or `EmptyState danger` for a failed load), a question
12
+ needing an answer (`ConfirmModal`).
13
+
14
+ ## `ToastProvider`
15
+
16
+ | Prop | Type | Default | Notes |
17
+ |---|---|---|---|
18
+ | `children` | `ReactNode` | required | The app. |
19
+ | `maxToasts` | `number` | `3` | When a new toast would exceed this, the oldest starts its exit animation. |
20
+
21
+ Placement:
22
+
23
+ - **Inside `ThemeProvider`** (toasts are styled from the theme) and above every
24
+ component that calls `useToast`. Bookplate nests it innermost among its app
25
+ providers, around the router.
26
+ - It renders its container itself; you don't place anything in the layout.
27
+ Desktop: bottom-right, `space.xxxxl` from the edges. Mobile: full width just
28
+ above the floating `NavMobile` (and below it in z-order, so toasts slide up
29
+ from behind the bar).
30
+ - The container is a `popover="manual"` element shown while any toast is up,
31
+ so toasts appear **above an open modal `<dialog>`** too.
32
+
33
+ ## `useToast()`
34
+
35
+ ```ts
36
+ useToast(): (message: string, type: 'success' | 'error' | 'info') => void
37
+ ```
38
+
39
+ Returns the **function itself** (not an object): `const showToast = useToast()`.
40
+
41
+ | Argument | Notes |
42
+ |---|---|
43
+ | `message` | Plain string. No elements, no actions, no links. |
44
+ | `type` | `'success'`: green check. `'error'`: red X, announced `aria-live="assertive"`. `'info'`: brand-blue info icon. Success and info are `polite`. Required; there is no default. |
45
+
46
+ ## Surprising behaviour
47
+
48
+ - **Without a `ToastProvider` above it, `showToast` silently does nothing**
49
+ (the default context is a no-op). No error is thrown.
50
+ - Duration is fixed at 4000ms; there is no per-toast duration, no close
51
+ button, and no tap-to-dismiss.
52
+ - Toasts have `radius.md` (a floating layer) per [corners](corners.md).
53
+
54
+ ## Examples
55
+
56
+ ```tsx
57
+ // App root.
58
+ <ThemeProvider identity={username}>
59
+ <ToastProvider>
60
+ <AppRouter />
61
+ </ToastProvider>
62
+ </ThemeProvider>
63
+
64
+ // A component reporting a mutation's outcome.
65
+ const showToast = useToast();
66
+ const save = async () => {
67
+ try {
68
+ const result = await changePassword(input);
69
+ if (!result.ok) {
70
+ showToast(result.message, 'error');
71
+ return;
72
+ }
73
+ showToast('Password changed', 'success');
74
+ } catch (err) {
75
+ showToast(err instanceof Error ? err.message : 'Password change failed', 'error');
76
+ }
77
+ };
78
+ ```
79
+
80
+ ## Do / don't
81
+
82
+ - Do mount exactly one `ToastProvider`, inside `ThemeProvider`.
83
+ - Do keep messages to one short sentence; nothing truncates a long one.
84
+ - Don't destructure: `const { showToast } = useToast()` is wrong.
85
+ - Don't use a toast for the only copy of an error the user must fix.
package/docs/tokens.md ADDED
@@ -0,0 +1,95 @@
1
+ # Tokens
2
+
3
+ Every token lives in `src/theme/theme.ts`. The `Theme` interface declares the groups; `lightTheme` and `darkTheme` are both built by `buildTheme(mode)` and share every key, differing only in values. Consumers read tokens with `useTheme()` or inside `createUseStyles((theme: Theme) => ...)`. The groups below follow the order of the `Theme` type; the key lists are taken from it.
4
+
5
+ The top-level `colorScheme` key holds the mode, `'light'` or `'dark'` (type `ThemeMode`), and is also the only non-group key of the type.
6
+
7
+ ## color
8
+
9
+ Surfaces, text, borders and state colours, mode-aware. Keys are grouped as follows.
10
+
11
+ - `color.gray`: primitive palette, steps `50 100 150 200 300 400 500 600 700 900`. Identical in both modes.
12
+ - `color.blue`: primitive palette, steps `50 100 200 300 400 500 600 700 800`. Identical in both modes.
13
+ - `color.red`: primitive palette, steps `50 100 300 400 500 600 700`. Identical in both modes.
14
+ - `color.text`: `primary secondary muted faint onPrimary onDanger description`
15
+ - `color.bg`: `page card cardHeader track input footer glass glassFallback glassActive selected hover success placeholder`. `track` must read against both `page` and `card`; `hover` is a translucent scrim; `glass*` feed `recipe.glass`.
16
+ - `color.border`: `default strong light focus hover danger glass glassActive faint loading success section`
17
+ - `color.success`: a single value.
18
+ - `color.brand`: `default hover active light outline loading loadingHover loadingActive linkHover`
19
+ - `color.danger`: `default hover active light outline loading loadingHover loadingActive`
20
+ - `color.overlay`: `backdrop`
21
+ - `color.chip`: eight tinted label colourways, each `{ text, bg, border }`: `status author series subject book entryType user rating`. See Slated for curation.
22
+
23
+ ## space
24
+
25
+ The spacing scale, in `rem`: `xxxs xxs xs sm md lg xl xxl xxxl xxxxl xxxxxl` (`0.1rem` up to `2rem`).
26
+
27
+ ## radius
28
+
29
+ Corner radii: `sm md lg circle pill` (`4px`, `8px`, `16px`, `50%`, `999px`).
30
+
31
+ ## size
32
+
33
+ Fixed component sizes that are not part of the spacing scale. One key: `metadataValue`. See Slated for curation.
34
+
35
+ ## layout
36
+
37
+ Intrinsic sizes of chrome that other elements must lay out around. They are measured, not derived, so they are tuned on a device and kept in one place. Keys: `navHeightMobile` (the floating mobile nav, `96px`), `modalWidth` (the one width for every dialog, `500px`), `controlHeight` (the shared single-line control height, `2.0625rem`), and `floatingControlTopBase`, a position rather than a size: the `top` at which the mobile back button and actions menu pin, `max(space.xxxl, env(safe-area-inset-top) + space.xxxxl)`.
38
+
39
+ ## fontSize
40
+
41
+ The type scale: `xxs xs sm md lg xl xxl` (`0.6rem` up to `1.75rem`).
42
+
43
+ ## fontFamily
44
+
45
+ Two stacks: `body` (`system-ui, sans-serif`) and `mono`.
46
+
47
+ ## fontWeight
48
+
49
+ Numeric weights: `medium semibold bold extrabold` (500, 600, 700, 800).
50
+
51
+ ## lineHeight
52
+
53
+ Two values: `tight` (1) and `body` (1.3).
54
+
55
+ ## shadow
56
+
57
+ Mode-aware elevation. `card` is a soft one-pixel shadow (defined, with no consumer outside the theme); `cardStack`, `dangerStack` and `brandStack` are the hard `0px 2px 0px` offset shadows for cards and buttons; `hoverLift` is the elevation of floating surfaces (the toast and the select and chips-input dropdowns); `glass` and `glassActive` belong to `recipe.glass` and `recipe.glassHighlight`. Keys: `card cardStack hoverLift dangerStack brandStack glass glassActive`.
58
+
59
+ ## transition
60
+
61
+ Shorthand durations and easings: `fast medium slide slow spring`.
62
+
63
+ ## zIndex
64
+
65
+ Stacking layers: `behind base stack header sticky toast`, where `stack` is a nested `{ lo, md, hi }` (1, 2, 3). Values run from `-1` (`behind`) to `9999` (`toast`).
66
+
67
+ ## breakpoint
68
+
69
+ Media-query strings, ready to use as JSS keys: `mobile` (`@media (max-width: 640px)`) and `normal` (`@media (min-width: 641px)`).
70
+
71
+ ## recipe
72
+
73
+ JSS-spreadable style fragments (`...theme.recipe.x`), not components.
74
+
75
+ - `recipe.input`: the base text-field look (border, radius, hover and focus colours, 16px font on mobile).
76
+ - `recipe.focusRing`: a transparent 2px outline that controls recolour on focus.
77
+ - `recipe.label`: form label text, with a `$danger` variant.
78
+ - `recipe.spinner`: a 1em rotating indicator using the `theme-rotation` keyframes.
79
+ - `recipe.glass`: frosted, blurred chrome with a solid fallback where backdrop blur is unsupported.
80
+ - `recipe.glassHighlight`: the active or pressed fill that sits on top of glass.
81
+ - `recipe.modal.dialog`: the shared dialog shell (one width, backdrop, mobile margins and safe-area insets).
82
+ - `recipe.modal.header`: dialog title row.
83
+ - `recipe.modal.footer`: dialog action row.
84
+ - `recipe.card.shell`: card container with border, radius and `shadow.cardStack`.
85
+ - `recipe.card.header`: card title bar.
86
+ - `recipe.card.footer`: card action row.
87
+
88
+ ## Slated for curation
89
+
90
+ Both groups below move into the package byte-for-byte in 0.0.1 and are due for a decision before the API settles.
91
+
92
+ - `color.chip.*`: eight colourways (`status author series subject book entryType user rating`) named after Bookplate's metadata chips, not after a general role.
93
+ - `size.metadataValue`: `15rem`, a width named after Bookplate's metadata display.
94
+
95
+ No other token name or comment in `src/theme/theme.ts` is clearly Bookplate-specific. Two comments mention app internals (`floatingControlTopBase` refers to the admin picker and `router/nav-layout-style`), but the tokens themselves are generic.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@korzun/design",
3
- "version": "0.0.2",
3
+ "version": "0.0.4",
4
4
  "type": "module",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {
@@ -12,9 +12,13 @@
12
12
  "url": "https://github.com/Korzun/korzun-design/issues"
13
13
  },
14
14
  "files": [
15
+ "AGENTS.md",
16
+ "docs",
17
+ "!docs/superpowers",
15
18
  "dist",
16
19
  "src",
17
20
  "!src/**/*.test.*",
21
+ "!src/**/*.stories.*",
18
22
  "!src/test-utils.tsx",
19
23
  "!src/setup.ts"
20
24
  ],
@@ -57,6 +61,8 @@
57
61
  },
58
62
  "scripts": {
59
63
  "gallery": "vite --config gallery/vite.config.ts",
64
+ "gallery:build": "vite build --config gallery/vite.config.ts",
65
+ "gallery:build:pages": "vite build --config gallery/vite.config.ts --mode pages",
60
66
  "smoke": "npm run build && bash scripts/smoke-exports.sh",
61
67
  "build": "rm -rf dist && tsc -p tsconfig.build.json",
62
68
  "test": "vitest run && npm run test:scripts",
@@ -10,6 +10,6 @@ export { NavMobile, type NavMobileProps, type NavPill } from './nav-mobile/index
10
10
  export type { NavItem } from './nav-types.js';
11
11
  export { Page } from './page/index.js';
12
12
  export { ProgressIndicator } from './progress-indicator/index.js';
13
- export { Tag } from './tag/index.js';
13
+ export { Tag, type TagTone } from './tag/index.js';
14
14
  export { ThemeSetting } from './theme-setting/index.js';
15
15
  export { TopFade } from './top-fade/index.js';
@@ -1,20 +1,25 @@
1
1
  import cx from 'classnames';
2
2
 
3
- import { useStyle } from './style.js';
3
+ import { type TagTone, useStyle } from './style.js';
4
+
5
+ export type { TagTone };
4
6
 
5
7
  interface TagProps {
6
8
  children: React.ReactNode;
7
9
  onClick?: () => void;
8
10
  /** `sm` renders a compact chip that fits within a normal text line height. */
9
11
  size?: 'sm' | 'md';
12
+ /** Colour, from the theme's `color.chip` tokens. `neutral` is a quiet grey. */
13
+ tone?: TagTone;
10
14
  }
11
15
 
12
- export const Tag = ({ children, onClick, size = 'md' }: TagProps) => {
16
+ export const Tag = ({ children, onClick, size = 'md', tone = 'subject' }: TagProps) => {
13
17
  const style = useStyle();
14
18
  return (
15
19
  <span
16
20
  className={cx(
17
21
  style.root,
22
+ style[`tone-${tone}`],
18
23
  size === 'sm' && style.sm,
19
24
  onClick !== undefined && style.clickable
20
25
  )}
@@ -1,14 +1,37 @@
1
1
  import { createUseStyles, type Theme } from '../../theme/index.js';
2
+ import { applyTransparency } from '../../utils.js';
3
+
4
+ export type TagTone = keyof Theme['color']['chip'];
5
+
6
+ // One static rule per chip token, so a tone is a class swap rather than a
7
+ // dynamic (per-instance) style sheet. Hover deepens the tone's own colour: for
8
+ // `subject` in light mode this reproduces the old hard-coded amber exactly.
9
+ const toneRules = (theme: Theme) =>
10
+ Object.fromEntries(
11
+ (Object.keys(theme.color.chip) as TagTone[]).map((tone) => {
12
+ const chip = theme.color.chip[tone];
13
+ return [
14
+ `tone-${tone}`,
15
+ {
16
+ background: chip.bg,
17
+ color: chip.text,
18
+ borderColor: chip.border,
19
+ '&$clickable:hover': {
20
+ background: applyTransparency(chip.text, 0.15),
21
+ borderColor: applyTransparency(chip.text, 0.4),
22
+ },
23
+ },
24
+ ];
25
+ })
26
+ ) as Record<`tone-${TagTone}`, object>;
2
27
 
3
28
  export const useStyle = createUseStyles((theme: Theme) => ({
4
29
  root: {
5
30
  padding: `${theme.space.xs} ${theme.space.md}`,
6
- background: theme.color.chip.subject.bg,
7
- color: theme.color.chip.subject.text,
8
31
  borderRadius: theme.radius.md,
9
32
  fontSize: theme.fontSize.sm,
10
33
  fontWeight: theme.fontWeight.medium,
11
- border: `1px solid ${theme.color.chip.subject.border}`,
34
+ border: '1px solid transparent',
12
35
  },
13
36
  // Compact variant: minimal vertical padding + tight line height so the chip
14
37
  // fits inside a normal text line, keeping fix rows the same height whether or
@@ -20,9 +43,6 @@ export const useStyle = createUseStyles((theme: Theme) => ({
20
43
  },
21
44
  clickable: {
22
45
  cursor: 'pointer',
23
- '&:hover': {
24
- background: 'rgba(138,94,0,0.15)',
25
- borderColor: 'rgba(138,94,0,0.40)',
26
- },
27
46
  },
47
+ ...toneRules(theme),
28
48
  }));
@@ -126,6 +126,9 @@ export interface Theme {
126
126
  entryType: { text: string; bg: string; border: string };
127
127
  user: { text: string; bg: string; border: string };
128
128
  rating: { text: string; bg: string; border: string };
129
+ // Quiet grey for states that carry no category (e.g. "no change"), built
130
+ // from the mode's muted text colour.
131
+ neutral: { text: string; bg: string; border: string };
129
132
  };
130
133
  };
131
134
  space: {
@@ -297,9 +300,15 @@ function buildTheme(mode: ThemeMode): Theme {
297
300
  },
298
301
  user: { text: '#a23a95', bg: 'rgba(162,58,149,0.08)', border: 'rgba(162,58,149,0.22)' },
299
302
  rating: { text: '#b5451b', bg: 'rgba(181,69,27,0.08)', border: 'rgba(181,69,27,0.22)' },
303
+ neutral: {
304
+ text: gray[600],
305
+ bg: applyTransparency(gray[600], 0.08),
306
+ border: applyTransparency(gray[600], 0.22),
307
+ },
300
308
  },
301
309
  };
302
310
 
311
+ const darkMuted = '#9CA1AB';
303
312
  const darkColor: Theme['color'] = {
304
313
  gray,
305
314
  blue,
@@ -307,7 +316,7 @@ function buildTheme(mode: ThemeMode): Theme {
307
316
  text: {
308
317
  primary: '#F5F5F7',
309
318
  secondary: '#C8CBD2',
310
- muted: '#9CA1AB',
319
+ muted: darkMuted,
311
320
  faint: '#6E7480',
312
321
  onPrimary: '#FFFFFF',
313
322
  onDanger: '#FFFFFF',
@@ -383,6 +392,12 @@ function buildTheme(mode: ThemeMode): Theme {
383
392
  },
384
393
  user: { text: '#E7A6DA', bg: 'rgba(162,58,149,0.16)', border: 'rgba(162,58,149,0.30)' },
385
394
  rating: { text: '#F2A07B', bg: 'rgba(181,69,27,0.18)', border: 'rgba(181,69,27,0.32)' },
395
+ // Dark chips run stronger alphas (0.16 / 0.30) than light (0.08 / 0.22).
396
+ neutral: {
397
+ text: darkMuted,
398
+ bg: applyTransparency(darkMuted, 0.16),
399
+ border: applyTransparency(darkMuted, 0.3),
400
+ },
386
401
  },
387
402
  };
388
403