@slotform/react-ui 0.0.0-stage → 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 (280) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +44 -2
  3. package/dist/density.d.ts +4 -0
  4. package/dist/density.d.ts.map +1 -0
  5. package/dist/density.js +8 -0
  6. package/dist/density.js.map +1 -0
  7. package/dist/index.d.ts +400 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +388 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/node/canvas.d.ts +3 -0
  12. package/dist/node/canvas.d.ts.map +1 -0
  13. package/dist/node/canvas.js +13 -0
  14. package/dist/node/canvas.js.map +1 -0
  15. package/dist/node/codegen.d.ts +6 -0
  16. package/dist/node/codegen.d.ts.map +1 -0
  17. package/dist/node/codegen.js +70 -0
  18. package/dist/node/codegen.js.map +1 -0
  19. package/dist/node/css-escape.d.ts +8 -0
  20. package/dist/node/css-escape.d.ts.map +1 -0
  21. package/dist/node/css-escape.js +12 -0
  22. package/dist/node/css-escape.js.map +1 -0
  23. package/dist/node/fonts.d.ts +6 -0
  24. package/dist/node/fonts.d.ts.map +1 -0
  25. package/dist/node/fonts.js +219 -0
  26. package/dist/node/fonts.js.map +1 -0
  27. package/dist/node/lint.d.ts +3 -0
  28. package/dist/node/lint.d.ts.map +1 -0
  29. package/dist/node/lint.js +23 -0
  30. package/dist/node/lint.js.map +1 -0
  31. package/dist/node/mode.d.ts +9 -0
  32. package/dist/node/mode.d.ts.map +1 -0
  33. package/dist/node/mode.js +38 -0
  34. package/dist/node/mode.js.map +1 -0
  35. package/dist/node/theme.d.ts +13 -0
  36. package/dist/node/theme.d.ts.map +1 -0
  37. package/dist/node/theme.js +160 -0
  38. package/dist/node/theme.js.map +1 -0
  39. package/dist/types.d.ts +250 -0
  40. package/dist/types.d.ts.map +1 -0
  41. package/dist/types.js +80 -0
  42. package/dist/types.js.map +1 -0
  43. package/guide/acts.md +61 -0
  44. package/guide/audio.md +77 -0
  45. package/guide/blocks.md +82 -0
  46. package/guide/canvas-choosing.md +34 -0
  47. package/guide/canvas-editing.md +36 -0
  48. package/guide/canvas-layout.md +46 -0
  49. package/guide/canvas-opening.md +47 -0
  50. package/guide/canvas-overview.md +24 -0
  51. package/guide/canvas-states.md +37 -0
  52. package/guide/canvas-view.md +46 -0
  53. package/guide/canvas.md +94 -0
  54. package/guide/containers.md +60 -0
  55. package/guide/content.md +40 -0
  56. package/guide/controls.md +89 -0
  57. package/guide/density.md +48 -0
  58. package/guide/dock.md +42 -0
  59. package/guide/drag.md +38 -0
  60. package/guide/figures.md +25 -0
  61. package/guide/forms.md +82 -0
  62. package/guide/pane-bar.md +11 -0
  63. package/guide/pane.md +50 -0
  64. package/guide/reference.md +74 -0
  65. package/guide/rules.md +109 -0
  66. package/guide/section.md +29 -0
  67. package/guide/shell.md +26 -0
  68. package/guide/shots.md +37 -0
  69. package/guide/sidebar.md +30 -0
  70. package/guide/table.md +119 -0
  71. package/lint/no-arbitrary-value.grit +9 -0
  72. package/lint/no-class-on-component.grit +12 -0
  73. package/lint/no-density.grit +8 -0
  74. package/lint/no-host-look.grit +38 -0
  75. package/lint/no-img.grit +10 -0
  76. package/lint/no-navigate-act.grit +22 -0
  77. package/lint/no-raw-style.grit +8 -0
  78. package/package.json +150 -3
  79. package/src/density.ts +9 -0
  80. package/src/index.ts +503 -0
  81. package/src/node/canvas.ts +14 -0
  82. package/src/node/codegen.ts +100 -0
  83. package/src/node/css-escape.ts +27 -0
  84. package/src/node/fonts.ts +260 -0
  85. package/src/node/lint.ts +25 -0
  86. package/src/node/mode.ts +64 -0
  87. package/src/node/theme.ts +232 -0
  88. package/src/types.ts +120 -0
  89. package/src/ui/atoms/avatar/base.tsx +42 -0
  90. package/src/ui/atoms/button/glyph.tsx +244 -0
  91. package/src/ui/atoms/button/link.tsx +81 -0
  92. package/src/ui/atoms/button/look.ts +32 -0
  93. package/src/ui/atoms/button/reason.tsx +69 -0
  94. package/src/ui/atoms/chip/base.tsx +85 -0
  95. package/src/ui/atoms/count/base.tsx +27 -0
  96. package/src/ui/atoms/icon/index.tsx +51 -0
  97. package/src/ui/atoms/message/waiting.tsx +19 -0
  98. package/src/ui/atoms/prose/painted.tsx +35 -0
  99. package/src/ui/atoms/row/badges.tsx +226 -0
  100. package/src/ui/atoms/row/leading.tsx +166 -0
  101. package/src/ui/atoms/row/lock.tsx +17 -0
  102. package/src/ui/atoms/row/marks.tsx +79 -0
  103. package/src/ui/atoms/section/card.tsx +27 -0
  104. package/src/ui/atoms/spinner/index.tsx +42 -0
  105. package/src/ui/atoms/status/base.tsx +51 -0
  106. package/src/ui/atoms/status/change.tsx +29 -0
  107. package/src/ui/atoms/status/dot.tsx +45 -0
  108. package/src/ui/atoms/switch/checkbox.tsx +121 -0
  109. package/src/ui/atoms/turn.tsx +28 -0
  110. package/src/ui/components/action-bar/base.tsx +276 -0
  111. package/src/ui/components/action-bar/index.tsx +20 -0
  112. package/src/ui/components/avatar/index.tsx +21 -0
  113. package/src/ui/components/banner/index.tsx +207 -0
  114. package/src/ui/components/banner/pending.tsx +109 -0
  115. package/src/ui/components/bar-chart/index.tsx +701 -0
  116. package/src/ui/components/button/base.tsx +214 -0
  117. package/src/ui/components/button/face.tsx +84 -0
  118. package/src/ui/components/button/index.tsx +206 -0
  119. package/src/ui/components/canvas/connection.tsx +26 -0
  120. package/src/ui/components/canvas/edges.tsx +116 -0
  121. package/src/ui/components/canvas/elk.ts +260 -0
  122. package/src/ui/components/canvas/floor.ts +173 -0
  123. package/src/ui/components/canvas/geometry.ts +772 -0
  124. package/src/ui/components/canvas/ground.tsx +97 -0
  125. package/src/ui/components/canvas/group.tsx +156 -0
  126. package/src/ui/components/canvas/hit.ts +40 -0
  127. package/src/ui/components/canvas/index.tsx +497 -0
  128. package/src/ui/components/canvas/label.tsx +53 -0
  129. package/src/ui/components/canvas/layout.ts +543 -0
  130. package/src/ui/components/canvas/lift.ts +272 -0
  131. package/src/ui/components/canvas/look.ts +129 -0
  132. package/src/ui/components/canvas/node.tsx +689 -0
  133. package/src/ui/components/canvas/open.ts +243 -0
  134. package/src/ui/components/canvas/opening.ts +240 -0
  135. package/src/ui/components/canvas/view.ts +621 -0
  136. package/src/ui/components/canvas/viewport.ts +417 -0
  137. package/src/ui/components/canvas/zoom.tsx +113 -0
  138. package/src/ui/components/card/index.tsx +20 -0
  139. package/src/ui/components/chip/index.tsx +24 -0
  140. package/src/ui/components/code/frame.ts +2 -0
  141. package/src/ui/components/code/index.tsx +234 -0
  142. package/src/ui/components/columns/index.tsx +51 -0
  143. package/src/ui/components/count/index.tsx +17 -0
  144. package/src/ui/components/diff/index.tsx +249 -0
  145. package/src/ui/components/diff/word.tsx +104 -0
  146. package/src/ui/components/dock/index.tsx +262 -0
  147. package/src/ui/components/file-row/index.tsx +213 -0
  148. package/src/ui/components/form/base.tsx +280 -0
  149. package/src/ui/components/form/derive.tsx +269 -0
  150. package/src/ui/components/form/index.tsx +49 -0
  151. package/src/ui/components/form/saved.tsx +39 -0
  152. package/src/ui/components/form-field/index.tsx +658 -0
  153. package/src/ui/components/gallery/index.tsx +83 -0
  154. package/src/ui/components/gate/index.tsx +183 -0
  155. package/src/ui/components/image/base.tsx +245 -0
  156. package/src/ui/components/image/index.tsx +58 -0
  157. package/src/ui/components/input/base.tsx +246 -0
  158. package/src/ui/components/input/code.tsx +108 -0
  159. package/src/ui/components/input/drop.ts +37 -0
  160. package/src/ui/components/input/file.tsx +154 -0
  161. package/src/ui/components/input/index.tsx +132 -0
  162. package/src/ui/components/input/prose.tsx +107 -0
  163. package/src/ui/components/input/refusal.tsx +30 -0
  164. package/src/ui/components/item-header/base.tsx +410 -0
  165. package/src/ui/components/menu/base.tsx +319 -0
  166. package/src/ui/components/message/attachments.tsx +101 -0
  167. package/src/ui/components/message/base.tsx +266 -0
  168. package/src/ui/components/message-input/index.tsx +377 -0
  169. package/src/ui/components/missing/base.tsx +45 -0
  170. package/src/ui/components/pane/head.tsx +399 -0
  171. package/src/ui/components/pane/index.tsx +325 -0
  172. package/src/ui/components/picker/base.tsx +1551 -0
  173. package/src/ui/components/picker/index.tsx +224 -0
  174. package/src/ui/components/picker/list.tsx +423 -0
  175. package/src/ui/components/picker/segments.tsx +183 -0
  176. package/src/ui/components/prose/index.tsx +259 -0
  177. package/src/ui/components/qr-code/index.tsx +65 -0
  178. package/src/ui/components/row/acts.tsx +126 -0
  179. package/src/ui/components/row/fact.tsx +54 -0
  180. package/src/ui/components/row/index.tsx +1370 -0
  181. package/src/ui/components/row/progress.tsx +38 -0
  182. package/src/ui/components/row/status.tsx +54 -0
  183. package/src/ui/components/row/title.ts +7 -0
  184. package/src/ui/components/rules/index.tsx +290 -0
  185. package/src/ui/components/section/band.tsx +39 -0
  186. package/src/ui/components/section/head.tsx +267 -0
  187. package/src/ui/components/section/index.tsx +409 -0
  188. package/src/ui/components/section/rows.tsx +356 -0
  189. package/src/ui/components/sheet/base.tsx +272 -0
  190. package/src/ui/components/sheet/confirm.tsx +79 -0
  191. package/src/ui/components/sheet/docked.tsx +218 -0
  192. package/src/ui/components/sheet/form.tsx +76 -0
  193. package/src/ui/components/sheet/head.tsx +120 -0
  194. package/src/ui/components/sheet/index.tsx +45 -0
  195. package/src/ui/components/sheet/layer.tsx +168 -0
  196. package/src/ui/components/sheet/outlet.tsx +58 -0
  197. package/src/ui/components/sheet/task.tsx +41 -0
  198. package/src/ui/components/shell/cut.tsx +116 -0
  199. package/src/ui/components/shell/drag.tsx +45 -0
  200. package/src/ui/components/shell/host.tsx +71 -0
  201. package/src/ui/components/shell/index.tsx +737 -0
  202. package/src/ui/components/shell/panes.tsx +76 -0
  203. package/src/ui/components/shell/preview.ts +230 -0
  204. package/src/ui/components/shell/rail.tsx +163 -0
  205. package/src/ui/components/shell/row.ts +11 -0
  206. package/src/ui/components/shell/switcher.tsx +143 -0
  207. package/src/ui/components/shell/tree.tsx +252 -0
  208. package/src/ui/components/slider/base.tsx +139 -0
  209. package/src/ui/components/slider/index.tsx +57 -0
  210. package/src/ui/components/stages/index.tsx +198 -0
  211. package/src/ui/components/stats/count-links.tsx +47 -0
  212. package/src/ui/components/stats/index.tsx +203 -0
  213. package/src/ui/components/stats/meter.tsx +213 -0
  214. package/src/ui/components/stats/parts.ts +10 -0
  215. package/src/ui/components/step-count/index.tsx +45 -0
  216. package/src/ui/components/switch/base.tsx +86 -0
  217. package/src/ui/components/switch/index.tsx +38 -0
  218. package/src/ui/components/table/columns.tsx +131 -0
  219. package/src/ui/components/table/index.tsx +2215 -0
  220. package/src/ui/components/text/index.tsx +37 -0
  221. package/src/ui/components/thread/index.tsx +503 -0
  222. package/src/ui/components/thread/latest.tsx +59 -0
  223. package/src/ui/components/toast/index.tsx +113 -0
  224. package/src/ui/components/toast/layer.tsx +26 -0
  225. package/src/ui/components/toolbar/filters.tsx +161 -0
  226. package/src/ui/components/toolbar/index.tsx +125 -0
  227. package/src/ui/components/waveform/index.tsx +205 -0
  228. package/src/ui/globals.css +427 -0
  229. package/src/ui/lib/act.ts +60 -0
  230. package/src/ui/lib/age.ts +49 -0
  231. package/src/ui/lib/bound.ts +16 -0
  232. package/src/ui/lib/canvas-layout.ts +11 -0
  233. package/src/ui/lib/caret.ts +9 -0
  234. package/src/ui/lib/chip-lines.ts +3 -0
  235. package/src/ui/lib/closed.ts +8 -0
  236. package/src/ui/lib/code.tsx +184 -0
  237. package/src/ui/lib/columns.ts +39 -0
  238. package/src/ui/lib/commit.ts +24 -0
  239. package/src/ui/lib/container.ts +112 -0
  240. package/src/ui/lib/copy.ts +29 -0
  241. package/src/ui/lib/drag.ts +575 -0
  242. package/src/ui/lib/empty.tsx +85 -0
  243. package/src/ui/lib/field.ts +39 -0
  244. package/src/ui/lib/focus.ts +175 -0
  245. package/src/ui/lib/folds.ts +67 -0
  246. package/src/ui/lib/follow.ts +220 -0
  247. package/src/ui/lib/form.ts +19 -0
  248. package/src/ui/lib/guards.ts +38 -0
  249. package/src/ui/lib/heading.ts +14 -0
  250. package/src/ui/lib/ink.ts +26 -0
  251. package/src/ui/lib/lang.ts +7 -0
  252. package/src/ui/lib/leave.ts +14 -0
  253. package/src/ui/lib/lockup.tsx +145 -0
  254. package/src/ui/lib/measure.ts +22 -0
  255. package/src/ui/lib/media.ts +63 -0
  256. package/src/ui/lib/modality.ts +69 -0
  257. package/src/ui/lib/moment.ts +13 -0
  258. package/src/ui/lib/more.tsx +76 -0
  259. package/src/ui/lib/navigate.ts +210 -0
  260. package/src/ui/lib/noop.ts +3 -0
  261. package/src/ui/lib/not-found.tsx +40 -0
  262. package/src/ui/lib/paint.tsx +55 -0
  263. package/src/ui/lib/parts-line.tsx +54 -0
  264. package/src/ui/lib/picked.ts +18 -0
  265. package/src/ui/lib/player-store.ts +38 -0
  266. package/src/ui/lib/player.ts +139 -0
  267. package/src/ui/lib/portal.ts +12 -0
  268. package/src/ui/lib/read.tsx +269 -0
  269. package/src/ui/lib/region.tsx +49 -0
  270. package/src/ui/lib/reorder.ts +154 -0
  271. package/src/ui/lib/rest.ts +16 -0
  272. package/src/ui/lib/saved.ts +29 -0
  273. package/src/ui/lib/scramble.tsx +147 -0
  274. package/src/ui/lib/scrolls.ts +70 -0
  275. package/src/ui/lib/style.ts +6 -0
  276. package/src/ui/lib/swap.tsx +107 -0
  277. package/src/ui/lib/toast.ts +39 -0
  278. package/src/ui/lib/walk-classes.ts +16 -0
  279. package/src/ui/lib/window.tsx +376 -0
  280. package/src/ui/worker.d.ts +4 -0
@@ -0,0 +1,658 @@
1
+ import { Field } from "@base-ui/react/field";
2
+ import { cn } from "@slotform/ui-core/cn";
3
+ import type {
4
+ ChangeKind,
5
+ FieldBinding,
6
+ FieldControl,
7
+ Run,
8
+ Runs,
9
+ } from "@slotform/ui-core/descriptors";
10
+ import { markedRuns } from "@slotform/ui-core/form";
11
+ import { type Draft, useFieldDraft } from "@slotform/ui-core/react/acts";
12
+ import { FieldOwned } from "@slotform/ui-core/react/field";
13
+ import { useWords } from "@slotform/ui-core/react/words";
14
+ import type { Datum } from "@slotform/ui-core/read";
15
+ import { partRuns, partText } from "@slotform/ui-core/runs";
16
+ import {
17
+ DEFINITION_BOX,
18
+ DEFINITION_BOX_AREA,
19
+ DEFINITION_LABEL,
20
+ DEFINITION_LINE,
21
+ DEFINITION_NAME,
22
+ DEFINITION_NAME_AREA,
23
+ DEFINITION_UNDER,
24
+ DEFINITION_VALUE,
25
+ FIELD_ALONE,
26
+ FIELD_ALONE_LINE,
27
+ FIELD_ALONE_LINE_AREA,
28
+ FIELD_ALONE_ROW,
29
+ FIELD_ALONE_ROW_AREA,
30
+ FIELD_ALONE_UNDER,
31
+ FIELD_ERROR_LINE,
32
+ FIELD_OPTIONAL,
33
+ FIELD_OPTIONAL_BOX,
34
+ FIELD_OPTIONAL_LABEL,
35
+ FIELD_OPTIONAL_LINE,
36
+ FIELD_OPTIONAL_NAME,
37
+ FIELD_SPLIT,
38
+ FIELD_SPLIT_FREE,
39
+ FIELD_SPLIT_TEXT,
40
+ FIELD_SPLIT_VALUE,
41
+ FLOW_IN,
42
+ ROW_END,
43
+ row,
44
+ text,
45
+ } from "@slotform/ui-core/variants";
46
+ import {
47
+ type FocusEvent,
48
+ type ReactNode,
49
+ useEffect,
50
+ useId,
51
+ useMemo,
52
+ useRef,
53
+ } from "react";
54
+ import { ChangeMark } from "../../atoms/status/change.tsx";
55
+ import type { Closed } from "../../lib/closed.ts";
56
+ import { RunText } from "../../lib/code.tsx";
57
+ import { type FieldedKey, GroupName } from "../../lib/field.ts";
58
+ import { focusFirst } from "../../lib/focus.ts";
59
+ import { InputBase } from "../input/base.tsx";
60
+ import type { ProseProps, TextInputProps } from "../input/index.tsx";
61
+ import { ProseBase } from "../input/prose.tsx";
62
+ import { PickerBase } from "../picker/base.tsx";
63
+ import type {
64
+ PickerListProps,
65
+ PickerMenuProps,
66
+ PickerSegmentsProps,
67
+ } from "../picker/index.tsx";
68
+ import { PickerListBase } from "../picker/list.tsx";
69
+ import { SegmentsBase } from "../picker/segments.tsx";
70
+ import { ASIDE, ASIDE_LABEL, ASIDE_LINE, STACKED_BOX } from "../row/index.tsx";
71
+ import { SliderBase } from "../slider/base.tsx";
72
+ import type { SliderProps } from "../slider/index.tsx";
73
+ import { SwitchBase } from "../switch/base.tsx";
74
+ import type { SwitchProps } from "../switch/index.tsx";
75
+
76
+ // A field stands its value under its label as a definition row does: docs/architecture/ui-core/layout.md, "Definition rows".
77
+ const STACKED_OPTIONAL_NAME = "definitions-stacked:pt-0";
78
+ const STACKED_NAME_AREA = "definitions-stacked:mt-0";
79
+ const STACKED_SPLIT =
80
+ "definitions-stacked:flex-col definitions-stacked:items-stretch";
81
+ const STACKED_SPLIT_VALUE = "definitions-stacked:w-auto";
82
+ const STACKED_SPLIT_FREE = "definitions-stacked:max-w-full";
83
+ const STACKED_ALONE_ROW =
84
+ "[.rows-host>&]:definitions-stacked:flex [.rows-host>&]:definitions-stacked:flex-col [.rows-host>&]:definitions-stacked:items-stretch";
85
+ const STACKED_ALONE_ROW_AREA =
86
+ "[.rows-host>&]:definitions-stacked:items-stretch";
87
+ const STACKED_ALONE_LINE_AREA = "[.rows-host>*>&]:definitions-stacked:mt-0";
88
+ const STACKED_ALONE_UNDER = "[.rows-host>*>&]:definitions-stacked:col-start-1";
89
+ // The value line: the change mark, the control and the end group, centred on the line.
90
+ const VALUE_LINE = "flex items-center min-w-0";
91
+ // The end group: on the first line's box at the line's end; a control taller
92
+ // than the line overflows it centred.
93
+ const END_GROUP = "flex shrink-0 items-center ms-auto h-line-body";
94
+ const DISABLED = "text-ink-disabled";
95
+ // The field is a definition row of the form's grid: the label in the first
96
+ // column, wrapping inside it, the value line in the second (the change mark,
97
+ // then the control filling the line, or a toggle at its end), the description
98
+ // or the error under the control.
99
+ const LABEL = "wrap-normal";
100
+ // A toggle placed alone stands at the end of its name's line.
101
+ const NAME_GROWS = "grow";
102
+ // A toggle's row on touch and in a narrow Pane keeps the definition row's two
103
+ // columns (a grid, as it is wide) so its name and the toggle share one line, its
104
+ // description or error under both across the columns; a flex row of the name, the
105
+ // toggle and a description on a line of its own would stand the toggle on the
106
+ // first line while the row's centre is the whole box's.
107
+ const TOGGLE_GRID =
108
+ "touch:grid touch:grid-cols-subgrid definitions-stacked:grid definitions-stacked:grid-cols-subgrid";
109
+ const TOGGLE_UNDER =
110
+ "touch:col-start-1 touch:col-span-2 definitions-stacked:col-start-1 definitions-stacked:col-span-2";
111
+ interface FormFieldBase extends Closed {
112
+ /** Where the field stands in a change set: its mark ahead of the field, on its label's line. */
113
+ change?: ChangeKind;
114
+ /** The control's name, drawn over it (beside a switch) (a short phrase; wraps). */
115
+ label: string;
116
+ /** Under the control; disabled, it is the reason (a sentence; wraps). */
117
+ description?: string;
118
+ /** The field may be left empty: the word `optional` stands under its label, in the meta ink. */
119
+ optional?: boolean;
120
+ /** The field commits itself and stands as a row of two groups: its label over its description, and its control at its own measure beside them (a toggle at its own width), so the row is as tall as its two lines and a short value does not fill it. A text area, a slider and a group of options keep their form; on touch the control stands under its text. */
121
+ split?: boolean;
122
+ /** The control takes no input: the label in the disabled ink, the control its disabled form. */
123
+ disabled?: boolean;
124
+ }
125
+
126
+ // A pick's props less what the field supplies (its label, description,
127
+ // optional word and error, and the fit a descriptor names), each of its forms
128
+ // keeping its own value and handler.
129
+ type PickerLess<P, K extends string = FieldedKey> = P extends unknown
130
+ ? Omit<P, K>
131
+ : never;
132
+
133
+ // The control descriptors, each the component's own props less what the field
134
+ // supplies (its label, description, optional word and error). Exactly one is
135
+ // set, or `children` draws any other control.
136
+ interface Controls<S extends string | null, O extends string, T> {
137
+ input: TextInputProps;
138
+ textArea: ProseProps;
139
+ picker: PickerLess<PickerMenuProps<S>>;
140
+ switch: Omit<SwitchProps, FieldedKey>;
141
+ slider: Omit<SliderProps, FieldedKey>;
142
+ options: PickerLess<PickerListProps<O, T>, FieldedKey | "fit" | "headed">;
143
+ segments: PickerLess<PickerSegmentsProps, FieldedKey | "fit">;
144
+ }
145
+ type ControlKind = keyof Controls<string, string, unknown>;
146
+ type Never<C> = { [K in keyof C]?: never };
147
+ type OneOf<C> = {
148
+ [K in keyof C]: Pick<C, K> & Never<Omit<C, K>>;
149
+ }[keyof C];
150
+
151
+ /** One control with its label, its description and its error. The control is the one descriptor set (`input`, `textArea`, `picker`, `switch`, `slider`, `options`, `segments`: the component's own props, less the label the field supplies), which the field draws in its value line (a switch at its end); or any other control as `children`. Unbound, the consumer gives the error and the control; bound, the form's field gives both, and the control is a function of the field's value: `{(control) => <Input {...control} />}`. */
152
+ type FormFieldProps<
153
+ V = unknown,
154
+ S extends string | null = string,
155
+ O extends string = string,
156
+ T = unknown,
157
+ > = FormFieldBase &
158
+ (
159
+ | (OneOf<Controls<S, O, T>> & {
160
+ /** Unbound. */
161
+ field?: never;
162
+ /** The message that takes the description's place, the control drawn in error (a sentence; wraps): words, or runs whose `{ code }` stands boxed in the mono. */
163
+ error?: Run | Runs;
164
+ children?: never;
165
+ })
166
+ | (Never<Controls<S, O, T>> &
167
+ (
168
+ | {
169
+ /** Unbound. */
170
+ field?: never;
171
+ /** The message that takes the description's place, the control drawn in error (a sentence; wraps): words, or runs whose `{ code }` stands boxed in the mono. */
172
+ error?: Run | Runs;
173
+ /** Any other control. */
174
+ children?: ReactNode;
175
+ }
176
+ | {
177
+ /** The form's field: its value, its change handler and its error. */
178
+ field: FieldBinding<V>;
179
+ error?: never;
180
+ /** The control, handed the field's value and change handler. */
181
+ children: (control: FieldControl<V>) => ReactNode;
182
+ }
183
+ ))
184
+ );
185
+
186
+ // The props a field body reads, its descriptors at their widest.
187
+ type Body = FormFieldBase & {
188
+ field?: FieldBinding<unknown>;
189
+ error?: Run | Runs;
190
+ children?: ReactNode | ((control: FieldControl<unknown>) => ReactNode);
191
+ /** A control placed alone: no form's label column to share, so the name stands over the control (`FIELD_ALONE`). */
192
+ alone?: boolean;
193
+ /** A derived form's: set afresh when a refusal names this field first, its control then takes focus. */
194
+ seek?: object;
195
+ /** A derived form's: focus left the field. */
196
+ onLeave?: () => void;
197
+ } & Partial<Controls<string | null, string, unknown>>;
198
+
199
+ // What a descriptor's control is drawn over: the draft the field holds and
200
+ // the field's label, disabled state and error.
201
+ interface Held {
202
+ draft: Draft<unknown>;
203
+ label: string;
204
+ disabled: boolean | undefined;
205
+ error: string | undefined;
206
+ }
207
+
208
+ // Each descriptor's control: the value it saves, which the field holds the
209
+ // draft of; how it draws over that draft; and whether a `split` field stands
210
+ // it beside its text (a text area, a slider and a group of options keep their
211
+ // form). The field holds one draft for whichever control its props name, so
212
+ // the draft is `unknown` and each control reads it as its own value; a pick's
213
+ // `onChange` is read at its widest, as `FormField` reads the descriptors.
214
+ const CONTROLS: Record<
215
+ ControlKind,
216
+ {
217
+ saved: (props: Body) => Datum<unknown>;
218
+ draw: (props: Body, held: Held) => ReactNode;
219
+ splits: boolean;
220
+ }
221
+ > = {
222
+ input: {
223
+ saved: ({ input }) => input?.value,
224
+ draw: ({ input }, { draft }) =>
225
+ input && <InputBase {...input} draft={draft as Draft<string>} />,
226
+ splits: true,
227
+ },
228
+ textArea: {
229
+ saved: ({ textArea }) => textArea?.value,
230
+ draw: ({ textArea }, { draft }) =>
231
+ textArea && <ProseBase {...textArea} draft={draft as Draft<string>} />,
232
+ splits: false,
233
+ },
234
+ picker: {
235
+ saved: ({ picker }) => picker?.value,
236
+ draw: ({ picker }, { draft, label, disabled, error }) =>
237
+ picker && (
238
+ <PickerBase<string | null>
239
+ {...picker}
240
+ label={label}
241
+ form={{ invalid: Boolean(error), disabled: disabled === true }}
242
+ draft={
243
+ draft as Draft<
244
+ string | null | readonly (string | null)[] | undefined
245
+ >
246
+ }
247
+ onChange={
248
+ picker.onChange as (
249
+ next: string | null | (string | null)[],
250
+ ) => unknown
251
+ }
252
+ />
253
+ ),
254
+ splits: true,
255
+ },
256
+ switch: {
257
+ saved: (props) => props.switch?.checked,
258
+ draw: (props, { draft, label }) =>
259
+ props.switch && (
260
+ <SwitchBase
261
+ {...props.switch}
262
+ draft={draft as Draft<boolean>}
263
+ label={label}
264
+ />
265
+ ),
266
+ splits: true,
267
+ },
268
+ slider: {
269
+ saved: ({ slider }) => slider?.value,
270
+ draw: ({ slider }, { draft, label }) =>
271
+ slider && (
272
+ <SliderBase {...slider} draft={draft as Draft<number>} label={label} />
273
+ ),
274
+ splits: false,
275
+ },
276
+ options: {
277
+ saved: ({ options }) => options?.value,
278
+ draw: ({ options }, { draft, label }) =>
279
+ options && (
280
+ <PickerListBase
281
+ {...options}
282
+ label={label}
283
+ draft={draft as Draft<string | null | readonly string[]>}
284
+ onChange={options.onChange as (next: string | string[]) => unknown}
285
+ />
286
+ ),
287
+ splits: false,
288
+ },
289
+ segments: {
290
+ saved: ({ segments }) => segments?.value,
291
+ draw: ({ segments }, { draft, label }) =>
292
+ segments && (
293
+ <SegmentsBase
294
+ {...segments}
295
+ draft={draft as Draft<string>}
296
+ label={label}
297
+ />
298
+ ),
299
+ splits: false,
300
+ },
301
+ };
302
+ // The order is the precedence: the first kind whose descriptor is set draws the
303
+ // field. `satisfies` rejects an extra kind; `Listed` on `KINDS` rejects a missing one.
304
+ const PRECEDENCE = [
305
+ "input",
306
+ "textArea",
307
+ "picker",
308
+ "switch",
309
+ "slider",
310
+ "options",
311
+ "segments",
312
+ ] as const satisfies readonly ControlKind[];
313
+ type Listed<L extends readonly ControlKind[]> = [
314
+ Exclude<ControlKind, L[number]>,
315
+ ] extends [never]
316
+ ? L
317
+ : never;
318
+ const KINDS: Listed<typeof PRECEDENCE> = PRECEDENCE;
319
+
320
+ // The field's form follows which descriptor is set: a switch at the value
321
+ // line's end, any other filling it; a slider's head is its own
322
+ // label; a group of controls is named by the label and holds controls named
323
+ // on their own.
324
+ type Form = "field" | ControlKind;
325
+
326
+ // The control a field draws: the descriptor's control over the draft the field
327
+ // holds, or its children, bound drawn from the field's value.
328
+ function controlOf(
329
+ props: Body,
330
+ kind: ControlKind | undefined,
331
+ held: Held,
332
+ ): ReactNode {
333
+ if (kind !== undefined) return CONTROLS[kind].draw(props, held);
334
+ // The field names what it holds: a control among its children draws no
335
+ // field of its own.
336
+ const { field, children } = props;
337
+ if (typeof children !== "function")
338
+ return <FieldOwned value>{children}</FieldOwned>;
339
+ return field ? (
340
+ <FieldOwned value>
341
+ {children({
342
+ value: field.value,
343
+ onChange: field.onChange,
344
+ onCommit: field.onCommit,
345
+ })}
346
+ </FieldOwned>
347
+ ) : null;
348
+ }
349
+
350
+ // The field itself, one definition row: the label in the label column, the
351
+ // control in the value line, the description (meta) or the error under it;
352
+ // placed alone (`alone`), the label over the control. Base UI's field wires
353
+ // the label, the description, the error, the validity and the disabled state
354
+ // into the control. Outside the package's exports: a control placed alone
355
+ // draws itself through it.
356
+ export function FieldBody(props: Body) {
357
+ const { label, description, optional, disabled, change, alone, split } =
358
+ props;
359
+ const words = useWords();
360
+ // The field hosts its control's save: a save the server refused stands in
361
+ // the error line until the control's next change.
362
+ const kind = KINDS.find((each) => props[each]);
363
+ const { draft, refused } = useFieldDraft(
364
+ kind === undefined ? undefined : CONTROLS[kind].saved(props),
365
+ );
366
+ // The error as runs, a refused save's own message too (the server's
367
+ // backticks box a machine name), and its words, which key its line and
368
+ // say whether it stands. The error is a sentence read whole, so a code run
369
+ // in it wraps inside its box, never cut at its end (`whole`).
370
+ const given =
371
+ refused === undefined
372
+ ? props.field
373
+ ? props.field.error
374
+ : props.error
375
+ : markedRuns(refused);
376
+ const worded = given === undefined ? "" : partText(given);
377
+ const error = worded === "" ? undefined : worded;
378
+ const errorLine =
379
+ given === undefined ? null : <RunText runs={partRuns(given)} whole />;
380
+ const control = controlOf(props, kind, { draft, label, disabled, error });
381
+ const form: Form = kind ?? "field";
382
+ const root = useRef<HTMLDivElement>(null);
383
+ // A refusal that names this field first hands its control focus, which
384
+ // scrolls it into view: the line under it may stand below the fold.
385
+ const { seek, onLeave } = props;
386
+ useEffect(() => {
387
+ if (seek) focusFirst(root.current);
388
+ }, [seek]);
389
+ // Focus leaving the field, not moving within it (a pick's trigger to its
390
+ // list), is the field left.
391
+ const onBlur =
392
+ onLeave &&
393
+ ((event: FocusEvent<HTMLDivElement>) => {
394
+ const { relatedTarget } = event;
395
+ if (
396
+ !(
397
+ relatedTarget instanceof Node &&
398
+ event.currentTarget.contains(relatedTarget)
399
+ )
400
+ )
401
+ onLeave();
402
+ });
403
+ const labelId = useId();
404
+ // What a group of controls is named by.
405
+ const groupName = useMemo(() => ({ labelledBy: labelId }), [labelId]);
406
+ // A toggle stands at the value line's end; any other control fills it.
407
+ const atEnd = form === "switch";
408
+ const area = form === "textArea";
409
+ // An optional field on one line: its word hangs under a name as high as the
410
+ // control (a text area's name hangs from its top, a slider names itself).
411
+ const splits =
412
+ split === true && !alone && (kind === undefined || CONTROLS[kind].splits);
413
+ const stacked =
414
+ optional === true && !area && form !== "slider" && !alone && !splits;
415
+ // The name on the first line, the word `optional` under it.
416
+ const labelled = optional ? (
417
+ <span>
418
+ {label}
419
+ <span className={cn(text({ role: "meta" }), FIELD_OPTIONAL)}>
420
+ {words.optional}
421
+ </span>
422
+ </span>
423
+ ) : (
424
+ label
425
+ );
426
+ const name = cn(
427
+ text({ role: "body" }),
428
+ DEFINITION_NAME,
429
+ area && !alone && cn(DEFINITION_NAME_AREA, STACKED_NAME_AREA),
430
+ alone && atEnd && NAME_GROWS,
431
+ LABEL,
432
+ stacked && cn(FIELD_OPTIONAL_NAME, STACKED_OPTIONAL_NAME),
433
+ disabled && DISABLED,
434
+ );
435
+ const named = (
436
+ <Field.Label
437
+ // A trigger is a button: a label element would press it.
438
+ nativeLabel={form !== "picker"}
439
+ render={form === "picker" ? <div /> : undefined}
440
+ className={name}
441
+ >
442
+ {labelled}
443
+ </Field.Label>
444
+ );
445
+ // Under the control: in the value column of a definition row, or, placed
446
+ // alone, under the control (and in a run of rows, in the value column).
447
+ const under = alone
448
+ ? cn(FIELD_ALONE_UNDER, STACKED_ALONE_UNDER)
449
+ : splits
450
+ ? undefined
451
+ : cn(DEFINITION_UNDER, atEnd && TOGGLE_UNDER);
452
+ const said = error ? (
453
+ <Field.Error
454
+ key={error}
455
+ match
456
+ className={cn(FIELD_ERROR_LINE, FLOW_IN, under)}
457
+ >
458
+ {errorLine}
459
+ </Field.Error>
460
+ ) : description ? (
461
+ <Field.Description className={cn(text({ role: "meta" }), under)}>
462
+ {description}
463
+ </Field.Description>
464
+ ) : null;
465
+ const mark = change ? <ChangeMark kind={change} /> : null;
466
+ // A group takes no field context (its label names the group, never the
467
+ // controls inside), so its line under is its own.
468
+ const groupLine = (place?: string) =>
469
+ error || description ? (
470
+ <p
471
+ key={error}
472
+ className={cn(
473
+ error ? cn(FIELD_ERROR_LINE, FLOW_IN) : text({ role: "meta" }),
474
+ place,
475
+ )}
476
+ >
477
+ {error ? errorLine : description}
478
+ </p>
479
+ ) : null;
480
+ if (alone) {
481
+ const group = form === "options" || form === "segments";
482
+ // A field that fills a line takes the label column: docs/architecture/ui-core/layout.md, "Rows grid".
483
+ const lined = !atEnd && !group && form !== "slider";
484
+ const head =
485
+ form === "slider" ? (
486
+ mark
487
+ ) : (
488
+ <div
489
+ className={cn(
490
+ FIELD_ALONE_LINE,
491
+ lined && area && cn(FIELD_ALONE_LINE_AREA, STACKED_ALONE_LINE_AREA),
492
+ )}
493
+ >
494
+ {mark}
495
+ {group ? (
496
+ <p id={labelId} className={name}>
497
+ {labelled}
498
+ </p>
499
+ ) : (
500
+ named
501
+ )}
502
+ {atEnd ? (
503
+ <span className={cn(ROW_END, END_GROUP)}>{control}</span>
504
+ ) : null}
505
+ </div>
506
+ );
507
+ const body = group ? (
508
+ <GroupName value={groupName}>{control}</GroupName>
509
+ ) : atEnd ? null : (
510
+ control
511
+ );
512
+ if (group)
513
+ return (
514
+ <div ref={root} className={FIELD_ALONE}>
515
+ {head}
516
+ {body}
517
+ {groupLine()}
518
+ </div>
519
+ );
520
+ return (
521
+ <Field.Root
522
+ onBlur={onBlur}
523
+ ref={root}
524
+ invalid={Boolean(error)}
525
+ disabled={disabled}
526
+ className={cn(
527
+ FIELD_ALONE,
528
+ lined && cn(FIELD_ALONE_ROW, STACKED_ALONE_ROW),
529
+ lined && area && cn(FIELD_ALONE_ROW_AREA, STACKED_ALONE_ROW_AREA),
530
+ )}
531
+ >
532
+ {head}
533
+ {body}
534
+ {said}
535
+ </Field.Root>
536
+ );
537
+ }
538
+ if (form === "options" || form === "segments") {
539
+ const title = (
540
+ <p id={labelId} className={name}>
541
+ {labelled}
542
+ </p>
543
+ );
544
+ return (
545
+ <div
546
+ ref={root}
547
+ className={cn(
548
+ row({ state: "rest" }),
549
+ DEFINITION_BOX,
550
+ STACKED_BOX,
551
+ stacked && FIELD_OPTIONAL_BOX,
552
+ )}
553
+ >
554
+ <span className={DEFINITION_LABEL}>{title}</span>
555
+ <div
556
+ className={cn(
557
+ DEFINITION_LINE,
558
+ VALUE_LINE,
559
+ stacked && FIELD_OPTIONAL_LINE,
560
+ )}
561
+ >
562
+ {mark}
563
+ <div className={DEFINITION_VALUE}>
564
+ <GroupName value={groupName}>{control}</GroupName>
565
+ </div>
566
+ </div>
567
+ {groupLine(DEFINITION_UNDER)}
568
+ </div>
569
+ );
570
+ }
571
+ if (splits)
572
+ return (
573
+ <Field.Root
574
+ onBlur={onBlur}
575
+ ref={root}
576
+ invalid={Boolean(error)}
577
+ disabled={disabled}
578
+ className={cn(row({ state: "rest" }), FIELD_SPLIT, STACKED_SPLIT)}
579
+ >
580
+ <div className={FIELD_SPLIT_TEXT}>
581
+ <div className={FIELD_ALONE_LINE}>
582
+ {mark}
583
+ {named}
584
+ </div>
585
+ {said}
586
+ </div>
587
+ <div
588
+ className={
589
+ atEnd
590
+ ? cn(ROW_END, END_GROUP)
591
+ : form === "field"
592
+ ? cn(FIELD_SPLIT_FREE, STACKED_SPLIT_FREE)
593
+ : cn(FIELD_SPLIT_VALUE, STACKED_SPLIT_VALUE)
594
+ }
595
+ >
596
+ {control}
597
+ </div>
598
+ </Field.Root>
599
+ );
600
+ return (
601
+ <Field.Root
602
+ onBlur={onBlur}
603
+ ref={root}
604
+ invalid={Boolean(error)}
605
+ disabled={disabled}
606
+ className={cn(
607
+ row({ state: "rest" }),
608
+ DEFINITION_BOX,
609
+ STACKED_BOX,
610
+ area && DEFINITION_BOX_AREA,
611
+ stacked && FIELD_OPTIONAL_BOX,
612
+ // A toggle has no value to stand under its name: on touch and in a
613
+ // narrow Pane the name and the toggle keep one line, as a row's label
614
+ // and its end group do (docs/architecture/ui-core/layout.md, "Definition rows").
615
+ atEnd && cn(ASIDE, TOGGLE_GRID),
616
+ )}
617
+ >
618
+ {/* A slider's head is its own label. */}
619
+ <span
620
+ className={cn(
621
+ DEFINITION_LABEL,
622
+ atEnd && ASIDE_LABEL,
623
+ stacked && said && FIELD_OPTIONAL_LABEL,
624
+ )}
625
+ >
626
+ {form === "slider" ? null : named}
627
+ </span>
628
+ <div
629
+ className={cn(
630
+ DEFINITION_LINE,
631
+ VALUE_LINE,
632
+ stacked && FIELD_OPTIONAL_LINE,
633
+ atEnd && ASIDE_LINE,
634
+ )}
635
+ >
636
+ {mark}
637
+ {atEnd ? (
638
+ <span className={cn(ROW_END, END_GROUP)}>{control}</span>
639
+ ) : (
640
+ <div className={DEFINITION_VALUE}>{control}</div>
641
+ )}
642
+ </div>
643
+ {said}
644
+ </Field.Root>
645
+ );
646
+ }
647
+
648
+ /** One row of its form: the label (the body role) in the label column, as wide as the form's widest, the control filling the value line (a switch at its end) and the description (meta) or the error under the control; on touch, and in a Pane too narrow for a label and a value side by side (`definitionsOneRow`), the label stands over the control, but for a toggle, which keeps its label's line. Base UI's field wires the label, the description, the error, the validity and the disabled state into the control. A `change` draws the change mark at the value line's start. The label and the description are constants and always stand; a control given a selection paints itself, inert, until its read lands. The field hosts the save of its descriptor's control: the viewer's value holds while the save pends, and a refusal stands in the field's error line until the control's next change. */
649
+ export function FormField<
650
+ V,
651
+ S extends string | null = string,
652
+ O extends string = string,
653
+ T = unknown,
654
+ >(props: FormFieldProps<V, S, O, T>) {
655
+ // The descriptors are read at their widest: a `Picker` over `S` is one over
656
+ // `string | null` to the field that draws it.
657
+ return <FieldBody {...(props as Body)} />;
658
+ }