@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,46 @@
1
+ # Where the canvas stands
2
+
3
+ Where a `Canvas` places its nodes, where it stands in a `Pane`, and what it draws while its read
4
+ waits or answers no node.
5
+
6
+ ## Where the nodes stand
7
+
8
+ Give no node a `position` and the canvas places them top to bottom in path order, loops inside
9
+ their group, the layers a bend, a chip's space and an arrowhead apart (about a node's height, so a
10
+ typical graph holds at a larger scale) and the nodes of a layer a card step apart. The parts of
11
+ a graph that no edge links (a group, or a loose node, with all an edge joins to it) stand side by
12
+ side; where that row is wider than the space the opening view has at the text floor, they wrap in
13
+ their order, each beside the last while the row holds it, else under it, so a narrow space holds
14
+ them in a column and no part opens wholly out of sight across. They wrap again as the canvas's
15
+ size changes, and the graph opens again on them. The places follow the nodes' measured heights: a
16
+ node that grows (a line that gains a second line after an edit) places the graph again, so each
17
+ layer keeps the space its chips need. With `onMove` it tells you each node's absolute position once, after it has placed
18
+ them: store those and pass them back as `position`. Give some nodes a position and you place
19
+ all of them; a node without one among placed ones lands at the centre of the view ([editing](./canvas-editing.md)).
20
+
21
+
22
+ ## In the page
23
+
24
+ The canvas has no height of its own: it fills the region it stands in. Stand it as the body's
25
+ direct child of a `Pane`'s body (it spans it), never inside a component of your own that sizes it. It fills the
26
+ body edge to edge: it runs over the body's inset to the Pane's sides and its bottom edge, and to
27
+ its top edge when it is the body's first child. What stands above it (a record's head, a meta line, a
28
+ banner) keeps the inset, and the canvas's top edge then draws a hairline where it meets that
29
+ content. Below `tablet` it keeps at least half of the column it stands in: the column scrolls past
30
+ it, so a head and banners above it scroll away and never shrink it.
31
+
32
+ ## Loading
33
+
34
+ `nodes`, `edges` and `groups` take a constant or a selection (`flow.at((f) => f.nodes)`). While a
35
+ selection's read waits the canvas stands its loaded ground painted: the dotted ground, the zoom stack
36
+ (with arrange where you gave `onMove`), inert, and in the middle three painted node cards at a step
37
+ node's measure (the node width and its card's height, a layer gap apart), laid by flex. A graph's own
38
+ nodes have no geometry before its data, so the painted cards stand for the nodes' measure and not their
39
+ places; nothing reads a box. It is the region the graph arrives in, so the page below the head does not
40
+ move when the nodes appear. The handlers and the `act` are
41
+ ignored meanwhile, and the surface draws no act, no node button and no drag. Give the canvas its
42
+ selection, not `nodes={[]}` for a wait: it reads as an empty graph. Its failed and empty read shapes
43
+ are the frame's, as for any collection.
44
+
45
+ A read that answers no node is the frame's empty shape, with the generic sentence. The canvas draws
46
+ no sentence of its own under a graph; a hint such as "Add a node" belongs in your page's head or its act.
@@ -0,0 +1,47 @@
1
+ # The canvas's opening view
2
+
3
+ Where a `Canvas`'s view stands as it opens, as its size changes and as its nodes change. Moving it is
4
+ [canvas-view](./canvas-view.md).
5
+
6
+ ## At its words
7
+
8
+ A graph opens at its words (scale 1, the text floor, `FIT_FLOOR`) where that shows every node whole
9
+ across the pane and clear of the zoom stack. Where its drawing (cards, routes, a loop's arrow up the
10
+ side, edge chips) fits the space the stack and the `act` leave, it is centred there;
11
+ where no node stands in the stack's rows it is centred across the pane;
12
+ else it is framed at its anchor, the reader panning down. The anchor
13
+ is the first node in path order, or the first that is `running` or has `failed` (its `status` tone),
14
+ so a run opens where it is: the anchor stands whole, the graph's top at the space's top unless the
15
+ anchor needs the view moved up. A drawing that holds in the pane only without its edge chips is
16
+ framed without them, and an edge chip past the pane's side is the one thing the opening may cut:
17
+ every card and box (the loops' bands) stands whole across the pane, a pair from either side, and none
18
+ under the zoom stack, else the graph opens as its overview.
19
+
20
+ ## As its overview
21
+
22
+ A graph that cannot open at its words opens as the overview: its glyphs, its boxes (the loops' bands,
23
+ their heads and the corridors up their sides) and the last glyph's name, fitted across the space the
24
+ stack leaves at the highest scale that holds them (just under the text floor where they fit there),
25
+ down to the overview's floor (half the node's size). Where it is also taller than the pane, it opens
26
+ lower, down to where its names still clear each other (with no named overview, to the lowest the
27
+ graph allows). A graph that holds only below the overview's
28
+ floor opens at that floor, never at its own size cut: its start against the space's start past the
29
+ stack, its top at the space's top, and the anchor kept whole in the pane and clear of the stack's
30
+ corner; the reader pans for the rest, and the last name in view may run past the pane's side.
31
+
32
+ ## Opening again
33
+
34
+ Arrange lands on the same view, and so does a change of the canvas's size (a `Pane` beside it
35
+ opening or closing, a resize), unless a node is `selected`: then the view keeps its scale
36
+ and pans only as far as that node needs, so a step's sheet docked beside the canvas leaves its step
37
+ in sight. A node `selected` as the canvas mounts is set in view at once where the opening leaves
38
+ it out. A node brought into view is centred in the space the zoom stack and the `act` leave, and where that space is too
39
+ narrow, moved past the stack or above it: it never stands under the controls.
40
+
41
+ A change of the node set (an id added or removed) opens the view again on
42
+ the new graph once it is laid out, or, with a node `selected`, pans to that node as a resize does,
43
+ unless the viewer has panned or zoomed since the view was last the canvas's own (by any gesture or zoom
44
+ step; Fit, Arrange and a resize make it the canvas's again): then the
45
+ view stays where the viewer left it. A graph whose nodes carry positions is not laid out and never
46
+ opens again; a node added to it lands where the viewer looks ([editing](./canvas-editing.md)).
47
+ The canvas needs no `key` for a new set.
@@ -0,0 +1,24 @@
1
+ # The canvas's overview
2
+
3
+ What a `Canvas` node draws under zoom 1, on every input: its glyph, the glyph's name, and the group
4
+ heads and edges around it. Zooming is [canvas-view](./canvas-view.md).
5
+
6
+ On every input, pointer and finger alike, a node under zoom 1 is its glyph: the icon in a
7
+ box of the density's `control` size, its border the state's (a selection or a warning), its
8
+ status as a dot on the box's top right corner, and a warning as a danger dot on its bottom right
9
+ corner, each seated on the rounded corner (half of it over the box) so neither covers the icon. From zoom 1 down to half the glyph
10
+ carries the node's `title` beside it, on one line at the meta size (12 px or more), in body ink at 500, cut at the
11
+ short measure, on the canvas's own ground so an edge never strikes through it; the name is
12
+ drawn at the same size at any zoom, so the overview never shows text under the 12 px floor.
13
+ Under half the glyph stands alone, with the `title` as its tooltip (the native `title`, so the cut-text tooltip leaves it its own). A name cut at the short measure, and a group head cut to the box's width, show whole in the cut-text tooltip when the pointer rests on them. A graph whose nodes stand too
14
+ close for their names to clear each other at half raises that zoom to the lowest at which they
15
+ clear, and one that cannot clear them under zoom 1 has no named overview: the glyph alone. Group
16
+ heads stay under zoom 1, drawn at their own size on screen (a button a target tall, the meta role's size, cut to
17
+ the box's width), and the nodes below a head move down by what it grew, so no head or box covers a
18
+ node outside its group; edge labels draw nothing. A click, a tap or Enter on a glyph or its name
19
+ zooms to that node at its own size about its centre, which stays where it stood (under the finger) unless the node would then pass the canvas's edge, when the view shifts just far enough (a page inset in) to hold the whole node, and chooses nothing.
20
+ Edges and group boxes follow the glyphs, so an edge ends on its glyph, and zooming out stops
21
+ where two glyphs would stand closer than two `gap`, so the edges between them still draw.
22
+ Give each node its own `title`: beside the icon it is the overview's only mark of one node of a
23
+ kind from another. Keep `warning` and `status` words short and put the detail in your
24
+ sheet: a glyph shows the mark, and the words are one tap away.
@@ -0,0 +1,37 @@
1
+ # Canvas states
2
+
3
+ What a `Canvas` node says of its state: off, a warning, a status, and the path a run took.
4
+
5
+ A node says its state in its own text or mark, never by colour alone.
6
+
7
+ - `off: true` draws the node quiet with the word "Off" in place of its line, and dims its edges. Under the text floor, where words drop, its glyph carries Off as a slash through its icon (and its name, the glyph's tooltip and accessible name, reads "<title>, Off").
8
+ An off edge is never dashed: dashed means a handoff and nothing else. The switch for it lives
9
+ in the node's sheet, not on the canvas. An off node ignores its `warning`.
10
+ - `warning` draws the node's border in the danger hue, a danger dot in its trailing column and
11
+ its words in place of the line, in the ink a line has. The dot stays when the node is selected,
12
+ which takes the border. Pass the first words only, and name the whole warning outside the canvas
13
+ in a `Banner` and a `Section`'s `items`. A node with a `warning` and a `status` draws both marks.
14
+ - `status` is a `StatusMark` (`{ tone, label }`): a fact, so it is a badge (`node_modules/@slotform/ui-core/guide/face-badges.md`, **Badges**) under the title,
15
+ its tone's mark (the dot, a spinner while the state is `running`) inside it before its `label`,
16
+ which stays in the meta ink; the title takes the node's whole width. The badge never breaks: the
17
+ label keeps its whole word up to the short measure and is cut with an ellipsis inside the badge
18
+ past it. The node's `line` (the `warning` in its place) is a sentence, so it is plain text under
19
+ the badge, wrapping to a second line and cut at that one's end. Keep the label a word or two
20
+ ("Paused", "Asks you first").
21
+ - `path` (`nodes`, `edges`, `at`) is what a run or a scenario took. A node the path leaves out
22
+ is a hairline on the canvas's ground (an on-path or an `off` node is a filled card) and draws every part in the meta ink, its title at regular weight (the node is a button you can still choose, so its words stay readable), and no status or warning mark; an edge it leaves out dims, its label chip's words in the meta ink with it, and `at` is outlined
23
+ as a selection is. On the path, off and off the path read apart: a filled card in the body ink, a filled card in the meta ink and the word "Off", a hairline in the meta ink. An edge is on the path by its own id, never by its ends.
24
+
25
+ A run over the workflow, with a status on the nodes it took:
26
+
27
+ ```tsx
28
+ <Canvas
29
+ label="Release run"
30
+ nodes={nodes.map((node) => ({ ...node, status: statuses.get(node.id) }))}
31
+ edges={edges}
32
+ groups={groups}
33
+ path={{ nodes: ["build", "check"], edges: ["a", "b"], at: "check" }}
34
+ />
35
+ ```
36
+
37
+ A state never moves a node or runs the layout again.
@@ -0,0 +1,46 @@
1
+ # Moving around the canvas
2
+
3
+ How a viewer pans and zooms a `Canvas`, and how the view travels. Where it opens is
4
+ [canvas-opening](./canvas-opening.md); a node zoomed out is [canvas-overview](./canvas-overview.md).
5
+
6
+ ## Pointer and wheel
7
+
8
+ A plain wheel pans, Shift with a wheel that only scrolls up and down pans sideways, Ctrl or Cmd with
9
+ the wheel zooms (a trackpad pinch is a Ctrl wheel), and a drag pans, even from a node (with `onMove`
10
+ a drag from a node moves that node instead). The zoom stack at the bottom left zooms in, zooms out
11
+ and fits. A zoom step is a fifth of the scale, about the node last focused, which stays where it
12
+ stands, else about the pane's centre; a zoom about a node (a step or a glyph's press) keeps it whole
13
+ and clear of the stack. Fit shows the whole graph, centred clear of the zoom stack and the `act`,
14
+ never larger than its own size, and under the text floor where it must, down to the lowest zoom the
15
+ graph allows.
16
+
17
+ A group head whose box runs under the zoom stack or off the pane's start or end keeps its words in
18
+ view: they stand past the stack's column where the head stands in the stack's rows (else at the pane's
19
+ start, so a head above the stack has its box's whole width) and stop at the pane's end (truncating
20
+ there) while the band stays across the box. The stack and the `act` stay at the region's foot: a focus on a node out of
21
+ view pans the view to it and scrolls nothing. Zooming out by hand still goes under the floor, to the
22
+ overview and the glyph alone.
23
+
24
+ ## On touch
25
+
26
+ The canvas draws the touch density's sizes at touch, and a phone pans and zooms the same
27
+ canvas. One finger drags the ground, and drags a node too, which pans (a node never moves under a
28
+ finger that is moving). Two fingers pinch. With `onMove`, a node held still for a moment lifts,
29
+ draws a 2 px outline in the selection's colour, scales to the lift scale with its float shadow fading in on `fast`, and follows the finger; releasing it calls `onMove` once. A
30
+ second finger landing on a lifted node drops it where it is. A lift never selects, and a tap on a
31
+ node selects it as a click does.
32
+
33
+ Every zoom button, the `act`, each glyph and each port is at least 44 px at the touch density, at
34
+ any zoom: a port's hit is drawn at that size whatever the scale.
35
+
36
+ ## Motion
37
+
38
+ The canvas's viewport travels for the viewer's own acts: a zoom step, Fit, a reveal of a node chosen
39
+ from outside or reached by the keyboard, and a tap on a glyph travel on `base` `in-out`, by the
40
+ canvas's own frames (the layer and the dot grid together); quick presses add up, and a pointer, a
41
+ finger or a wheel taking over ends the travel where it got to. The opening view, Arrange's fit, the
42
+ view a resize opens again and the lowest-scale clamp land at once. A node answers on `fast` (its border and ink), a taken path's
43
+ tone (the edges, the chips, the words) cross-fades on `base`, and a node crossing the text floor
44
+ cross-fades with its glyph on `fast`: the card fades out and, inert, takes no pointer or key, and
45
+ the glyph fades in. A node that lands fades in at its place on `base`, and the graph fades in once
46
+ it is laid out. Under reduced motion every one of these lands at once.
@@ -0,0 +1,94 @@
1
+ # The canvas
2
+
3
+ A graph the viewer reads or walks, a workflow or a journey, is a `Canvas`, never a hand-built
4
+ diagram of `div`s and lines. It takes data and draws the nodes, the arrows between them, the
5
+ boxes around groups and the zoom stack.
6
+
7
+ ```tsx
8
+ import { Canvas } from "@slotform/react-ui/components/canvas";
9
+ ```
10
+
11
+ ## The data
12
+
13
+ A node is a `CanvasNode` (`id`, `icon`, `role`, `overline`, `title`, `line`, and a trailing `number` or
14
+ `count`), an edge a `CanvasEdge` (`id`, `from`, `to`, an optional `label`), a group a
15
+ `CanvasGroup` (`id`, `head`, `holds`: node ids and group ids). All come from
16
+ `@slotform/ui-core/descriptors`. The canvas draws `number` over `count` and never invents a number.
17
+ A node's `line` wraps to a second line and is cut at that one's end, so a list in it (a trigger's
18
+ callers, a gate's answers) keeps more than its first words; the node is as tall as its lines.
19
+
20
+ A **workflow** loops, answers back upstream and hands work to someone else. An edge into an
21
+ earlier node is drawn up the side, an edge that skips a layer runs down a column beside the nodes
22
+ it passes, never behind one, and an edge with `handoff: true` is dashed, with the handoff
23
+ glyph beside its label: dashed means a handoff and nothing else. A label stands beside its edge's
24
+ own stretch, near its source; a label never prints over another, under a node or over a loop's
25
+ border or head: one that would meet another label, a node's box or a group box's border moves down its
26
+ stretch past it, or beside it where the stretch cannot hold both.
27
+
28
+ ```tsx
29
+ <Canvas
30
+ label="Release flow"
31
+ nodes={[
32
+ { id: "build", icon: "Hammer", overline: "Build", title: "Make the change", line: "Edits the files" },
33
+ { id: "check", icon: "ShieldCheck", overline: "Check", title: "Run the checks", count: 3 },
34
+ { id: "ship", icon: "Send", overline: "Handoff", title: "Hand over" },
35
+ ]}
36
+ edges={[
37
+ { id: "a", from: "build", to: "check" },
38
+ { id: "b", from: "check", to: "build", label: "red" },
39
+ { id: "c", from: "check", to: "ship", label: "green", handoff: true },
40
+ ]}
41
+ groups={[{ id: "loop", head: "Until green", holds: ["build", "check"] }]}
42
+ />
43
+ ```
44
+
45
+ A **journey** branches and rejoins, and numbers its steps. Take the numbers from the library, in
46
+ the order the canvas reads and the keyboard walks:
47
+
48
+ ```tsx
49
+ import { pathOrder } from "@slotform/ui-core/canvas";
50
+
51
+ const numbers = new Map(pathOrder(nodes, edges).map((id, index) => [id, index + 1]));
52
+ const numbered = nodes.map((node) => ({ ...node, number: numbers.get(node.id) }));
53
+ ```
54
+
55
+ ## What a node is
56
+
57
+ A node says what it is in the graph with its `role`, which sets its shape and its tone from the
58
+ design's tokens, never from a colour of the app's. `step` is the default, today's plain card.
59
+
60
+ | `role` | Draws | For |
61
+ | --- | --- | --- |
62
+ | `start` | a pill in the accent tone (accent-tinted ground and edge, accent icon) | where the graph begins: a trigger, an entry |
63
+ | `step` | the plain card | work that happens |
64
+ | `decision` | a card with its icon in a diamond, a stronger edge | a branch; its answers are the labels on its out-edges, its line the subject they answer |
65
+ | `wait` | a card in the attention tone (attention-tinted ground and edge, attention icon) | something waits for a person here |
66
+ | `call` | a card with a double edge (a second hairline a step outside the first) and, with an `href`, an open act | another graph runs here |
67
+ | `end` | a pill in the quiet tone (muted ground, muted words) | where a path stops |
68
+
69
+ A `call` node's `href` (a `Route`) draws a small open act at the card's end, an arrow named
70
+ "Open" and the node's title, which goes to that graph and never chooses the node; pressing the
71
+ node's body still does. The act is the card's sibling and draws only while the node draws its card:
72
+ under the text floor the glyph carries no act.
73
+
74
+ Every tier shows the role: under the text floor and the overview floor the glyph takes the role's
75
+ shape and tone too (a pill is a circle, a decision a diamond, a call keeps its double edge), so an
76
+ overview you zoomed out to still reads. A role's look is its own shape and tone only: `off` draws
77
+ the node quiet over its role (the shape stays, the tone steps back to the plain card's), a
78
+ `warning` still replaces the line and takes the outline, a node off a run's `path` dims as it
79
+ did, and the selection's outline is the accent's ink, which is stronger than the start's edge.
80
+
81
+ ## Its other pages
82
+
83
+ - [Moving around](./canvas-view.md): pan, zoom, touch and the view's motion.
84
+ - [The opening view](./canvas-opening.md): where the view stands as it opens.
85
+ - [The overview](./canvas-overview.md): the glyphs under zoom 1.
86
+ - [Where it stands](./canvas-layout.md): the nodes' places, the canvas in a `Pane`, loading.
87
+ - [Editing](./canvas-editing.md): moving, landing and connecting nodes.
88
+ - [States](./canvas-states.md): off, warning, status and a run's path.
89
+ - [Choosing a node](./canvas-choosing.md): selection, groups and the `act`.
90
+
91
+ ## Check
92
+
93
+ `pnpm check` passes, and the canvas is read in light and dark at desktop and touch density, with
94
+ one node chosen and with none.
@@ -0,0 +1,60 @@
1
+ # Gate, Sheet, Banner, Columns and Card
2
+
3
+ The containers past the `Shell` and the `Pane`: the `Gate` outside the shell, the `Sheet` over a page, the `Banner` over a column, the `Columns` and `Card` that arrange its sections. This page is what each takes and how it lays out; the `Shell` is [shell](./shell.md), the `Pane` [pane](./pane.md), and which container a screen needs is [rules](./rules.md).
4
+
5
+ ## Gate
6
+
7
+ A page outside the shell: one centred step.
8
+
9
+ | Prop | Is |
10
+ | --- | --- |
11
+ | `title` | the page's one `h1` |
12
+ | `description` | a meta line, runs allowed (`{ strong }` for an address) |
13
+ | `step` | `{ at, of }`, the onboarding count between the mark and the title |
14
+ | `banner` | a `Banner` under the title, at the column's width, so a verdict stands with the content it is about |
15
+ | `children` | the body ahead of the form: a `Picker` at `list`, `Section`s of rows, controls |
16
+ | `acts` | `Act`s and `LinkAct`s (a Back, a way home) in reading order, the filled act last, drawn as an `ActionBar` under the body at the auth width, across the column with the filled act on top |
17
+ | `form` | a `Form`'s props ([forms](./forms.md)): its fields a card and its bar after the card |
18
+
19
+ A Gate holds one bar, its `acts` or its `form`'s. A step with a `form` gives its alternatives as the form's `acts`; a resend is a caption with an inline act (`Button` at `fit="inline"`) in the form's `after`.
20
+
21
+ ## Sheet
22
+
23
+ A task over the page: a create, an edit, a decision, an acknowledgement. A record is read in a `Pane`, never in a sheet.
24
+
25
+ | Prop | Is |
26
+ | --- | --- |
27
+ | `open`, `onClose` | its holder owns both; an act's `sheet` takes the rest (`node_modules/@slotform/ui-core/guide/sheets.md`) |
28
+ | `title` | the heading, which names it |
29
+ | `description` | the sentence under it |
30
+ | `back` | a function, a second page's way back, first in the head (on touch in the close act's place) |
31
+ | `submit` | the act that completes the task, an `Act` with its `blocked`, `confirm`, `done` and `to`, or `{ label }` alone, which acknowledges |
32
+ | `read` | the body's read: while it waits the body and the submit paint, inert; its failure stands in the body's place, the submit blocked |
33
+ | `empty` | the body's sentence when the `read` is empty |
34
+ | `children` | the body's parts, ahead of the `form`, at the card inset |
35
+ | `form` | a `Form`'s props ([forms](./forms.md); in a sheet, `node_modules/@slotform/ui-core/guide/forms.md#a-form-in-a-sheet-or-a-gate`): its `after` follows its fields with the form's bar after it, pinned to the sheet's foot, so the submit never ends above the preview |
36
+
37
+ The submit stands in the foot after the body, so it follows the fields it submits: after Cancel on the desktop, alone on touch, where the close act leads the head. A `submit` with no `onAct` (`{ label: "I saved them" }`) acknowledges what the sheet shows: its press closes the sheet, and no Cancel stands beside it.
38
+
39
+ A `submit` that cannot run says why with `blocked: "the reason"`, a sentence the viewer can act on ("Write the trigger's words."): the submit stands blocked, and its reason stands in the foot's line under the acts, at the submit's edge, once the viewer presses it or the sheet has taken input, never before. A sheet with no foot (no `submit`) ends on its last part, which keeps a sections gap under it, so a banner that closes a sheet stands off its bottom edge.
40
+
41
+ ## Banner
42
+
43
+ A sentence over a column (the `Shell`'s `banner`, a `Gate`'s, a Pane's section): a verdict, a caution, a run in progress.
44
+
45
+ | Prop | Is |
46
+ | --- | --- |
47
+ | `sentence` | the text beside the glyph, words or runs (a `{ code }` stands boxed in the mono); a selection that waits or answers `undefined` draws no banner |
48
+ | `tone` | `active` (news, the default), `attention`, `failed` (announced at once) or `running` (`node_modules/@slotform/ui-core/guide/tone.md`); a selection paints the glyph in the news tint until it lands |
49
+ | `act` | the one act at the line's end, an `Act` or a `LinkAct` (an anchor), drawn as the hairline Button, whose outline shows because the banner's soft ground re-points `edge` to the strong edge; a blocked act's reason stands on the banner's own line under it |
50
+ | `until` | with `tone="running"`, when the run ends: the time left after the sentence, a line along the foot that fills toward it, the clock stopping at 0:00, and the `act` as the cancel |
51
+
52
+ A banner that stands only with its data is always placed, its `sentence` a selection that answers `undefined` when there is nothing to say, so the page moves once, by its height, when it arrives.
53
+
54
+ ## Columns
55
+
56
+ Sections side by side. `fit`: `board` (the default) stands each at the column width in a row that scrolls sideways; `half` stands two to a row from the Pane's desktop width and stacks them below it.
57
+
58
+ ## Card
59
+
60
+ A surface for one part of a `Section` that draws none (a `Prose`, `Stages`, `Image` or `Slider`, as `children`). A `Form`, a `Table`, a `Stats` and a `BarChart` are cards already.
@@ -0,0 +1,40 @@
1
+ # Content: toolbars, rules and threads
2
+
3
+ The `Toolbar` over a list, `Rules` and a `Thread`. Each takes its data as props and, given a selection, is the frame of its own read. A `Section` of rows is [section](./section.md), a `Table` [table](./table.md), the drags between them [drag](./drag.md), and the parts that read as a block [blocks](./blocks.md). This page is what each takes.
4
+
5
+ ## Toolbar
6
+
7
+ The strip over a list.
8
+
9
+ - `tabs`: `{ label, href }` views, the one the location selects marked.
10
+ - `search`: `{ value, onChange, placeholder? }`. Absent, the strip has none.
11
+ - `filters`: a `Picker`'s own props (`label`, `options`, `value`, `onChange`; an array `value` picks several). Two or fewer stand beside the acts on the desktop; three or more fold behind one Filters act that counts those set; on touch every filter folds.
12
+ - `chips`: `{ label, family, onRemove }`, the applied filters of the app's own, in a row under the strip.
13
+ - `children`: the acts at the bar fit, never a filled act: the create act is the page's.
14
+
15
+ ## Rules
16
+
17
+ Rows of inline terms. `rules` is a list of `{ id, terms, onRemove? }` with `terms` a pair (`from`, `to`) or a condition (`field`, `operator`, `value`); `add` is the act that ends the list.
18
+
19
+ ## Thread
20
+
21
+ A conversation: `items` drawn through `message`, over a `composer`.
22
+
23
+ - `message`: regions each reading only its item: `key`, `author`, `name`, `body`, `at`, `attachments`, `from`, `streaming`, `onOpen`, `detail`.
24
+ - `composer`: `value`, `onChange`, `attachments`, `onAttach`, `onDetach`, `placeholder`, `notice`, `working`, `onSend`, `onStop`, `disabled`. An attached image's file carries `src`, an object URL to draw it from before it is uploaded; it stays until you revoke it (`URL.revokeObjectURL(file.src)`) once you drop the attachment. A `file` `Input`'s file carries no `src`.
25
+ - `sheet`: docks in the input's place.
26
+ - `replying`: a reply from the other author is on its way; the loaded log ends on a waiting message of theirs until it is cleared.
27
+ - `reply`: the turn being written, a stream the app declares (`node_modules/@slotform/query/guide/pages-and-streams.md`). It draws after the items and steps aside once the last item has its key.
28
+ - `empty`: the sentence, and the act that makes the first message.
29
+
30
+ ```tsx
31
+ <Pane title="Chat" fill>
32
+ <Thread
33
+ items={log}
34
+ message={{ key: (m) => m.id, author: (m) => m.who, body: (m) => m.text }}
35
+ composer={{ value: draft, onChange: setDraft, onSend: send }}
36
+ />
37
+ </Pane>
38
+ ```
39
+
40
+ Where the composer docks in a `Pane`'s foot: [pane](./pane.md#the-foot).
@@ -0,0 +1,89 @@
1
+ # Controls
2
+
3
+ A control is a field: it takes its `label`, plus the `description`, `optional` and `error` it draws placed alone, and no screen draws a control's name itself (`node_modules/@slotform/ui-core/guide/controls.md` says which control a value takes and when a control draws its field). A control's `value` may be a selection: it paints the control, inert, until its read lands, and follows it until the viewer changes it. Save from `onChange` or, where a keystroke is no save, `onCommit`: return the save's promise and the viewer's value holds while it pends; a refusal puts it back with its reason. This page is what each control takes.
4
+
5
+ ## The field's props
6
+
7
+ Every `Input`, `Picker` at its field fit, as a list or as choice segments, `Switch` and `Slider` takes these; placed alone (in a `Card`, a `Sheet`'s body, a `Gate`) it draws them around the control.
8
+
9
+ | Prop | Is |
10
+ | --- | --- |
11
+ | `label` | the field's name, over the control (a switch at the end of its label's line); in a `Form` or a `Toolbar`, and on a `search` or a `Picker` at `bar`, `row` or `pill`, the accessible name alone |
12
+ | `description` | a sentence under the control |
13
+ | `optional` | draws the word `optional` under the label |
14
+ | `error` | the line in the description's place, a sentence, words or runs (`["No project at ", { code: "apps/billing" }, "."]`), so a machine name in it stands boxed in the mono; a refused save's reason stands there too until the next change |
15
+
16
+ ## Button
17
+
18
+ One act in three forms: labelled, `href` (a link) and `glyph` (the icon alone).
19
+
20
+ | Prop | Is |
21
+ | --- | --- |
22
+ | `label` | the visible text, and in the `glyph` form the accessible name and the tooltip |
23
+ | `act` | its kind: `primary` (the accent fill, the default), `danger` (the danger fill), `secondary` (a hairline), `destructive` (the hairline in danger ink), `quiet` (words in the meta ink). The `glyph` form takes `quiet` (the default), `destructive` or `primary` (a glyph on the accent fill, the act its bar is for: a player's Play). A link given an `act` is an anchor in that act's look; without one it is accent ink in the type of its line |
24
+ | `fit` | what it sits in: `body` (the default), `field` (full width under a field, or a glyph at a field's end), or `inline`, inside a sentence after its caption ("Didn't get the code? Resend"): its words in the accent ink, underlined, in the sentence's type; a rejection raises a failed toast, and blocked it stands inert in the meta ink |
25
+ | `icon` | leads the label, in the label's ink; the glyph in the `glyph` form |
26
+ | `count` | follows the label, in the label's ink |
27
+ | `wait` | the seconds left of a delay (a resend that opens in 30): inert while it is above zero, its count drawn and no reason under it; at zero the count's region stays hidden so the act keeps its width |
28
+ | `blocked` | why the act cannot run, a sentence: it is inert and says so under itself once pressed. The link form takes none |
29
+ | `onAct`, `confirm`, `done`, `to`, `sheet` | the act's wiring, run in that order (`node_modules/@slotform/ui-core/guide/acts.md#the-wiring-is-data`) |
30
+ | `href` | makes it a link, an `<a href>`: a new tab, a copied link and a middle click work, a plain click opens the route through the router, and a rest preloads it |
31
+ | `glyph` | `true`: the icon alone |
32
+
33
+ ## Input
34
+
35
+ What is typed or picked, by `kind`.
36
+
37
+ | `kind` | Is |
38
+ | --- | --- |
39
+ | `text` | a line of text, the default |
40
+ | `search` | a toolbar box with its glyph; it names itself |
41
+ | `secret` | a line masked as typed |
42
+ | `source` | a line in the mono for what a machine reads (a command, a path): at the field's own fit (placed alone, in a `Form`'s field) it wraps at any character, the box growing by its lines and Enter never starting a second; in a row's entry, a `Rules` term or a `Table` cell it stands at the bar fit, one line |
43
+ | `number` | a numeric line, with `unit` |
44
+ | `email` | an address line |
45
+ | `date` | a day (`<input type="date">`), the value `YYYY-MM-DD` |
46
+ | `prose` | many lines, in a box that grows from three |
47
+ | `code` | a one-time code, a box per digit |
48
+ | `file` | a file chosen or dropped |
49
+
50
+ A line of text scrolls inside its box and is cut with an ellipsis at rest.
51
+
52
+ | Prop | Is |
53
+ | --- | --- |
54
+ | `placeholder` | the hint while empty, never the field's name |
55
+ | `onChange` | hears every keystroke |
56
+ | `onCommit` | hears the value when the viewer is done: on leaving the field or Enter, only if it changed since focus; Escape puts back the value at focus. A `prose` input commits on leaving it alone, since Enter is a new line |
57
+ | `unit` | a `number`'s unit after the value, a word |
58
+ | `act` | an icon act at the field's end (copy, reveal, add), which Enter presses except in a `secret`, where Enter commits and only a press runs the act (a Remove) |
59
+ | `autoFocus` | focus on mount, the caret at the end, for a field that replaces what the viewer was reading; never one on a form that loads with the page |
60
+ | `source` | on `prose`: mono, indentation kept |
61
+ | `budget` | on `prose`: a word budget, the count drawn against it, in the error ink once over |
62
+ | `length` | on `code`: the digits, a box each |
63
+ | `onComplete` | on `code`: hears the code at its last digit. Return the check's promise: the boxes hold the code at rest, disabled under a spinner line, and a refusal stands under them with its reason |
64
+ | `accept` | on `file`: the MIME types, families and extensions (`["text/csv", ".har"]`); any other file never reaches `onChange` |
65
+
66
+ ## Picker
67
+
68
+ A pick among options.
69
+
70
+ | Prop | Is |
71
+ | --- | --- |
72
+ | `options` | flat, or under group labels (`{ label, options }`). An option is `{ value, label, line?, leading?, chip?, recommended?, blocked? }`: its `leading` a status, an avatar or an icon, its `chip` after its label, its `line` under it, and `blocked` why it cannot be chosen while it is not in the value. An option whose value is `null` is the empty choice |
73
+ | `value` | the chosen value; an array picks several |
74
+ | `placeholder` | the hint while nothing is chosen. At `field` the label stands over the box; at `row` the hint is the generic word (`words.choose`) and the label stays the accessible name; at the other fits the label is the hint |
75
+ | `fit` | where it stands: `field` (the default), `bar`, `row` or `pill` open a popover (a sheet on touch); `list` stands the options in the page as rows; `segments` as one row |
76
+ | `act` | the act that makes a new option, ending the list under a hairline: an icon act that runs, a sheet it opens, or a link to where it is made |
77
+ | `headed` | at `list`, the body of a titled `Section`: it draws no field, the title naming it; it takes no `description`, `optional` or `error` of its own |
78
+ | `items`, `option` | at `list`, rows drawn from a read, a function per row region |
79
+ | `children` | at `list`, what stands under the first chosen option |
80
+
81
+ At `segments`, options `{ label, href }` are the tabs of a place and hold no value: the option whose `href` is the location's path, or its nearest parent, is selected, and a plain press opens its `href` in the router like a `Link`. A `Toolbar` takes the same array as `tabs`.
82
+
83
+ ## Switch
84
+
85
+ Every boolean: `checked` and `onChange`, with the field's props. Placed alone the switch stands at the end of its label's line, the `description` or `error` under them.
86
+
87
+ ## Slider
88
+
89
+ A number along a range. `value` runs from `min` to `max` in `step`s (1 unless set). `unit` is an Intl unit identifier (`minute`, `percent`) formatted after the value in the viewer's locale. `onChange` hears each value as it moves, `onCommit` the one the viewer lets go of (a key's step is one).
@@ -0,0 +1,48 @@
1
+ # Density and the page
2
+
3
+ Which set of sizes draws where (desktop, touch and room), the page container a `Pane` reads its width
4
+ from, and the safe areas on a phone. The options and the mode are [reference](./reference.md).
5
+
6
+ ## Density
7
+
8
+ Density is no option. The desktop set draws where the pointer is fine and the viewport is at
9
+ least `tablet` wide; the touch set draws everywhere else, so a narrow desktop window draws the
10
+ touch sizes and structure. A `data-density` attribute on `<html>` pins one: `desktop` or `touch`.
11
+ Sizes, spacing roles and type roles follow density on their own; a molecule whose structure
12
+ differs by density reads it itself.
13
+
14
+ A desktop window narrower than `tablet` with a fine pointer (a browser extension's popup, about
15
+ 420 px) draws the touch set: width is the structure rule, and the pin is the supported answer. Set
16
+ `data-density="desktop"` on `<html>` for a page that stands in such a window, in its HTML or with
17
+ `document.documentElement.dataset.density = "desktop"` before the first render (the `no-density`
18
+ lint rejects the attribute as JSX, so it is never on an element of the app's own). The page
19
+ does not use the `Shell`, whose desktop form is a 220 px sidebar that a 420 px window cannot hold
20
+ beside a page: a pinned page is a `Gate` alone.
21
+
22
+ A screen read from across a room is the one set a page states, `distance="room"` on the `Panes` it
23
+ draws outside the `Shell` ([shell](./shell.md#panes); the
24
+ showcase's `/tv` page; the `Shell` takes none): that place sets `data-density="room"` on
25
+ itself, so the touch set at a 960 × 540 canvas scaled to the window draws inside it (`--room-unit`
26
+ holds the scale), with the touch structure. A layer that portals (a menu, a picker, a sheet) draws
27
+ outside that scope, which is why a room place's `Pane` takes no `more` or `foot`. A room page with
28
+ no data to show (signed out, the server not answering) draws its `Gate` inside the same `Panes`, so
29
+ the Gate fills it at the room set and stands its step in the middle of the screen (the showcase's
30
+ `/tv-offline`). Inside a room place the board takes the room's own forms: a `Pane`'s head stands a
31
+ `pad` off the top, on the table, over a bar of its own; a row whose only mark is a status fact draws
32
+ one line, the status after the facts at the end group's start, whole whatever its word, the facts taking
33
+ the space it leaves; a `Stats` strip is the rows' width, its cells sharing it in proportion, so it
34
+ reads as one column with the rows under it. The showcase's `/tv` draws the strips and `/tv-board`
35
+ thirty rows at 960 × 540.
36
+
37
+ ## The page container
38
+
39
+ The place the `Shell` draws is the `place` size container and each `Pane` the `page` one. The place
40
+ decides which `Pane`s stand by its own width, never the viewport's ([shell](./shell.md#panes)), so a record keeps its space beside the sidebar at any window width. What stands
41
+ in a `Pane` reads the `Pane`'s width. On the desktop the place is a raised panel an `gap` gap from the canvas
42
+ at its top, end and bottom and against the 220 px sidebar (a dark slate column, pinned dark in both modes); on touch it fills the column.
43
+
44
+ ## Safe areas
45
+
46
+ The touch places layer clears a phone's status bar and home indicator by itself: the document
47
+ sets `viewport-fit=cover`, and the layer pads its top and bottom by the safe-area insets. The Shell's column pads
48
+ its top by the safe-area inset, so a banner or a page's head clears a notch or a status bar.
package/guide/dock.md ADDED
@@ -0,0 +1,42 @@
1
+ # The dock and the waveform
2
+
3
+ The `Dock` draws what the player plays under the place, and a `Waveform` draws a track's peaks as a
4
+ seek slider, in the dock or on its own. The player and its tracks are [audio](./audio.md).
5
+
6
+ ## The dock
7
+
8
+ It draws the picture, the name over its line, previous, play or pause (the primary glyph) and next
9
+ (the first and last only where there is a queue), the elapsed time, the seek, the total, mute with a
10
+ volume slider and a close. The name, the transport and the seek share the bar's width by flex, so the
11
+ transport stands at its centre. An `image` given as a selection paints the tile until its read lands. A track with no `image`, or one that fails to load, draws the tile's
12
+ failed shape, so the name keeps its place. The seek is a `Waveform` where the track has `peaks` and a
13
+ slider where not. On touch the transport and the name stand on a first bar and the seek on a second,
14
+ with no volume: the device's own buttons set it. Volume and mute are kept from one visit to the next.
15
+
16
+ While it stands the dock takes Space and the horizontal arrows anywhere that is not typing or a
17
+ control that takes the key itself (a `Table`'s grid takes them where it acts on them), and the
18
+ system's media keys and lock screen drive the same player. The system's media controls show the
19
+ name and the line, and the picture once the dock draws it (an `image` given as a selection once its
20
+ read lands). A `Dock` takes no props.
21
+
22
+ ## A waveform on its own
23
+
24
+ ```tsx
25
+ <Waveform
26
+ label="Seek the track"
27
+ peaks={{ values: song.peaks }}
28
+ duration={song.seconds}
29
+ at={time}
30
+ onSeek={player.seek}
31
+ />
32
+ ```
33
+
34
+ `peaks.values` is one 0..1 magnitude per value, or with `paired: true` each pair a stretch's
35
+ lowest and highest sample (-1..1); an array or a typed array, at any resolution. `fit="bar"`
36
+ stands at the control height (in a `Toolbar`-height bar); the default stands at the waveform size
37
+ in a `Pane` or a `Card`. It does not move itself: `at` is the playhead, so a standalone waveform
38
+ takes `usePlayerTime().time` or the app's own clock. A drag holds the pointer as the playhead and
39
+ `onSeek` hears one second, on release; the keys seek at once.
40
+
41
+ **Check:** a drag on the waveform moves the playhead and seeks once on release, and Left and Right
42
+ move it five seconds.
package/guide/drag.md ADDED
@@ -0,0 +1,38 @@
1
+ # Drag, drop and reorder
2
+
3
+ A drag is data: a row says what it carries, a place or a row says what it takes, a collection says whether it orders its rows; the press, the label that follows the pointer, the line, the scroll, the held order and the keys are the platform's. Web only.
4
+
5
+ | Prop | On | Is |
6
+ | --- | --- | --- |
7
+ | `drag` | a `Table` | `{ kind }`: a row carries `{ kind, picked }`, the whole pick when the row dragged is ticked (over a paginated read the query), the row alone when not |
8
+ | `drag` | a `Section` row | `{ kind, picked }`, the row's own |
9
+ | `drop` | a `PlaceSpec`, a `Section` row, a `Table`'s `row.drop` | `{ accepts, label, onDrop, blocked?, confirm?, done?, to? }`: `accepts` a kind or several; `label` required, as it is also the row's menu entry; `onDrop(drag)` runs as an act does |
10
+ | `reorder` | a flat `Section`, a `Table` while unsorted | `{ onMove(id, { index, after, before }), done? }` |
11
+
12
+ ```tsx
13
+ // A table of tasks: its rows drag, and the ticked ones drag together.
14
+ <Table columns={COLUMNS} items={tasks} row={ROW}
15
+ drag={{ kind: "task" }}
16
+ choose={{ chosen, onChange: setChosen }} />
17
+
18
+ // A place in the sidebar takes them. `drag.picked` is a `Picked`: the ids, or the query less the ids
19
+ // unticked, which `selector()` of `@slotform/api` takes whole.
20
+ const places: PlaceSpec[] = boards.map((p) => ({
21
+ label: p.name, icon: "ListChecks", route: `#${p.id}`, group: "Boards",
22
+ drop: {
23
+ accepts: "task",
24
+ label: `Add to ${p.name}`,
25
+ onDrop: (drag) => addTasks.mutateAsync({ board: p.id, tasks: drag.picked }),
26
+ done: `Added to ${p.name}`,
27
+ },
28
+ }));
29
+
30
+ // A collection that orders its rows:
31
+ <Section items={queue.at((rows) => rows.map(toRow))} // toRow gives each row `drag: { kind: "task", picked: { ids: [id] } }`
32
+ reorder={{ onMove: (id, to) => move.mutateAsync({ id, after: to.after, before: to.before }), done: "Queue updated" }} />
33
+ ```
34
+
35
+ - **Payload.** A drop hears `onDrop(drag)` and runs as an act does: its `confirm` asked, `done` toasted, `to` gone to, a rejection toasted with Retry. A drop with `blocked` takes nothing and its menu entry is blocked. `PlaceSpec<Q>`, `Row<V, Q>` and `RowRegions<T, Q>` take the read's query as `Q`, so `drag.picked` is the `Picked<Q>` a `selector()` mutation takes whole, with no cast.
36
+ - **Reorder.** `after` and `before` are the ids the row lands between (null at an end): a fractional position is `between(after?.position, before?.position)`, and the order is yours. The rows show the move at once and keep it until the data answers; a refusal puts them back. One row moves at a time: a ticked set drags to a drop and is never moved as a set.
37
+ - **Pointer.** The press that moves a row (4 px; a finger after a 400 ms hold, one that moves sooner scrolls the page) drags it, and goes on while the dragged row leaves the window of a long collection. A line in the accent marks where a reordered row lands, a place that takes the drag washes as selected under the ring, the scroller under the pointer (the Pane's body, the sidebar's places, any list) scrolls near its edges, a drag held over a folded sidebar branch that a place inside takes opens it, and Escape cancels. Nothing animates: the drop lands at once.
38
+ - **Keyboard and menu, the floor.** Every drop standing that accepts a row's kind is an entry in that row's more menu (its `label`); a collection that reorders adds Move up, Move down, Move to top and Move to bottom to every row's menu, and **Alt with Up, Down, Home or End** moves the focused row (the active row of a grid, any control of a list row). A sidebar place's drop is an entry whether or not its row stands, a folded branch's children included. Nothing is merged by label: places that share one are each named by their path (`Add to Warm-up (Sets › Warm-up)`, `Add to Warm-up (Archive › Warm-up)`); a row and a place are one entry only where the row's `href` is the place's route.