@slotform/react-ui 0.0.0-stage → 0.1.1

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,280 @@
1
+ import { cn } from "@slotform/ui-core/cn";
2
+ import { groupKey, type ProcedureCall } from "@slotform/ui-core/form";
3
+ import type { Acting } from "@slotform/ui-core/react/acts";
4
+ import { useArrivals } from "@slotform/ui-core/react/arrive";
5
+ import type { FormModel, StepModel } from "@slotform/ui-core/react/form";
6
+ import {
7
+ type Frame,
8
+ submitOf,
9
+ useFrame,
10
+ usePainted,
11
+ } from "@slotform/ui-core/react/read";
12
+ import {
13
+ type Touched,
14
+ TouchedContext,
15
+ useEditedByValue,
16
+ } from "@slotform/ui-core/react/touched";
17
+ import { useWords } from "@slotform/ui-core/react/words";
18
+ import type { Selection } from "@slotform/ui-core/read";
19
+ import {
20
+ BLOCK_IN,
21
+ FORM_FIELD_SUMMARY_GLYPH,
22
+ FORM_GROUP,
23
+ LIST_BAND,
24
+ row,
25
+ SHEET_PARTS,
26
+ text,
27
+ textStrong,
28
+ } from "@slotform/ui-core/variants";
29
+ import type { ReactNode } from "react";
30
+ import { useId, useState } from "react";
31
+ import { Icon } from "../../atoms/icon/index.tsx";
32
+ import { DIVIDER } from "../../atoms/section/card.tsx";
33
+ import type { Act } from "../../lib/act.ts";
34
+ import type { Closed } from "../../lib/closed.ts";
35
+ import type { Empty } from "../../lib/empty.tsx";
36
+ import { useLeaveGuard } from "../../lib/leave.ts";
37
+ import { BusyMark, FrameBody, FrameLine, stillOf } from "../../lib/read.tsx";
38
+ import { ActionBarBase } from "../action-bar/base.tsx";
39
+ import type { ActionBarProps } from "../action-bar/index.tsx";
40
+ import { Button } from "../button/index.tsx";
41
+ import { Text } from "../text/index.tsx";
42
+
43
+ // The form is its rows over its foot: docs/architecture/ui-core/layout.md, "Rows grid".
44
+ const BAND = "flex flex-col";
45
+ // A sheet's parts after the fields stand in a column.
46
+ const AFTER = "flex flex-col";
47
+ // The legend is a line, the busy mark after its title.
48
+ const LEGEND = "flex items-center gap-gap";
49
+ // A folded step's row: the check, the title, the answers cut at the line's
50
+ // end, the Edit act.
51
+ const SUMMARY = "flex items-center min-w-0";
52
+ const SUMMARY_GLYPH = "flex shrink-0";
53
+ const SUMMARY_TITLE = "min-w-0 truncate";
54
+ const SUMMARY_ANSWERS = "min-w-0 grow truncate";
55
+
56
+ /** One group of fields a `Form` draws as a run of its rows under a band. */
57
+ interface FormGroup {
58
+ /** The group's name, on its band (a short phrase; wraps); without it the group is a run with no band, for fields that lead or close the form among titled groups. */
59
+ title?: string;
60
+ /** Under the title on the band (a sentence; wraps). */
61
+ description?: string;
62
+ /** The group's `FormField`s, its rows. */
63
+ fields: ReactNode;
64
+ /** What the group's fields hold, read once for the group's frame: its leaves paint while it waits, and its failure and a missing record stand in the fields' place. */
65
+ read?: Selection<unknown>;
66
+ /** The fields' sentence when the group's `read` is empty. */
67
+ empty?: Empty;
68
+ /** Where a form that asks one step at a time stands at this group: folded to its summary row, open, or not reached and not drawn. */
69
+ step?: StepModel;
70
+ }
71
+
72
+ // A derived form's bar: its acts, and what a press of its blocked submit
73
+ // tells the form, as `useFormModel` gives it.
74
+ type FormBar = ActionBarProps &
75
+ Pick<NonNullable<FormModel<ProcedureCall, Act>["bar"]>, "onBlocked">;
76
+
77
+ interface FormBase extends Closed {
78
+ /** The acts that close the form, its last row under a hairline; the bar's filled act submits the form. */
79
+ bar?: FormBar;
80
+ /** `field`: each field commits itself, so the form draws no bar and, standing edited, asks nothing when its page is left. */
81
+ commit?: "submit" | "field";
82
+ /** What the form's fields hold, read once for the form's frame: the fields' leaves paint while it waits, the filled act with them, inert; its failure and a missing record stand in the fields' place, the filled act blocked with the failed sentence. Each group has its own, which the bar never reads. */
83
+ read?: Selection<unknown>;
84
+ /** The fields' sentence when the `read`'s selection is empty. */
85
+ empty?: Empty;
86
+ /** What follows the fields at the card inset (a live preview of what the form would send), the bar after it. */
87
+ after?: ReactNode;
88
+ /** A field holds a value other than its first: the form's leave stands edited. */
89
+ edited: boolean;
90
+ }
91
+
92
+ /** The structure every form draws, which the derived `Form`, a `Sheet`'s form and a `Gate`'s form (each over a procedure) fill. Its structure is its props: `children`, a flat run of `FormField`s, or `groups`, each a run of rows under a band; never both. A form among a page's other sections is `Section > Form`, so every section's head-to-body gap stays the pair step. */
93
+ export type FormFrameProps = FormBase &
94
+ (
95
+ | {
96
+ /** A flat run of `FormField`s, the form's rows. */
97
+ children?: ReactNode;
98
+ groups?: never;
99
+ }
100
+ | {
101
+ children?: never;
102
+ /** Groups of fields, each a run of the form's rows under its band (the title over the description), a hairline between the runs. */
103
+ groups: readonly FormGroup[];
104
+ }
105
+ );
106
+
107
+ // One group: a run of the form's rows (a subgrid of the form's columns, so its
108
+ // labels align with the rest), its legend a band, then its fields, which are the group's own frame when it holds a `read`. A block of
109
+ // the form, fading in if it came on its own once the form was drawn (held
110
+ // from the first render, so a later commit does not cut it short).
111
+ function GroupBox(props: { group: FormGroup; arrived: boolean }) {
112
+ const { group } = props;
113
+ const frame = useFrame(group.read);
114
+ const [fades] = useState(props.arrived);
115
+ const id = useId();
116
+ return (
117
+ // biome-ignore lint/a11y/useSemanticElements: a fieldset lays its grid on an anonymous box, which cannot subgrid the form's columns
118
+ <div
119
+ role="group"
120
+ aria-labelledby={group.title ? id : undefined}
121
+ aria-busy={(frame.holds && frame.shape === "waiting") || undefined}
122
+ data-still={stillOf(frame)}
123
+ className={cn(FORM_GROUP, DIVIDER, fades && BLOCK_IN)}
124
+ >
125
+ {group.title || group.description ? (
126
+ <div className={cn(LIST_BAND, BAND)}>
127
+ {group.title ? (
128
+ <span id={id} className={cn(text({ role: "heading" }), LEGEND)}>
129
+ {group.title}
130
+ <BusyMark frame={frame} />
131
+ </span>
132
+ ) : null}
133
+ {group.description ? (
134
+ <Text kind="meta">{group.description}</Text>
135
+ ) : null}
136
+ </div>
137
+ ) : null}
138
+ <FrameLine frame={frame} flow />
139
+ <FrameBody frame={frame} fit="part" empty={group.empty}>
140
+ {group.fields}
141
+ </FrameBody>
142
+ </div>
143
+ );
144
+ }
145
+
146
+ // A folded step: its check, its title, its answers a middle dot apart, and the
147
+ // Edit act that unfolds it.
148
+ function StepSummary(props: { step: StepModel }) {
149
+ const { step } = props;
150
+ const words = useWords();
151
+ return (
152
+ <div className={cn(row({ state: "rest" }), SUMMARY)}>
153
+ <span className={cn(FORM_FIELD_SUMMARY_GLYPH, SUMMARY_GLYPH)}>
154
+ <Icon name="Check" />
155
+ </span>
156
+ <p
157
+ className={cn(
158
+ text({ role: "body" }),
159
+ textStrong({ role: "body" }),
160
+ SUMMARY_TITLE,
161
+ )}
162
+ >
163
+ {step.title}
164
+ </p>
165
+ <p className={cn(text({ role: "meta" }), SUMMARY_ANSWERS)}>
166
+ {step.summary}
167
+ </p>
168
+ <Button
169
+ glyph
170
+ icon="Pencil"
171
+ label={`${words.edit} ${step.title}`}
172
+ onAct={step.edit}
173
+ />
174
+ </div>
175
+ );
176
+ }
177
+
178
+ // A group as the form draws it: a step not reached draws nothing, a folded one
179
+ // its summary row.
180
+ function drawnGroup(
181
+ group: FormGroup,
182
+ index: number,
183
+ arrived: ReadonlySet<string>,
184
+ ) {
185
+ const key = groupKey(group, index);
186
+ if (group.step?.state === "later") return null;
187
+ if (group.step?.state === "done")
188
+ return <StepSummary key={key} step={group.step} />;
189
+ return <GroupBox key={key} group={group} arrived={arrived.has(key)} />;
190
+ }
191
+
192
+ /** A form's rows: its fields (`children`, or `groups` each under its band) in the frame of the form's own `read`, then what follows them (`after`) at the card inset. Outside the package's exports: a `Form`, a `Sheet`'s form and a `Gate`'s form stand them in their `FormShell`. */
193
+ export function FormRows({
194
+ children,
195
+ groups,
196
+ empty,
197
+ after,
198
+ frame,
199
+ }: Pick<FormBase, "empty" | "after"> & {
200
+ children?: ReactNode;
201
+ groups?: readonly FormGroup[];
202
+ /** The frame of the form's own `read`. */
203
+ frame: Frame;
204
+ }) {
205
+ // A step the viewer opens lands at once: every group's key, a step not
206
+ // reached included, is the form's from its first draw.
207
+ const arrived = useArrivals(
208
+ groups?.map(groupKey) ?? [],
209
+ frame.shape === "ready",
210
+ );
211
+ return (
212
+ <>
213
+ <div className={cn(FORM_GROUP, DIVIDER)}>
214
+ <FrameLine frame={frame} flow />
215
+ <FrameBody frame={frame} fit="part" empty={empty}>
216
+ {groups
217
+ ? groups.map((group, index) => drawnGroup(group, index, arrived))
218
+ : children}
219
+ </FrameBody>
220
+ </div>
221
+ {after ? (
222
+ <div className={cn(SHEET_PARTS, AFTER, DIVIDER)}>{after}</div>
223
+ ) : null}
224
+ </>
225
+ );
226
+ }
227
+
228
+ /** A form's bar: its acts, the filled one submitting the form. It submits what the form's own read gives, and the `outer` reads': it paints while either waits and stands blocked once the form's has ended. Outside the package's exports. */
229
+ export function useFormBar(
230
+ bar: FormBar | undefined,
231
+ frame: Frame,
232
+ /** The reads the bar paints under besides the form's own (the sheet's read, the ability the form is gated on); constants are no read. */
233
+ outer: readonly unknown[],
234
+ /** The holder of the bar's run, when the form stands in one that holds more than the bar (a sheet's dismissal). */
235
+ acting?: Acting<number>,
236
+ ): ReactNode {
237
+ const words = useWords();
238
+ const { waiting, ended } = submitOf(words, frame.shape);
239
+ const outerWaits = usePainted(outer);
240
+ return bar ? (
241
+ <ActionBarBase
242
+ {...bar}
243
+ acting={acting}
244
+ painted={waiting || outerWaits}
245
+ ended={ended}
246
+ submits
247
+ />
248
+ ) : null;
249
+ }
250
+
251
+ /** The form element every form stands in: it hands its fields the `touch` it edits, asks before its page is left while that stands edited where it `guards` a leave, and says the busy and still state of the form's own read. Outside the package's exports. */
252
+ export function FormShell(props: {
253
+ frame: Frame;
254
+ /** The touched state the fields edit: the form's own, or a sheet's, which the sheet asks when it is closed. */
255
+ touch: Touched;
256
+ /** Leaving the page asks first while the form stands edited. */
257
+ guards: boolean;
258
+ /** A field holds a value other than its first: a value put back un-edits the form. */
259
+ edited: boolean;
260
+ className: string;
261
+ children: ReactNode;
262
+ }) {
263
+ const { frame, touch } = props;
264
+ useLeaveGuard(touch.leave, props.guards);
265
+ useEditedByValue(touch, props.edited);
266
+ return (
267
+ <TouchedContext value={touch}>
268
+ {/* The submit act's click runs its `onAct`; the submit only stays on the page. */}
269
+ <form
270
+ onSubmit={(event) => event.preventDefault()}
271
+ onChange={touch.touch}
272
+ aria-busy={(frame.holds && frame.shape === "waiting") || undefined}
273
+ data-still={stillOf(frame)}
274
+ className={props.className}
275
+ >
276
+ {props.children}
277
+ </form>
278
+ </TouchedContext>
279
+ );
280
+ }
@@ -0,0 +1,269 @@
1
+ import type { Option, PickedFile } from "@slotform/ui-core/descriptors";
2
+ import { heldPick, type ProcedureCall } from "@slotform/ui-core/form";
3
+ import { type FieldModel, useFormModel } from "@slotform/ui-core/react/form";
4
+ import { useFrame } from "@slotform/ui-core/react/read";
5
+ import { useTouchState } from "@slotform/ui-core/react/touched";
6
+ import { type Datum, isSelection } from "@slotform/ui-core/read";
7
+ import type { Act } from "../../lib/act.ts";
8
+ import type { Empty } from "../../lib/empty.tsx";
9
+ import { toast } from "../../lib/toast.ts";
10
+ import { FieldBody } from "../form-field/index.tsx";
11
+ import { Input } from "../input/index.tsx";
12
+ import { type FormFrameProps, useFormBar } from "./base.tsx";
13
+ import type { FormProps } from "./index.tsx";
14
+ import { SavedSecret } from "./saved.tsx";
15
+
16
+ /** What a derived form draws: the structure `FormRows` and `useFormBar` take, the reads its bar paints under besides the form's own (the ability its `can` asks), and `clear`, which drops the viewer's edits and the refusals they drew. */
17
+ interface DerivedFrame {
18
+ frame: FormFrameProps;
19
+ outer: readonly unknown[];
20
+ clear: () => void;
21
+ }
22
+
23
+ /** A derivation over no form (a sheet with none): nothing to draw, and the `clear` a sheet calls as it opens. */
24
+ interface NoFrame {
25
+ frame?: undefined;
26
+ outer?: undefined;
27
+ clear: () => void;
28
+ }
29
+
30
+ /** The derivation of a form over its procedure: its fields, its bar and its read, as the structure a `Form`, a `Gate` or a `Sheet` draws. Without props (a sheet with no form) it draws nothing. `stays`: the form stays on its page after a send (a `Form`, a `Gate`'s), so its fields go back to `values` unless its submit goes `to` a page; a sheet's does not, and the sheet calls `clear` as it opens again. */
31
+ export function useDerivedForm<P extends ProcedureCall>(
32
+ props: FormProps<P>,
33
+ stays: boolean,
34
+ ): DerivedFrame;
35
+ export function useDerivedForm<P extends ProcedureCall>(
36
+ props: FormProps<P> | undefined,
37
+ stays: boolean,
38
+ ): DerivedFrame | NoFrame;
39
+ export function useDerivedForm<P extends ProcedureCall>(
40
+ props: FormProps<P> | undefined,
41
+ stays: boolean,
42
+ ): DerivedFrame | NoFrame {
43
+ const model = useFormModel<P, Act, Empty>(props, stays, { toast });
44
+ if (!props || model.fields === undefined) return { clear: model.clear };
45
+ const byField = model.commit === "field";
46
+ const drawn = (field: FieldModel) => (
47
+ <FieldBody
48
+ key={field.key}
49
+ label={field.spec.label}
50
+ description={field.description}
51
+ error={field.error}
52
+ optional={field.optional}
53
+ change={field.change}
54
+ split={byField}
55
+ disabled={field.disabled}
56
+ seek={field.seek}
57
+ onLeave={field.leave}
58
+ // The body's props take each control at its widest, which a spread of
59
+ // `controlOf`'s union is not checked against member by member.
60
+ {...(controlOf(field) as object)}
61
+ />
62
+ );
63
+ const { bar, commit, read } = model;
64
+ const after = props.after?.(model.sent);
65
+ return {
66
+ outer: model.outer,
67
+ clear: model.clear,
68
+ frame: model.groups
69
+ ? {
70
+ bar,
71
+ commit,
72
+ after,
73
+ read,
74
+ edited: model.edited,
75
+ empty: props.empty,
76
+ groups: model.groups.map((group) => ({
77
+ ...group,
78
+ fields: group.fields.map(drawn),
79
+ })),
80
+ }
81
+ : {
82
+ bar,
83
+ commit,
84
+ after,
85
+ read,
86
+ edited: model.edited,
87
+ empty: props.empty,
88
+ children: model.fields.map(drawn),
89
+ },
90
+ };
91
+ }
92
+
93
+ // The descriptor of the control a field draws: docs/architecture/ui-core/acts.md, "Forms".
94
+ function controlOf(field: FieldModel) {
95
+ const { derived, spec, value, options, set, commit, said, saved } = field;
96
+ const text = (value ?? "") as Datum<string>;
97
+ const onText = (next: string) => set(next);
98
+ const onCommit = commit && ((next: string) => commit(next));
99
+ const done = commit ?? set;
100
+ switch (derived.control) {
101
+ case "switch":
102
+ return {
103
+ switch: {
104
+ checked: (value ?? false) as Datum<boolean>,
105
+ onChange: (next: boolean) => done(next),
106
+ },
107
+ };
108
+ case "prose":
109
+ case "source":
110
+ case "lines":
111
+ case "json":
112
+ return {
113
+ textArea: {
114
+ value: text,
115
+ onChange: onText,
116
+ onCommit,
117
+ source: derived.control === "source" || derived.control === "json",
118
+ },
119
+ };
120
+ case "code":
121
+ return {
122
+ children: (
123
+ <Input
124
+ label={spec.label}
125
+ kind="code"
126
+ length={derived.checks.minLength ?? 0}
127
+ value={(value ?? "") as string}
128
+ onChange={set}
129
+ onComplete={onCommit}
130
+ />
131
+ ),
132
+ };
133
+ case "mono":
134
+ return {
135
+ input: {
136
+ kind: "source" as const,
137
+ value: text,
138
+ onChange: onText,
139
+ onCommit,
140
+ },
141
+ };
142
+ case "number":
143
+ return {
144
+ input: {
145
+ kind: "number" as const,
146
+ value: text,
147
+ onChange: onText,
148
+ onCommit,
149
+ },
150
+ };
151
+ case "secret":
152
+ // A saved secret says it is saved and how it ends; Replace opens the
153
+ // empty input, which takes focus.
154
+ if (saved && !saved.replacing)
155
+ return {
156
+ children: (
157
+ <SavedSecret
158
+ tail={saved.tail}
159
+ label={saved.label}
160
+ onReplace={saved.replace}
161
+ onRemove={saved.remove}
162
+ />
163
+ ),
164
+ };
165
+ return {
166
+ input: {
167
+ kind: "secret" as const,
168
+ value: text,
169
+ onChange: onText,
170
+ onCommit,
171
+ autoFocus: saved?.replacing,
172
+ },
173
+ };
174
+ case "date":
175
+ return {
176
+ input: {
177
+ kind: "date" as const,
178
+ value: text,
179
+ onChange: onText,
180
+ onCommit,
181
+ },
182
+ };
183
+ case "file":
184
+ return {
185
+ children: (
186
+ <Input
187
+ label={spec.label}
188
+ kind="file"
189
+ value={(value ?? null) as PickedFile | null}
190
+ onChange={(file) => {
191
+ set(file);
192
+ commit?.(file);
193
+ }}
194
+ accept={spec.accept ?? []}
195
+ />
196
+ ),
197
+ };
198
+ case "several":
199
+ if (spec.control === "list")
200
+ return {
201
+ options: {
202
+ options: listedOf(options),
203
+ value: value as Datum<readonly string[]>,
204
+ onChange: (next: string[]) => done(next),
205
+ },
206
+ };
207
+ return {
208
+ picker: {
209
+ options,
210
+ placeholder: said.several,
211
+ value: value as Datum<readonly string[]>,
212
+ onChange: (next: string[]) => done(next),
213
+ },
214
+ };
215
+ case "pick":
216
+ return pickOf(field, value as Datum<string | null>);
217
+ default:
218
+ return spec.options
219
+ ? pickOf(
220
+ field,
221
+ (isSelection(value)
222
+ ? value.at(heldPick)
223
+ : heldPick(value)) as Datum<string | null>,
224
+ )
225
+ : {
226
+ input: { value: text, onChange: onText, onCommit },
227
+ };
228
+ }
229
+ }
230
+
231
+ // A choice hint's options: the model holds them to a list in hand with no
232
+ // empty choice (a fixed `options` or the schema's values, on a field that
233
+ // always holds a value or picks several), which its `Datum` does not say.
234
+ const listedOf = (options: FieldModel["options"]) =>
235
+ options as readonly Option<string>[];
236
+
237
+ // A pick of one: the menu, or with a choice hint the option list or the
238
+ // segmented row, whose choices are a list in hand and never the empty one
239
+ // (the model throws otherwise).
240
+ function pickOf(field: FieldModel, value: Datum<string | null>) {
241
+ const { spec, options, said, set, commit } = field;
242
+ const done = commit ?? set;
243
+ const onChange = (next: string | null) => done(next);
244
+ if (spec.control === "list")
245
+ return {
246
+ options: { options: listedOf(options), value, onChange },
247
+ };
248
+ if (spec.control === "segments")
249
+ return {
250
+ segments: {
251
+ options: listedOf(options).map(({ value, label }) => ({
252
+ value,
253
+ label,
254
+ })),
255
+ value: value as Datum<string>,
256
+ onChange,
257
+ },
258
+ };
259
+ return { picker: { options, placeholder: said.one, value, onChange } };
260
+ }
261
+
262
+ /** A form that stands on its page (a `Form`, a `Gate`'s): its derivation, its frame over its read, its own touch state and its bar. Outside the package's exports. */
263
+ export function useStandingForm<P extends ProcedureCall>(props: FormProps<P>) {
264
+ const { frame: form, outer } = useDerivedForm(props, true);
265
+ const frame = useFrame(form.read);
266
+ const [touch] = useTouchState();
267
+ const bar = useFormBar(form.bar, frame, outer);
268
+ return { form, frame, touch, bar };
269
+ }
@@ -0,0 +1,49 @@
1
+ import { cn } from "@slotform/ui-core/cn";
2
+ import type { InputOf, ProcedureCall } from "@slotform/ui-core/form";
3
+ import type { FormModelProps } from "@slotform/ui-core/react/form";
4
+ import { CARD, FORM_FOOT, ROWS } from "@slotform/ui-core/variants";
5
+ import type { ReactNode } from "react";
6
+ import type { Act } from "../../lib/act.ts";
7
+ import type { Closed } from "../../lib/closed.ts";
8
+ import type { Empty } from "../../lib/empty.tsx";
9
+ import { FormRows, FormShell } from "./base.tsx";
10
+ import { useStandingForm } from "./derive.tsx";
11
+
12
+ interface FormBase<P extends ProcedureCall> extends Closed {
13
+ /** What follows the fields at the card inset, drawn from the input the fields make now (`given` and every field that holds a value, as the procedure would take them, a file as the picked file): a live preview of what the form would send. It is a function the form calls as it draws, so it is right before any keystroke (a prefilled form shows its first values), follows each change, and starts over when a sheet reopens; the form's bar stands after it, pinned in a sheet's foot. */
14
+ after?: (input: Partial<InputOf<P>>) => ReactNode;
15
+ /** The fields' sentence when the `read`'s selection is empty. */
16
+ empty?: Empty;
17
+ }
18
+
19
+ /** A form is its procedure and its field labels: `fields` or `groups`, never both. */
20
+ export type FormProps<P extends ProcedureCall = ProcedureCall> = FormModelProps<
21
+ P,
22
+ Act,
23
+ Empty
24
+ > &
25
+ FormBase<P>;
26
+
27
+ /** A form over a procedure: a card of the fields `fields` names, each drawn from the procedure's input schema (a string a line of text, in the mono with the `mono` hint, an enum a pick (the option list with the `list` hint, the segmented row with `segments`), a boolean a switch, a number a numeric line, a list of an enum, or of strings with `options`, a pick of several (the option list with a checkbox per option with `list`), a date a date line, a string with the `file` hint a file pick whose file is read into the string, a list with the `lines` hint a line per item, an object with the `json` hint mono JSON source), required unless the schema makes it optional (a pick or a switch with a schema `default` always holds a value, so it is required: no empty choice, no optional word) (in a submit form an optional one says so under its label; a form that commits by field marks nothing), with the server's refusal of its value under it, over a bar whose filled act submits the procedure. The act is pending while the procedure runs and while a promise `onDone` returns settles; then, where the form stays (on a page, its submit going nowhere), the fields go back to `values`; a rejection stands in the bar, and the issues the server's schema refused under their fields until the viewer changes them. A field with a `locked` reason stands inert with it under the control. With `commit: "field"` the form draws no bar and each field sends itself. `groups` partition the fields under bands, each with its own `values` and `empty`. A field holding a value other than its first draws its change mark. With `steps` the form asks one group (or one field) at a time: Continue folds the open step to its summary row and opens the next, and the last step's act is the submit. While the form stands edited (a field holds a value other than its first), leaving its page asks once, "Discard your edit?". A form over no procedure (a filter, a local setting) is not a `Form`: a filter is a `Toolbar`, a setting a `Switch` in a row. A form in a sheet is that `Sheet`'s `form`, these same props. */
28
+ export function Form<P extends ProcedureCall>(props: FormProps<P>) {
29
+ const { form, frame, touch, bar } = useStandingForm(props);
30
+ return (
31
+ <FormShell
32
+ frame={frame}
33
+ touch={touch}
34
+ guards={form.commit !== "field"}
35
+ edited={form.edited}
36
+ className={cn(CARD, ROWS)}
37
+ >
38
+ <FormRows
39
+ frame={frame}
40
+ groups={form.groups}
41
+ empty={form.empty}
42
+ after={form.after}
43
+ >
44
+ {form.children}
45
+ </FormRows>
46
+ {bar ? <div className={cn(FORM_FOOT)}>{bar}</div> : null}
47
+ </FormShell>
48
+ );
49
+ }
@@ -0,0 +1,39 @@
1
+ import { cn } from "@slotform/ui-core/cn";
2
+ import { useWords } from "@slotform/ui-core/react/words";
3
+ import { filled } from "@slotform/ui-core/tokens";
4
+ import { text } from "@slotform/ui-core/variants";
5
+ import { Button } from "../button/index.tsx";
6
+
7
+ const LINE = "flex min-w-0 grow items-center gap-gap";
8
+ const SAID = "min-w-0 grow truncate";
9
+
10
+ /** What a saved secret draws in its field: that it is saved and how it ends, in the meta ink, with a quiet Replace and a quiet Remove that asks first. The value is never read back, so no mask stands in for it. Outside the package's exports: a `Form` draws it for a saved `secret`. */
11
+ export function SavedSecret(props: {
12
+ /** The saved value's last characters, as the server sends them. */
13
+ tail: string;
14
+ /** The field's label, which names the acts and the decision. */
15
+ label: string;
16
+ onReplace: () => void;
17
+ onRemove: () => Promise<unknown>;
18
+ }) {
19
+ const words = useWords();
20
+ const { tail, label, onReplace, onRemove } = props;
21
+ return (
22
+ <div className={LINE}>
23
+ <span className={cn(text({ role: "meta" }), SAID)}>
24
+ {filled(words.savedEndsIn, { tail })}
25
+ </span>
26
+ <Button act="quiet" label={words.replace} onAct={onReplace} />
27
+ <Button
28
+ act="quiet"
29
+ label={words.remove}
30
+ confirm={{
31
+ title: `${words.remove} ${label}`,
32
+ sentence: words.removeSecret,
33
+ }}
34
+ done={words.removed}
35
+ onAct={onRemove}
36
+ />
37
+ </div>
38
+ );
39
+ }