@korzun/design 0.0.4 → 0.0.6

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 (199) hide show
  1. package/AGENTS.md +3 -0
  2. package/dist/component/card/index.d.ts +13 -2
  3. package/dist/component/card/index.d.ts.map +1 -1
  4. package/dist/component/card/index.js +1 -0
  5. package/dist/component/card/index.js.map +1 -1
  6. package/dist/component/card/style.d.ts.map +1 -1
  7. package/dist/component/card/style.js +3 -1
  8. package/dist/component/card/style.js.map +1 -1
  9. package/dist/component/card-divider/index.d.ts +15 -0
  10. package/dist/component/card-divider/index.d.ts.map +1 -1
  11. package/dist/component/card-divider/index.js +4 -0
  12. package/dist/component/card-divider/index.js.map +1 -1
  13. package/dist/component/card-row/index.d.ts +5 -0
  14. package/dist/component/card-row/index.d.ts.map +1 -1
  15. package/dist/component/card-row/index.js +1 -0
  16. package/dist/component/card-row/index.js.map +1 -1
  17. package/dist/component/card-row/style.js +1 -1
  18. package/dist/component/card-row/style.js.map +1 -1
  19. package/dist/component/collapsible-section/index.d.ts +8 -3
  20. package/dist/component/collapsible-section/index.d.ts.map +1 -1
  21. package/dist/component/collapsible-section/index.js +1 -0
  22. package/dist/component/collapsible-section/index.js.map +1 -1
  23. package/dist/component/empty-state/index.d.ts +2 -2
  24. package/dist/component/empty-state/index.d.ts.map +1 -1
  25. package/dist/component/empty-state/index.js.map +1 -1
  26. package/dist/component/index.d.ts +10 -10
  27. package/dist/component/index.d.ts.map +1 -1
  28. package/dist/component/index.js.map +1 -1
  29. package/dist/component/meta-line/index.d.ts +1 -1
  30. package/dist/component/meta-line/index.d.ts.map +1 -1
  31. package/dist/component/meta-line/index.js.map +1 -1
  32. package/dist/component/metadata/index.d.ts +2 -0
  33. package/dist/component/metadata/index.d.ts.map +1 -1
  34. package/dist/component/metadata/index.js +1 -0
  35. package/dist/component/metadata/index.js.map +1 -1
  36. package/dist/component/metadata-list/index.d.ts +6 -2
  37. package/dist/component/metadata-list/index.d.ts.map +1 -1
  38. package/dist/component/metadata-list/index.js +1 -0
  39. package/dist/component/metadata-list/index.js.map +1 -1
  40. package/dist/component/nav-desktop/index.d.ts +6 -0
  41. package/dist/component/nav-desktop/index.d.ts.map +1 -1
  42. package/dist/component/nav-desktop/index.js +5 -2
  43. package/dist/component/nav-desktop/index.js.map +1 -1
  44. package/dist/component/nav-mobile/index.d.ts +11 -3
  45. package/dist/component/nav-mobile/index.d.ts.map +1 -1
  46. package/dist/component/nav-mobile/index.js +5 -0
  47. package/dist/component/nav-mobile/index.js.map +1 -1
  48. package/dist/component/nav-types.d.ts +4 -0
  49. package/dist/component/nav-types.d.ts.map +1 -1
  50. package/dist/component/nav-types.js.map +1 -1
  51. package/dist/component/page/index.d.ts +10 -2
  52. package/dist/component/page/index.d.ts.map +1 -1
  53. package/dist/component/page/index.js +1 -0
  54. package/dist/component/page/index.js.map +1 -1
  55. package/dist/component/progress-indicator/index.d.ts +4 -2
  56. package/dist/component/progress-indicator/index.d.ts.map +1 -1
  57. package/dist/component/progress-indicator/index.js +1 -0
  58. package/dist/component/progress-indicator/index.js.map +1 -1
  59. package/dist/component/tag/index.d.ts +6 -3
  60. package/dist/component/tag/index.d.ts.map +1 -1
  61. package/dist/component/tag/index.js +1 -0
  62. package/dist/component/tag/index.js.map +1 -1
  63. package/dist/component/theme-setting/index.d.ts +6 -0
  64. package/dist/component/theme-setting/index.d.ts.map +1 -1
  65. package/dist/component/theme-setting/index.js +4 -0
  66. package/dist/component/theme-setting/index.js.map +1 -1
  67. package/dist/component/top-fade/index.d.ts +7 -0
  68. package/dist/component/top-fade/index.d.ts.map +1 -1
  69. package/dist/component/top-fade/index.js +5 -2
  70. package/dist/component/top-fade/index.js.map +1 -1
  71. package/dist/control/action-menu-list/index.d.ts +7 -0
  72. package/dist/control/action-menu-list/index.d.ts.map +1 -1
  73. package/dist/control/action-menu-list/index.js.map +1 -1
  74. package/dist/control/back-button/index.d.ts +9 -2
  75. package/dist/control/back-button/index.d.ts.map +1 -1
  76. package/dist/control/back-button/index.js +4 -0
  77. package/dist/control/back-button/index.js.map +1 -1
  78. package/dist/control/button/index.d.ts +30 -1
  79. package/dist/control/button/index.d.ts.map +1 -1
  80. package/dist/control/button/index.js +4 -0
  81. package/dist/control/button/index.js.map +1 -1
  82. package/dist/control/chips-input/index.d.ts +20 -0
  83. package/dist/control/chips-input/index.d.ts.map +1 -1
  84. package/dist/control/chips-input/index.js +4 -0
  85. package/dist/control/chips-input/index.js.map +1 -1
  86. package/dist/control/confirm-modal/index.d.ts +15 -2
  87. package/dist/control/confirm-modal/index.d.ts.map +1 -1
  88. package/dist/control/confirm-modal/index.js +4 -0
  89. package/dist/control/confirm-modal/index.js.map +1 -1
  90. package/dist/control/date-time-input/index.d.ts +4 -0
  91. package/dist/control/date-time-input/index.d.ts.map +1 -1
  92. package/dist/control/date-time-input/index.js.map +1 -1
  93. package/dist/control/field-list/index.d.ts +20 -2
  94. package/dist/control/field-list/index.d.ts.map +1 -1
  95. package/dist/control/field-list/index.js +4 -0
  96. package/dist/control/field-list/index.js.map +1 -1
  97. package/dist/control/index.d.ts +16 -21
  98. package/dist/control/index.d.ts.map +1 -1
  99. package/dist/control/index.js +5 -5
  100. package/dist/control/index.js.map +1 -1
  101. package/dist/control/number-input/index.d.ts +12 -0
  102. package/dist/control/number-input/index.d.ts.map +1 -1
  103. package/dist/control/number-input/index.js +4 -0
  104. package/dist/control/number-input/index.js.map +1 -1
  105. package/dist/control/page-actions-bar/index.d.ts +11 -3
  106. package/dist/control/page-actions-bar/index.d.ts.map +1 -1
  107. package/dist/control/page-actions-bar/index.js +5 -1
  108. package/dist/control/page-actions-bar/index.js.map +1 -1
  109. package/dist/control/page-actions-menu/index.d.ts +6 -1
  110. package/dist/control/page-actions-menu/index.d.ts.map +1 -1
  111. package/dist/control/page-actions-menu/index.js +4 -0
  112. package/dist/control/page-actions-menu/index.js.map +1 -1
  113. package/dist/control/page-footer-actions/index.d.ts +16 -2
  114. package/dist/control/page-footer-actions/index.d.ts.map +1 -1
  115. package/dist/control/page-footer-actions/index.js +4 -0
  116. package/dist/control/page-footer-actions/index.js.map +1 -1
  117. package/dist/control/popover/index.d.ts +6 -3
  118. package/dist/control/popover/index.d.ts.map +1 -1
  119. package/dist/control/popover/index.js +2 -0
  120. package/dist/control/popover/index.js.map +1 -1
  121. package/dist/control/segmented-control/index.d.ts +10 -3
  122. package/dist/control/segmented-control/index.d.ts.map +1 -1
  123. package/dist/control/segmented-control/index.js.map +1 -1
  124. package/dist/control/select/index.d.ts +17 -0
  125. package/dist/control/select/index.d.ts.map +1 -1
  126. package/dist/control/select/index.js +4 -0
  127. package/dist/control/select/index.js.map +1 -1
  128. package/dist/control/switch/index.d.ts +16 -2
  129. package/dist/control/switch/index.d.ts.map +1 -1
  130. package/dist/control/switch/index.js +4 -0
  131. package/dist/control/switch/index.js.map +1 -1
  132. package/dist/control/switch/style.d.ts.map +1 -1
  133. package/dist/control/switch/style.js +1 -3
  134. package/dist/control/switch/style.js.map +1 -1
  135. package/dist/control/text-area/index.d.ts +15 -0
  136. package/dist/control/text-area/index.d.ts.map +1 -1
  137. package/dist/control/text-area/index.js +4 -0
  138. package/dist/control/text-area/index.js.map +1 -1
  139. package/dist/control/text-input/index.d.ts +23 -1
  140. package/dist/control/text-input/index.d.ts.map +1 -1
  141. package/dist/control/text-input/index.js +4 -0
  142. package/dist/control/text-input/index.js.map +1 -1
  143. package/dist/control/use-modal-dialog/index.d.ts +7 -1
  144. package/dist/control/use-modal-dialog/index.d.ts.map +1 -1
  145. package/dist/control/use-modal-dialog/index.js +5 -0
  146. package/dist/control/use-modal-dialog/index.js.map +1 -1
  147. package/dist/theme/theme.d.ts +2 -0
  148. package/dist/theme/theme.d.ts.map +1 -1
  149. package/dist/theme/theme.js +5 -0
  150. package/dist/theme/theme.js.map +1 -1
  151. package/docs/component/card-row.md +11 -12
  152. package/docs/component/card.md +4 -5
  153. package/docs/control/confirm-modal.md +1 -2
  154. package/docs/control/segmented-control.md +2 -2
  155. package/docs/corners.md +4 -4
  156. package/docs/philosophy.md +1 -1
  157. package/docs/theme.md +1 -0
  158. package/docs/tokens.md +1 -0
  159. package/package.json +1 -1
  160. package/src/component/card/index.tsx +14 -2
  161. package/src/component/card/style.ts +3 -1
  162. package/src/component/card-divider/index.tsx +15 -6
  163. package/src/component/card-row/index.tsx +6 -0
  164. package/src/component/card-row/style.ts +1 -1
  165. package/src/component/collapsible-section/index.tsx +8 -2
  166. package/src/component/empty-state/index.tsx +2 -2
  167. package/src/component/index.ts +10 -10
  168. package/src/component/meta-line/index.tsx +1 -1
  169. package/src/component/metadata/index.tsx +6 -1
  170. package/src/component/metadata-list/index.tsx +13 -2
  171. package/src/component/nav-desktop/index.tsx +6 -2
  172. package/src/component/nav-mobile/index.tsx +11 -3
  173. package/src/component/nav-types.ts +4 -0
  174. package/src/component/page/index.tsx +11 -1
  175. package/src/component/progress-indicator/index.tsx +4 -1
  176. package/src/component/tag/index.tsx +6 -3
  177. package/src/component/theme-setting/index.tsx +7 -0
  178. package/src/component/top-fade/index.tsx +8 -2
  179. package/src/control/action-menu-list/index.tsx +7 -0
  180. package/src/control/back-button/index.tsx +9 -1
  181. package/src/control/button/index.tsx +39 -5
  182. package/src/control/chips-input/index.tsx +20 -3
  183. package/src/control/confirm-modal/index.tsx +15 -1
  184. package/src/control/date-time-input/index.tsx +4 -0
  185. package/src/control/field-list/index.tsx +20 -1
  186. package/src/control/index.ts +39 -22
  187. package/src/control/number-input/index.tsx +12 -0
  188. package/src/control/page-actions-bar/index.tsx +16 -2
  189. package/src/control/page-actions-menu/index.tsx +6 -1
  190. package/src/control/page-footer-actions/index.tsx +16 -1
  191. package/src/control/popover/index.tsx +6 -2
  192. package/src/control/segmented-control/index.tsx +10 -3
  193. package/src/control/select/index.tsx +17 -1
  194. package/src/control/switch/index.tsx +17 -1
  195. package/src/control/switch/style.ts +1 -3
  196. package/src/control/text-area/index.tsx +15 -0
  197. package/src/control/text-input/index.tsx +25 -0
  198. package/src/control/use-modal-dialog/index.ts +11 -2
  199. package/src/theme/theme.ts +7 -0
@@ -14,12 +14,14 @@ import { useStyle } from './style.js';
14
14
 
15
15
  type Position = { top: number; left: number; width: number };
16
16
 
17
- type Props = {
17
+ export type PopoverProps = {
18
18
  /** Element the popover aligns to (positioned directly beneath it). */
19
19
  anchorRef: RefObject<HTMLElement | null>;
20
20
  /** Whether the popover is rendered. */
21
21
  open: boolean;
22
+ /** Your surface: give it its own background, border, and radius. */
22
23
  children: ReactNode;
24
+ /** Applied to the fixed wrapper; win specificity with `'&&'`, never `!important`. */
23
25
  className?: string;
24
26
  /** Vertical gap between the anchor and the popover, in pixels. */
25
27
  gap?: number;
@@ -37,6 +39,8 @@ type Props = {
37
39
  * coordinates directly under `anchorRef`. This lets dropdowns escape ancestors
38
40
  * that clip overflow (e.g. cards with rounded corners) without those ancestors
39
41
  * having to opt out of clipping.
42
+ *
43
+ * No Escape handling or focus management, and it never flips above the anchor.
40
44
  */
41
45
  export const Popover = ({
42
46
  anchorRef,
@@ -46,7 +50,7 @@ export const Popover = ({
46
50
  gap = 4,
47
51
  matchWidth = true,
48
52
  onClose,
49
- }: Props) => {
53
+ }: PopoverProps) => {
50
54
  const style = useStyle();
51
55
  const contentRef = useRef<HTMLDivElement>(null);
52
56
  const [position, setPosition] = useState<Position | null>(null);
@@ -4,17 +4,23 @@ import { type CSSProperties, type KeyboardEvent, useRef } from 'react';
4
4
  import type { IconProps } from '../../icon/index.js';
5
5
  import { useStyle } from './style.js';
6
6
 
7
+ /** One segment of a `SegmentedControl`. */
7
8
  export type SegmentedOption<V extends string> = {
9
+ /** The value passed to `onChange` when this segment is picked. */
8
10
  value: V;
9
11
  /** The segment's accessible name, and its visible text unless `showLabels` is off. */
10
12
  label: string;
11
- /** Drawn above the label, which then becomes a small caption under it. */
13
+ /**
14
+ * Icon component (`Icon: SearchIcon`), not an element. Drawn above the label,
15
+ * which then becomes a small caption under it.
16
+ */
12
17
  Icon?: (props: IconProps) => React.JSX.Element;
13
18
  };
14
19
 
15
20
  type BaseProps<V extends string> = {
16
- /** The group's accessible name, e.g. the setting or field it edits. */
21
+ /** The group's accessible name, e.g. the setting or field it edits. Not rendered visibly. */
17
22
  label: string;
23
+ /** The segments, in order. Declare them `as const` or type them as `SegmentedOption<V>`. */
18
24
  options: ReadonlyArray<SegmentedOption<V>>;
19
25
  /** The checked option; `null` (or a value no option has) checks nothing and draws no lens. */
20
26
  value: V | null;
@@ -32,7 +38,7 @@ type BaseProps<V extends string> = {
32
38
  surface?: 'card' | 'row';
33
39
  };
34
40
 
35
- type SegmentedControlProps<V extends string> = BaseProps<V> &
41
+ export type SegmentedControlProps<V extends string> = BaseProps<V> &
36
42
  (
37
43
  | {
38
44
  /** Clicking (or Space/Enter on) the checked segment, Backspace and Delete clear the value. */
@@ -41,6 +47,7 @@ type SegmentedControlProps<V extends string> = BaseProps<V> &
41
47
  onChange?: (value: V | null) => void;
42
48
  }
43
49
  | {
50
+ /** Off by default: clicking the checked segment does nothing and there is no way to clear. */
44
51
  clearable?: false;
45
52
  /** Absent means read-only: the control shows the value and ignores input. */
46
53
  onChange?: (value: V) => void;
@@ -5,21 +5,31 @@ import { ChevronIcon, SpinnerIcon } from '../../icon/index.js';
5
5
  import { Popover } from '../popover/index.js';
6
6
  import { useStyle } from './style.js';
7
7
 
8
+ /** A `Select` option: a plain string (label and value alike), or `{ label, value, description? }`. */
8
9
  export type SelectOption = string | { label: string; value: string; description?: string };
9
10
 
10
11
  type InternalOption = { label: string; value: string; description?: string; _isCreate?: boolean };
11
12
 
12
13
  export type SelectProps = {
14
+ /** With a search query that matches no label exactly, offers an "Add: *query*" option. */
13
15
  allowCreate?: boolean;
14
- // Show the inline "clear" (✕) control when a value is selected (default true).
16
+ /** Show the inline "clear" (✕) control when a value is selected (default true). */
15
17
  clearable?: boolean;
18
+ /** Faded; can't open; no clear button. */
16
19
  disabled?: boolean;
20
+ /** Visible label; it targets the search box, not the closed trigger. */
17
21
  label?: string;
22
+ /** Default `'horizontal'`; `horizontal`/`vertical` paint a card-header row. */
18
23
  layout?: 'horizontal' | 'vertical' | 'inline';
24
+ /** Shows a spinner and "Loading…"; can't open. */
19
25
  loading?: boolean;
26
+ /** Only lands on the search box while open: form data never carries the selection. */
20
27
  name: string;
28
+ /** Receives the option's `value`, `undefined` from clear, or the trimmed typed text from "Add:"; not an event. */
21
29
  onChange?: (value: string | undefined) => void;
30
+ /** Strings or `{ label, value, description? }` objects, mixed freely. */
22
31
  options: SelectOption[];
32
+ /** Shown when nothing is selected. Default `'Select…'`. */
23
33
  placeholder?: string;
24
34
  /**
25
35
  * Which surface this select sits on, which decides its corner radius AND its
@@ -37,7 +47,9 @@ export type SelectProps = {
37
47
  * because here the radius is a consequence, not the choice.
38
48
  */
39
49
  surface?: 'card' | 'page';
50
+ /** Opening swaps the trigger for a search box (default `true`); `false` is a plain list, arrow keys only. */
40
51
  searchable?: boolean;
52
+ /** Controlled selection; a value not in `options` displays as the raw string. */
41
53
  value: string | undefined;
42
54
  };
43
55
 
@@ -58,6 +70,10 @@ function highlight(text: string, query: string, className: string): React.ReactN
58
70
  );
59
71
  }
60
72
 
73
+ /**
74
+ * Controlled single-value picker with an optional search box and "Add:" entry,
75
+ * its list in a `Popover`. No hidden input: submit `value` from state.
76
+ */
61
77
  export const Select = ({
62
78
  allowCreate = false,
63
79
  clearable = true,
@@ -39,7 +39,9 @@ function useDelayedFlag(active: boolean, delayMs: number): boolean {
39
39
  return elapsed;
40
40
  }
41
41
 
42
- type SwitchProps = {
42
+ export type { SwitchRadiusValue };
43
+
44
+ export type SwitchProps = {
43
45
  /**
44
46
  * Accessible name when the visible `label` is absent because something
45
47
  * OUTSIDE the switch already carries it — a grid's row and column headers,
@@ -47,10 +49,18 @@ type SwitchProps = {
47
49
  * machine key (`BOOK_REQUEST_FULFILLED:EMAIL`), not a name.
48
50
  */
49
51
  ariaLabel?: string;
52
+ /** Controlled on/off state. */
50
53
  checked: boolean;
54
+ /** Helper text under the label, linked by `aria-describedby`. */
51
55
  description?: ReactNode;
56
+ /** Fades the switch and removes it from the tab order. */
52
57
  disabled?: boolean;
58
+ /** Visible label and accessible name (`ariaLabel` wins over it). */
53
59
  label?: string;
60
+ /**
61
+ * `'default'`: track then label, inline. `'horizontal'`: full-width shaded
62
+ * row, track on the right; the whole row toggles, description included.
63
+ */
54
64
  layout?: 'default' | 'horizontal';
55
65
  /**
56
66
  * A save driven by this switch is in flight. The thumb becomes a spinner
@@ -63,7 +73,9 @@ type SwitchProps = {
63
73
  * where the click is taking it.
64
74
  */
65
75
  loading?: boolean;
76
+ /** Not a form field (no hidden input); only the last-resort accessible name. */
66
77
  name: string;
78
+ /** Receives the new value, not an event. Not called while `disabled` or `loading`. */
67
79
  onChange: (checked: boolean) => void;
68
80
  /**
69
81
  * The corner shape of the track, named for what the switch sits in. Defaults
@@ -74,6 +86,10 @@ type SwitchProps = {
74
86
  radius?: SwitchRadiusValue;
75
87
  };
76
88
 
89
+ /**
90
+ * Controlled on/off toggle with an optional label and description. Enter and
91
+ * Space toggle; clicks don't propagate to a clickable parent row.
92
+ */
77
93
  export const Switch = ({
78
94
  ariaLabel,
79
95
  checked,
@@ -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',
@@ -4,19 +4,34 @@ import { useCallback, useEffect, useRef, useState } from 'react';
4
4
  import { useStyle } from './style.js';
5
5
 
6
6
  export type TextAreaProps = {
7
+ /** Grows to fit content (min height 7rem, else 10rem; set inline, so a class can't lower it). */
7
8
  autoResize?: boolean;
9
+ /** Visible label. Not linked to the textarea (no `htmlFor`). */
8
10
  label?: string;
11
+ /** Default `'horizontal'`; `horizontal`/`vertical` paint a card-header row. */
9
12
  layout?: 'horizontal' | 'vertical' | 'inline';
13
+ /** Native limit, plus an `n/max` counter once within `max(10% of max, 50)` characters. */
10
14
  maxLength?: number;
15
+ /** The textarea's `name` and the key passed to `onValidChange`. */
11
16
  name: string;
17
+ /** Receives the string, or `undefined` when emptied; not an event. Not called while `validate` fails. */
12
18
  onChange?: (newValue: string | undefined) => void;
19
+ /** Called with `name` and the new validity; fires only when validity flips. */
13
20
  onValidChange?: (fieldName: string, newValid: boolean) => void;
21
+ /** Placeholder text for the textarea. */
14
22
  placeholder?: string;
23
+ /** Receives the raw text on each keystroke; `false` turns the label red. Default accepts all. */
15
24
  validate?: (newValue: string) => boolean;
25
+ /** Typed as required (pass `undefined` for empty). Re-syncs into the field only when the prop changes. */
16
26
  value: string | undefined;
27
+ /** `'outlined'` (default) has border and input background; `'borderless'` drops both (check dark mode). */
17
28
  variant?: 'outlined' | 'borderless';
18
29
  };
19
30
 
31
+ /**
32
+ * Multi-line text field with optional auto-resize and a length counter.
33
+ * Keeps its own text and re-syncs from `value` only when the prop changes.
34
+ */
20
35
  export const TextArea = ({
21
36
  autoResize = false,
22
37
  label,
@@ -5,28 +5,53 @@ import { IconProps } from '../../icon/index.js';
5
5
  import { Button } from '../button/index.js';
6
6
  import { useStyle } from './style.js';
7
7
 
8
+ /** Trailing icon button of a `TextInput`. Broken: `action` is never called. */
8
9
  type Action = {
10
+ /** Icon component, not an element. */
9
11
  icon: React.ComponentType<IconProps>;
12
+ /** Never wired up: clicking the icon does nothing. */
10
13
  action: () => void;
14
+ /** Red icon. */
11
15
  danger?: boolean;
12
16
  };
17
+
18
+ export type { Action as TextInputAction };
19
+
13
20
  export type TextInputProps = {
21
+ /** Broken, do not use: the icon button is drawn but its `action` callback is never wired up. */
14
22
  action?: Action;
23
+ /** Passed through to the input. */
15
24
  autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters';
25
+ /** Passed through to the input. */
16
26
  autoComplete?: React.HTMLInputAutoCompleteAttribute | undefined;
27
+ /** Visible label. Not linked to the input (no `htmlFor`). */
17
28
  label?: string;
29
+ /** Default `'horizontal'`; `horizontal`/`vertical` paint a card-header row, `inline` paints nothing. */
18
30
  layout?: 'horizontal' | 'vertical' | 'inline';
31
+ /** Native limit, plus an `n/max` counter once within `max(10% of max, 10)` characters. */
19
32
  maxLength?: number;
33
+ /** The input's `name` (form data) and the key passed to `onValidChange`. */
20
34
  name: string;
35
+ /** Receives the string, or `undefined` when emptied; not an event. Not called while `validate` fails. */
21
36
  onChange?: (newValue: string | undefined) => void;
37
+ /** Passed through; unlike `onChange`, this one receives the event. */
22
38
  onKeyDown?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
39
+ /** Called with `name` and the new validity; fires only when validity flips. */
23
40
  onValidChange?: (fieldName: string, newValid: boolean) => void;
41
+ /** Renders `type="password"`. */
24
42
  password?: boolean;
43
+ /** Placeholder text for the input. */
25
44
  placeholder?: string;
45
+ /** Receives the raw text on each keystroke; `false` turns label and border red. Default accepts all. */
26
46
  validate?: (newValue: string) => boolean;
47
+ /** Typed as required (pass `undefined` for empty). Re-syncs into the field only when the prop changes. */
27
48
  value: string | undefined;
28
49
  };
29
50
 
51
+ /**
52
+ * Single-line text field. Keeps its own text and re-syncs from `value` only
53
+ * when the prop changes; `onChange` is skipped while `validate` fails.
54
+ */
30
55
  export const TextInput = ({
31
56
  autoCapitalize,
32
57
  autoComplete,
@@ -1,4 +1,4 @@
1
- import { useEffect, useRef } from 'react';
1
+ import { type RefObject, useEffect, useRef } from 'react';
2
2
 
3
3
  /**
4
4
  * Drives a native `<dialog>` from an `isOpen` flag and wires up ESC-to-dismiss.
@@ -21,8 +21,17 @@ import { useEffect, useRef } from 'react';
21
21
  * released over the backdrop also clicks the `<dialog>` — and must not close
22
22
  * it. Modals keep their own `onClick` only to stop the click bubbling to a
23
23
  * clickable ancestor; they no longer decide dismissal.
24
+ *
25
+ * @param isOpen The single source of truth: `true` calls `showModal()`, `false` calls `close()`.
26
+ * @param onDismiss Called on Escape and a backdrop click; receives no event and closes nothing itself.
27
+ * @param canDismiss When `false`, Escape and backdrop clicks are swallowed; pass `!loading`. Default `true`.
28
+ * @returns A ref to attach to a `<dialog>` that stays mounted.
24
29
  */
25
- export function useModalDialog(isOpen: boolean, onDismiss: () => void, canDismiss = true) {
30
+ export function useModalDialog(
31
+ isOpen: boolean,
32
+ onDismiss: () => void,
33
+ canDismiss = true
34
+ ): RefObject<HTMLDialogElement | null> {
26
35
  const ref = useRef<HTMLDialogElement>(null);
27
36
 
28
37
  useEffect(() => {
@@ -201,6 +201,8 @@ export interface Theme {
201
201
  spinner: Recipe;
202
202
  glass: Recipe;
203
203
  glassHighlight: Recipe;
204
+ /** The shaded field row (`bg.cardHeader`, `md` corners) a control sits in inside a card. */
205
+ row: Recipe;
204
206
  modal: {
205
207
  dialog: Recipe;
206
208
  header: Recipe;
@@ -568,6 +570,11 @@ function buildTheme(mode: ThemeMode): Theme {
568
570
  borderColor: color.border.glassActive,
569
571
  boxShadow: shadow.glassActive,
570
572
  },
573
+ row: {
574
+ backgroundColor: color.bg.cardHeader,
575
+ borderRadius: radius.md,
576
+ padding: `${space.md} ${space.lg} ${space.md} ${space.sm}`,
577
+ },
571
578
  modal: {
572
579
  dialog: {
573
580
  cursor: 'default',