@korzun/design 0.0.5 → 0.1.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 (48) hide show
  1. package/AGENTS.md +5 -1
  2. package/dist/component/card/style.d.ts.map +1 -1
  3. package/dist/component/card/style.js +3 -1
  4. package/dist/component/card/style.js.map +1 -1
  5. package/dist/component/card-row/style.js +1 -1
  6. package/dist/component/card-row/style.js.map +1 -1
  7. package/dist/component/tag/index.d.ts +1 -1
  8. package/dist/component/tag/index.d.ts.map +1 -1
  9. package/dist/component/tag/index.js.map +1 -1
  10. package/dist/component/tag/style.d.ts +1 -1
  11. package/dist/component/tag/style.d.ts.map +1 -1
  12. package/dist/control/index.d.ts +1 -1
  13. package/dist/control/index.d.ts.map +1 -1
  14. package/dist/control/index.js +1 -1
  15. package/dist/control/index.js.map +1 -1
  16. package/dist/control/popover/index.d.ts +24 -8
  17. package/dist/control/popover/index.d.ts.map +1 -1
  18. package/dist/control/popover/index.js +60 -15
  19. package/dist/control/popover/index.js.map +1 -1
  20. package/dist/control/popover/position.d.ts +47 -0
  21. package/dist/control/popover/position.d.ts.map +1 -0
  22. package/dist/control/popover/position.js +29 -0
  23. package/dist/control/popover/position.js.map +1 -0
  24. package/dist/control/switch/style.d.ts.map +1 -1
  25. package/dist/control/switch/style.js +1 -3
  26. package/dist/control/switch/style.js.map +1 -1
  27. package/dist/theme/theme.d.ts +26 -0
  28. package/dist/theme/theme.d.ts.map +1 -1
  29. package/dist/theme/theme.js +41 -0
  30. package/dist/theme/theme.js.map +1 -1
  31. package/docs/component/card-row.md +11 -12
  32. package/docs/component/card.md +3 -3
  33. package/docs/component/metadata-list.md +1 -1
  34. package/docs/component/tag.md +26 -6
  35. package/docs/control/popover.md +41 -10
  36. package/docs/corners.md +4 -4
  37. package/docs/philosophy.md +1 -1
  38. package/docs/theme.md +5 -2
  39. package/docs/tokens.md +4 -3
  40. package/package.json +1 -1
  41. package/src/component/card/style.ts +3 -1
  42. package/src/component/card-row/style.ts +1 -1
  43. package/src/component/tag/index.tsx +1 -1
  44. package/src/control/index.ts +6 -1
  45. package/src/control/popover/index.tsx +77 -19
  46. package/src/control/popover/position.ts +66 -0
  47. package/src/control/switch/style.ts +1 -3
  48. package/src/theme/theme.ts +52 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@korzun/design",
3
- "version": "0.0.5",
3
+ "version": "0.1.0",
4
4
  "type": "module",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {
@@ -3,7 +3,9 @@ import { createUseStyles, type Theme } from '../../theme/index.js';
3
3
  export const useStyle = createUseStyles((theme: Theme) => ({
4
4
  root: {
5
5
  ...theme.recipe.card.shell,
6
- '&$small': { borderRadius: '9px' },
6
+ // A small card insets its content by 1px, so it is md + 1px: concentric with the
7
+ // md-cornered children (covers, rows) that sit flush inside it.
8
+ '&$small': { borderRadius: `calc(${theme.radius.md} + 1px)` },
7
9
  },
8
10
  header: {
9
11
  ...theme.recipe.card.header,
@@ -5,7 +5,7 @@ export const useStyle = createUseStyles((theme: Theme) => ({
5
5
  ...theme.recipe.card.shell,
6
6
  backgroundColor: theme.color.bg.card,
7
7
  padding: '6px', // row-specific compact padding
8
- borderRadius: '12px', // row-specific 10px radius (not on theme scale)
8
+ // Corners come from recipe.card.shell (radius.lg): a row sits on the page background.
9
9
  },
10
10
  clickable: {
11
11
  cursor: 'pointer',
@@ -11,7 +11,7 @@ export interface TagProps {
11
11
  onClick?: () => void;
12
12
  /** `sm` renders a compact chip that fits within a normal text line height. Default `'md'`. */
13
13
  size?: 'sm' | 'md';
14
- /** Colour, from the theme's `color.chip` tokens (default `'subject'`). `neutral` is a quiet grey. */
14
+ /** Colour, from the theme's `color.chip` tokens. Status tones (`success`, `warning`, `danger`, `info`, `neutral`) report state; label tones (the rest) name a kind of thing. `status` is a legacy label tone despite its name; for a state use `success`/`warning`/`danger`/`info`, or `neutral` when it carries no meaning. Default `subject`. */
15
15
  tone?: TagTone;
16
16
  }
17
17
 
@@ -27,7 +27,12 @@ export {
27
27
  type FooterAction,
28
28
  type PageFooterActionsProps,
29
29
  } from './page-footer-actions/index.js';
30
- export { Popover, type PopoverProps } from './popover/index.js';
30
+ export {
31
+ Popover,
32
+ type PopoverAlign,
33
+ type PopoverProps,
34
+ type PopoverSide,
35
+ } from './popover/index.js';
31
36
  export { Select, type SelectOption, type SelectProps } from './select/index.js';
32
37
  export {
33
38
  SegmentedControl,
@@ -10,12 +10,18 @@ import {
10
10
  } from 'react';
11
11
  import { createPortal } from 'react-dom';
12
12
 
13
+ import {
14
+ computePosition,
15
+ type Placement,
16
+ type PopoverAlign,
17
+ type PopoverSide,
18
+ } from './position.js';
13
19
  import { useStyle } from './style.js';
14
20
 
15
- type Position = { top: number; left: number; width: number };
21
+ export type { PopoverAlign, PopoverSide } from './position.js';
16
22
 
17
23
  export type PopoverProps = {
18
- /** Element the popover aligns to (positioned directly beneath it). */
24
+ /** Element the popover aligns to (placed below or above it, per `side`). */
19
25
  anchorRef: RefObject<HTMLElement | null>;
20
26
  /** Whether the popover is rendered. */
21
27
  open: boolean;
@@ -23,24 +29,38 @@ export type PopoverProps = {
23
29
  children: ReactNode;
24
30
  /** Applied to the fixed wrapper; win specificity with `'&&'`, never `!important`. */
25
31
  className?: string;
26
- /** Vertical gap between the anchor and the popover, in pixels. */
32
+ /** Vertical gap between the anchor and the popover, in pixels; also the viewport edge margin when `matchWidth` is false. */
27
33
  gap?: number;
28
34
  /** Match the popover width to the anchor width (default true). */
29
35
  matchWidth?: boolean;
36
+ /** Preferred side; flips to the other side when this one has no room. */
37
+ side?: PopoverSide;
38
+ /** Horizontal alignment to the anchor's left edge, centre, or right edge. */
39
+ align?: PopoverAlign;
30
40
  /**
31
- * Called on a pointer-down outside both the anchor and the popover content.
32
- * Omit to opt out of outside-close handling.
41
+ * Called on a pointer-down outside both the anchor and the popover content,
42
+ * and on an Escape keydown no control has already handled. Omit to opt out.
33
43
  */
34
44
  onClose?: () => void;
35
45
  };
36
46
 
37
47
  /**
38
48
  * Renders `children` in a portal on `document.body`, positioned with `fixed`
39
- * coordinates directly under `anchorRef`. This lets dropdowns escape ancestors
40
- * that clip overflow (e.g. cards with rounded corners) without those ancestors
49
+ * coordinates against `anchorRef`. This lets dropdowns escape ancestors that
50
+ * clip overflow (e.g. cards with rounded corners) without those ancestors
41
51
  * having to opt out of clipping.
42
52
  *
43
- * No Escape handling or focus management, and it never flips above the anchor.
53
+ * Opens on `side` (default below) and flips when that side has no room; aligns
54
+ * per `align` and clamps horizontally to the viewport (only without
55
+ * `matchWidth`). The wrapper carries `data-side` with the side actually used.
56
+ * On the top side it is anchored by CSS `bottom`, so it stays attached as its
57
+ * content changes height. The first render is transparent (`opacity: 0`, still
58
+ * focusable) until measured, then it re-measures on scroll (capture phase),
59
+ * window resize, and content resize (`ResizeObserver`, where available).
60
+ *
61
+ * With `onClose`, Escape closes it unless the keydown was already
62
+ * `defaultPrevented`; it calls `preventDefault` so an enclosing `<dialog>`
63
+ * does not also cancel. No focus management.
44
64
  */
45
65
  export const Popover = ({
46
66
  anchorRef,
@@ -49,18 +69,34 @@ export const Popover = ({
49
69
  className,
50
70
  gap = 4,
51
71
  matchWidth = true,
72
+ side = 'bottom',
73
+ align = 'start',
52
74
  onClose,
53
75
  }: PopoverProps) => {
54
76
  const style = useStyle();
55
77
  const contentRef = useRef<HTMLDivElement>(null);
56
- const [position, setPosition] = useState<Position | null>(null);
78
+ const [placement, setPlacement] = useState<Placement | null>(null);
57
79
 
58
80
  const updatePosition = useCallback(() => {
59
81
  const anchor = anchorRef.current;
60
- if (!anchor) return;
82
+ const content = contentRef.current;
83
+ if (!anchor || !content) return;
61
84
  const rect = anchor.getBoundingClientRect();
62
- setPosition({ top: rect.bottom + gap, left: rect.left, width: rect.width });
63
- }, [anchorRef, gap]);
85
+ // Measure at the width it will render with, so wrapped height is right.
86
+ if (matchWidth) content.style.width = `${rect.width}px`;
87
+ const size = content.getBoundingClientRect();
88
+ setPlacement(
89
+ computePosition({
90
+ anchor: rect,
91
+ content: { width: size.width, height: size.height },
92
+ viewport: { width: window.innerWidth, height: window.innerHeight },
93
+ side,
94
+ align,
95
+ gap,
96
+ matchWidth,
97
+ })
98
+ );
99
+ }, [anchorRef, gap, matchWidth, side, align]);
64
100
 
65
101
  useLayoutEffect(() => {
66
102
  if (!open) return;
@@ -69,9 +105,13 @@ export const Popover = ({
69
105
  // Capture-phase scroll so nested scroll containers reposition too.
70
106
  window.addEventListener('scroll', handle, true);
71
107
  window.addEventListener('resize', handle);
108
+ const observer = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(handle) : undefined;
109
+ if (observer && contentRef.current) observer.observe(contentRef.current);
72
110
  return () => {
73
111
  window.removeEventListener('scroll', handle, true);
74
112
  window.removeEventListener('resize', handle);
113
+ observer?.disconnect();
114
+ setPlacement(null);
75
115
  };
76
116
  }, [open, updatePosition]);
77
117
 
@@ -83,21 +123,39 @@ export const Popover = ({
83
123
  if (contentRef.current?.contains(target)) return;
84
124
  onClose();
85
125
  };
126
+ const handleKeyDown = (event: KeyboardEvent) => {
127
+ if (event.key !== 'Escape' || event.defaultPrevented) return;
128
+ // preventDefault on keydown is what stops a native <dialog> from cancelling.
129
+ event.preventDefault();
130
+ onClose();
131
+ };
86
132
  document.addEventListener('mousedown', handleMouseDown);
87
- return () => document.removeEventListener('mousedown', handleMouseDown);
133
+ document.addEventListener('keydown', handleKeyDown);
134
+ return () => {
135
+ document.removeEventListener('mousedown', handleMouseDown);
136
+ document.removeEventListener('keydown', handleKeyDown);
137
+ };
88
138
  }, [open, onClose, anchorRef]);
89
139
 
90
- if (!open || !position) return null;
140
+ if (!open) return null;
91
141
 
92
142
  return createPortal(
93
143
  <div
94
144
  ref={contentRef}
95
145
  className={cx(style.popover, className)}
96
- style={{
97
- top: position.top,
98
- left: position.left,
99
- width: matchWidth ? position.width : undefined,
100
- }}
146
+ data-side={placement?.side}
147
+ style={
148
+ placement
149
+ ? {
150
+ top: placement.top,
151
+ bottom: placement.bottom,
152
+ left: placement.left,
153
+ width: placement.width,
154
+ }
155
+ : // Never painted: the layout effect measures and re-renders first.
156
+ // Opacity, not visibility, so an autoFocus child can take focus.
157
+ { top: 0, left: 0, opacity: 0 }
158
+ }
101
159
  >
102
160
  {children}
103
161
  </div>,
@@ -0,0 +1,66 @@
1
+ /** Which side of the anchor the popover prefers. */
2
+ export type PopoverSide = 'bottom' | 'top';
3
+ /** Horizontal alignment of the popover against the anchor. */
4
+ export type PopoverAlign = 'start' | 'center' | 'end';
5
+ /** Viewport-relative rectangle, as from getBoundingClientRect. */
6
+ export type Rect = { top: number; bottom: number; left: number; right: number; width: number };
7
+ /**
8
+ * Resolved popover position; `side` is the side actually used after flipping.
9
+ * Exactly one of `top` / `bottom` is set: the bottom side is anchored by its
10
+ * top edge (CSS `top`), the top side by its bottom edge (CSS `bottom`, measured
11
+ * from the viewport's bottom), so content that grows or shrinks while open
12
+ * stays attached to the anchor.
13
+ */
14
+ export type Placement = {
15
+ top: number | undefined;
16
+ bottom: number | undefined;
17
+ left: number;
18
+ width: number | undefined;
19
+ side: PopoverSide;
20
+ };
21
+
22
+ /**
23
+ * Pure placement: picks the side (flipping when the preferred side does not
24
+ * fit and the other has more room), aligns horizontally, and clamps to the
25
+ * viewport horizontally unless `matchWidth` (then it lines up with the anchor).
26
+ */
27
+ export function computePosition({
28
+ anchor,
29
+ content,
30
+ viewport,
31
+ side,
32
+ align,
33
+ gap,
34
+ matchWidth,
35
+ }: {
36
+ anchor: Rect;
37
+ content: { width: number; height: number };
38
+ viewport: { width: number; height: number };
39
+ side: PopoverSide;
40
+ align: PopoverAlign;
41
+ gap: number;
42
+ matchWidth: boolean;
43
+ }): Placement {
44
+ const w = matchWidth ? anchor.width : content.width;
45
+ const h = content.height;
46
+
47
+ const roomBelow = viewport.height - anchor.bottom - gap;
48
+ const roomAbove = anchor.top - gap;
49
+ const room = (s: PopoverSide) => (s === 'bottom' ? roomBelow : roomAbove);
50
+ const other: PopoverSide = side === 'bottom' ? 'top' : 'bottom';
51
+ const used = room(side) >= h || room(other) <= room(side) ? side : other;
52
+ const top = used === 'bottom' ? anchor.bottom + gap : undefined;
53
+ const bottom = used === 'top' ? viewport.height - anchor.top + gap : undefined;
54
+
55
+ let left: number;
56
+ if (align === 'start') left = anchor.left;
57
+ else if (align === 'center') left = anchor.left + anchor.width / 2 - w / 2;
58
+ else left = anchor.right - w;
59
+
60
+ if (!matchWidth) {
61
+ left =
62
+ w > viewport.width - 2 * gap ? gap : Math.max(gap, Math.min(left, viewport.width - w - gap));
63
+ }
64
+
65
+ return { top, bottom, left, width: matchWidth ? anchor.width : undefined, side: used };
66
+ }
@@ -142,9 +142,7 @@ export const useStyle = createUseStyles((theme: Theme) => ({
142
142
  alignItems: 'center',
143
143
  gap: theme.space.md,
144
144
  width: '100%',
145
- backgroundColor: theme.color.bg.cardHeader,
146
- borderRadius: theme.radius.md,
147
- padding: `${theme.space.md} ${theme.space.lg} ${theme.space.md} ${theme.space.sm}`,
145
+ ...theme.recipe.row,
148
146
  '& $content': {
149
147
  display: 'flex',
150
148
  flexDirection: 'column',
@@ -95,6 +95,10 @@ export interface Theme {
95
95
  section: string;
96
96
  };
97
97
  success: string;
98
+ /** Solid warning colour for icons and accents. */
99
+ warning: string;
100
+ /** Solid info colour for icons and accents. */
101
+ info: string;
98
102
  brand: {
99
103
  default: string;
100
104
  hover: string;
@@ -129,6 +133,11 @@ export interface Theme {
129
133
  // Quiet grey for states that carry no category (e.g. "no change"), built
130
134
  // from the mode's muted text colour.
131
135
  neutral: { text: string; bg: string; border: string };
136
+ // Status tones for state, as opposed to the label tones above.
137
+ success: { text: string; bg: string; border: string };
138
+ warning: { text: string; bg: string; border: string };
139
+ danger: { text: string; bg: string; border: string };
140
+ info: { text: string; bg: string; border: string };
132
141
  };
133
142
  };
134
143
  space: {
@@ -201,6 +210,8 @@ export interface Theme {
201
210
  spinner: Recipe;
202
211
  glass: Recipe;
203
212
  glassHighlight: Recipe;
213
+ /** The shaded field row (`bg.cardHeader`, `md` corners) a control sits in inside a card. */
214
+ row: Recipe;
204
215
  modal: {
205
216
  dialog: Recipe;
206
217
  header: Recipe;
@@ -265,6 +276,8 @@ function buildTheme(mode: ThemeMode): Theme {
265
276
  section: '#E6E6E9',
266
277
  },
267
278
  success: '#16a34a',
279
+ warning: '#ca8a04',
280
+ info: blue[500],
268
281
  brand: {
269
282
  default: blue[500],
270
283
  hover: blue[400],
@@ -305,6 +318,22 @@ function buildTheme(mode: ThemeMode): Theme {
305
318
  bg: applyTransparency(gray[600], 0.08),
306
319
  border: applyTransparency(gray[600], 0.22),
307
320
  },
321
+ success: {
322
+ text: '#15803d',
323
+ bg: applyTransparency('#16a34a', 0.08),
324
+ border: applyTransparency('#16a34a', 0.22),
325
+ },
326
+ warning: { text: '#854d0e', bg: 'rgba(234,179,8,0.16)', border: 'rgba(202,138,4,0.40)' },
327
+ danger: {
328
+ text: red[700],
329
+ bg: applyTransparency(red[500], 0.08),
330
+ border: applyTransparency(red[500], 0.22),
331
+ },
332
+ info: {
333
+ text: blue[700],
334
+ bg: applyTransparency(blue[500], 0.08),
335
+ border: applyTransparency(blue[500], 0.24),
336
+ },
308
337
  },
309
338
  };
310
339
 
@@ -357,6 +386,8 @@ function buildTheme(mode: ThemeMode): Theme {
357
386
  section: '#2B2C30',
358
387
  },
359
388
  success: '#22C55E',
389
+ warning: '#EAB308',
390
+ info: blue[400],
360
391
  brand: {
361
392
  default: blue[400],
362
393
  hover: blue[300],
@@ -398,6 +429,22 @@ function buildTheme(mode: ThemeMode): Theme {
398
429
  bg: applyTransparency(darkMuted, 0.16),
399
430
  border: applyTransparency(darkMuted, 0.3),
400
431
  },
432
+ success: {
433
+ text: '#86EFAC',
434
+ bg: applyTransparency('#22C55E', 0.16),
435
+ border: applyTransparency('#22C55E', 0.3),
436
+ },
437
+ warning: { text: '#FDE047', bg: 'rgba(234,179,8,0.20)', border: 'rgba(234,179,8,0.42)' },
438
+ danger: {
439
+ text: red[400],
440
+ bg: applyTransparency(red[500], 0.16),
441
+ border: applyTransparency(red[500], 0.3),
442
+ },
443
+ info: {
444
+ text: blue[300],
445
+ bg: applyTransparency(blue[400], 0.18),
446
+ border: applyTransparency(blue[400], 0.36),
447
+ },
401
448
  },
402
449
  };
403
450
 
@@ -568,6 +615,11 @@ function buildTheme(mode: ThemeMode): Theme {
568
615
  borderColor: color.border.glassActive,
569
616
  boxShadow: shadow.glassActive,
570
617
  },
618
+ row: {
619
+ backgroundColor: color.bg.cardHeader,
620
+ borderRadius: radius.md,
621
+ padding: `${space.md} ${space.lg} ${space.md} ${space.sm}`,
622
+ },
571
623
  modal: {
572
624
  dialog: {
573
625
  cursor: 'default',