@slotform/react-ui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (280) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +44 -2
  3. package/dist/density.d.ts +4 -0
  4. package/dist/density.d.ts.map +1 -0
  5. package/dist/density.js +8 -0
  6. package/dist/density.js.map +1 -0
  7. package/dist/index.d.ts +400 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +388 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/node/canvas.d.ts +3 -0
  12. package/dist/node/canvas.d.ts.map +1 -0
  13. package/dist/node/canvas.js +13 -0
  14. package/dist/node/canvas.js.map +1 -0
  15. package/dist/node/codegen.d.ts +6 -0
  16. package/dist/node/codegen.d.ts.map +1 -0
  17. package/dist/node/codegen.js +70 -0
  18. package/dist/node/codegen.js.map +1 -0
  19. package/dist/node/css-escape.d.ts +8 -0
  20. package/dist/node/css-escape.d.ts.map +1 -0
  21. package/dist/node/css-escape.js +12 -0
  22. package/dist/node/css-escape.js.map +1 -0
  23. package/dist/node/fonts.d.ts +6 -0
  24. package/dist/node/fonts.d.ts.map +1 -0
  25. package/dist/node/fonts.js +219 -0
  26. package/dist/node/fonts.js.map +1 -0
  27. package/dist/node/lint.d.ts +3 -0
  28. package/dist/node/lint.d.ts.map +1 -0
  29. package/dist/node/lint.js +23 -0
  30. package/dist/node/lint.js.map +1 -0
  31. package/dist/node/mode.d.ts +9 -0
  32. package/dist/node/mode.d.ts.map +1 -0
  33. package/dist/node/mode.js +38 -0
  34. package/dist/node/mode.js.map +1 -0
  35. package/dist/node/theme.d.ts +13 -0
  36. package/dist/node/theme.d.ts.map +1 -0
  37. package/dist/node/theme.js +160 -0
  38. package/dist/node/theme.js.map +1 -0
  39. package/dist/types.d.ts +250 -0
  40. package/dist/types.d.ts.map +1 -0
  41. package/dist/types.js +80 -0
  42. package/dist/types.js.map +1 -0
  43. package/guide/acts.md +61 -0
  44. package/guide/audio.md +77 -0
  45. package/guide/blocks.md +82 -0
  46. package/guide/canvas-choosing.md +34 -0
  47. package/guide/canvas-editing.md +36 -0
  48. package/guide/canvas-layout.md +46 -0
  49. package/guide/canvas-opening.md +47 -0
  50. package/guide/canvas-overview.md +24 -0
  51. package/guide/canvas-states.md +37 -0
  52. package/guide/canvas-view.md +46 -0
  53. package/guide/canvas.md +94 -0
  54. package/guide/containers.md +60 -0
  55. package/guide/content.md +40 -0
  56. package/guide/controls.md +89 -0
  57. package/guide/density.md +48 -0
  58. package/guide/dock.md +42 -0
  59. package/guide/drag.md +38 -0
  60. package/guide/figures.md +25 -0
  61. package/guide/forms.md +82 -0
  62. package/guide/pane-bar.md +11 -0
  63. package/guide/pane.md +50 -0
  64. package/guide/reference.md +74 -0
  65. package/guide/rules.md +109 -0
  66. package/guide/section.md +29 -0
  67. package/guide/shell.md +26 -0
  68. package/guide/shots.md +37 -0
  69. package/guide/sidebar.md +30 -0
  70. package/guide/table.md +119 -0
  71. package/lint/no-arbitrary-value.grit +9 -0
  72. package/lint/no-class-on-component.grit +12 -0
  73. package/lint/no-density.grit +8 -0
  74. package/lint/no-host-look.grit +38 -0
  75. package/lint/no-img.grit +10 -0
  76. package/lint/no-navigate-act.grit +22 -0
  77. package/lint/no-raw-style.grit +8 -0
  78. package/package.json +150 -3
  79. package/src/density.ts +9 -0
  80. package/src/index.ts +503 -0
  81. package/src/node/canvas.ts +14 -0
  82. package/src/node/codegen.ts +100 -0
  83. package/src/node/css-escape.ts +27 -0
  84. package/src/node/fonts.ts +260 -0
  85. package/src/node/lint.ts +25 -0
  86. package/src/node/mode.ts +64 -0
  87. package/src/node/theme.ts +232 -0
  88. package/src/types.ts +120 -0
  89. package/src/ui/atoms/avatar/base.tsx +42 -0
  90. package/src/ui/atoms/button/glyph.tsx +244 -0
  91. package/src/ui/atoms/button/link.tsx +81 -0
  92. package/src/ui/atoms/button/look.ts +32 -0
  93. package/src/ui/atoms/button/reason.tsx +69 -0
  94. package/src/ui/atoms/chip/base.tsx +85 -0
  95. package/src/ui/atoms/count/base.tsx +27 -0
  96. package/src/ui/atoms/icon/index.tsx +51 -0
  97. package/src/ui/atoms/message/waiting.tsx +19 -0
  98. package/src/ui/atoms/prose/painted.tsx +35 -0
  99. package/src/ui/atoms/row/badges.tsx +226 -0
  100. package/src/ui/atoms/row/leading.tsx +166 -0
  101. package/src/ui/atoms/row/lock.tsx +17 -0
  102. package/src/ui/atoms/row/marks.tsx +79 -0
  103. package/src/ui/atoms/section/card.tsx +27 -0
  104. package/src/ui/atoms/spinner/index.tsx +42 -0
  105. package/src/ui/atoms/status/base.tsx +51 -0
  106. package/src/ui/atoms/status/change.tsx +29 -0
  107. package/src/ui/atoms/status/dot.tsx +45 -0
  108. package/src/ui/atoms/switch/checkbox.tsx +121 -0
  109. package/src/ui/atoms/turn.tsx +28 -0
  110. package/src/ui/components/action-bar/base.tsx +276 -0
  111. package/src/ui/components/action-bar/index.tsx +20 -0
  112. package/src/ui/components/avatar/index.tsx +21 -0
  113. package/src/ui/components/banner/index.tsx +207 -0
  114. package/src/ui/components/banner/pending.tsx +109 -0
  115. package/src/ui/components/bar-chart/index.tsx +701 -0
  116. package/src/ui/components/button/base.tsx +214 -0
  117. package/src/ui/components/button/face.tsx +84 -0
  118. package/src/ui/components/button/index.tsx +206 -0
  119. package/src/ui/components/canvas/connection.tsx +26 -0
  120. package/src/ui/components/canvas/edges.tsx +116 -0
  121. package/src/ui/components/canvas/elk.ts +260 -0
  122. package/src/ui/components/canvas/floor.ts +173 -0
  123. package/src/ui/components/canvas/geometry.ts +772 -0
  124. package/src/ui/components/canvas/ground.tsx +97 -0
  125. package/src/ui/components/canvas/group.tsx +156 -0
  126. package/src/ui/components/canvas/hit.ts +40 -0
  127. package/src/ui/components/canvas/index.tsx +497 -0
  128. package/src/ui/components/canvas/label.tsx +53 -0
  129. package/src/ui/components/canvas/layout.ts +543 -0
  130. package/src/ui/components/canvas/lift.ts +272 -0
  131. package/src/ui/components/canvas/look.ts +129 -0
  132. package/src/ui/components/canvas/node.tsx +689 -0
  133. package/src/ui/components/canvas/open.ts +243 -0
  134. package/src/ui/components/canvas/opening.ts +240 -0
  135. package/src/ui/components/canvas/view.ts +621 -0
  136. package/src/ui/components/canvas/viewport.ts +417 -0
  137. package/src/ui/components/canvas/zoom.tsx +113 -0
  138. package/src/ui/components/card/index.tsx +20 -0
  139. package/src/ui/components/chip/index.tsx +24 -0
  140. package/src/ui/components/code/frame.ts +2 -0
  141. package/src/ui/components/code/index.tsx +234 -0
  142. package/src/ui/components/columns/index.tsx +51 -0
  143. package/src/ui/components/count/index.tsx +17 -0
  144. package/src/ui/components/diff/index.tsx +249 -0
  145. package/src/ui/components/diff/word.tsx +104 -0
  146. package/src/ui/components/dock/index.tsx +262 -0
  147. package/src/ui/components/file-row/index.tsx +213 -0
  148. package/src/ui/components/form/base.tsx +280 -0
  149. package/src/ui/components/form/derive.tsx +269 -0
  150. package/src/ui/components/form/index.tsx +49 -0
  151. package/src/ui/components/form/saved.tsx +39 -0
  152. package/src/ui/components/form-field/index.tsx +658 -0
  153. package/src/ui/components/gallery/index.tsx +83 -0
  154. package/src/ui/components/gate/index.tsx +183 -0
  155. package/src/ui/components/image/base.tsx +245 -0
  156. package/src/ui/components/image/index.tsx +58 -0
  157. package/src/ui/components/input/base.tsx +246 -0
  158. package/src/ui/components/input/code.tsx +108 -0
  159. package/src/ui/components/input/drop.ts +37 -0
  160. package/src/ui/components/input/file.tsx +154 -0
  161. package/src/ui/components/input/index.tsx +132 -0
  162. package/src/ui/components/input/prose.tsx +107 -0
  163. package/src/ui/components/input/refusal.tsx +30 -0
  164. package/src/ui/components/item-header/base.tsx +410 -0
  165. package/src/ui/components/menu/base.tsx +319 -0
  166. package/src/ui/components/message/attachments.tsx +101 -0
  167. package/src/ui/components/message/base.tsx +266 -0
  168. package/src/ui/components/message-input/index.tsx +377 -0
  169. package/src/ui/components/missing/base.tsx +45 -0
  170. package/src/ui/components/pane/head.tsx +399 -0
  171. package/src/ui/components/pane/index.tsx +325 -0
  172. package/src/ui/components/picker/base.tsx +1551 -0
  173. package/src/ui/components/picker/index.tsx +224 -0
  174. package/src/ui/components/picker/list.tsx +423 -0
  175. package/src/ui/components/picker/segments.tsx +183 -0
  176. package/src/ui/components/prose/index.tsx +259 -0
  177. package/src/ui/components/qr-code/index.tsx +65 -0
  178. package/src/ui/components/row/acts.tsx +126 -0
  179. package/src/ui/components/row/fact.tsx +54 -0
  180. package/src/ui/components/row/index.tsx +1370 -0
  181. package/src/ui/components/row/progress.tsx +38 -0
  182. package/src/ui/components/row/status.tsx +54 -0
  183. package/src/ui/components/row/title.ts +7 -0
  184. package/src/ui/components/rules/index.tsx +290 -0
  185. package/src/ui/components/section/band.tsx +39 -0
  186. package/src/ui/components/section/head.tsx +267 -0
  187. package/src/ui/components/section/index.tsx +409 -0
  188. package/src/ui/components/section/rows.tsx +356 -0
  189. package/src/ui/components/sheet/base.tsx +272 -0
  190. package/src/ui/components/sheet/confirm.tsx +79 -0
  191. package/src/ui/components/sheet/docked.tsx +218 -0
  192. package/src/ui/components/sheet/form.tsx +76 -0
  193. package/src/ui/components/sheet/head.tsx +120 -0
  194. package/src/ui/components/sheet/index.tsx +45 -0
  195. package/src/ui/components/sheet/layer.tsx +168 -0
  196. package/src/ui/components/sheet/outlet.tsx +58 -0
  197. package/src/ui/components/sheet/task.tsx +41 -0
  198. package/src/ui/components/shell/cut.tsx +116 -0
  199. package/src/ui/components/shell/drag.tsx +45 -0
  200. package/src/ui/components/shell/host.tsx +71 -0
  201. package/src/ui/components/shell/index.tsx +737 -0
  202. package/src/ui/components/shell/panes.tsx +76 -0
  203. package/src/ui/components/shell/preview.ts +230 -0
  204. package/src/ui/components/shell/rail.tsx +163 -0
  205. package/src/ui/components/shell/row.ts +11 -0
  206. package/src/ui/components/shell/switcher.tsx +143 -0
  207. package/src/ui/components/shell/tree.tsx +252 -0
  208. package/src/ui/components/slider/base.tsx +139 -0
  209. package/src/ui/components/slider/index.tsx +57 -0
  210. package/src/ui/components/stages/index.tsx +198 -0
  211. package/src/ui/components/stats/count-links.tsx +47 -0
  212. package/src/ui/components/stats/index.tsx +203 -0
  213. package/src/ui/components/stats/meter.tsx +213 -0
  214. package/src/ui/components/stats/parts.ts +10 -0
  215. package/src/ui/components/step-count/index.tsx +45 -0
  216. package/src/ui/components/switch/base.tsx +86 -0
  217. package/src/ui/components/switch/index.tsx +38 -0
  218. package/src/ui/components/table/columns.tsx +131 -0
  219. package/src/ui/components/table/index.tsx +2215 -0
  220. package/src/ui/components/text/index.tsx +37 -0
  221. package/src/ui/components/thread/index.tsx +503 -0
  222. package/src/ui/components/thread/latest.tsx +59 -0
  223. package/src/ui/components/toast/index.tsx +113 -0
  224. package/src/ui/components/toast/layer.tsx +26 -0
  225. package/src/ui/components/toolbar/filters.tsx +161 -0
  226. package/src/ui/components/toolbar/index.tsx +125 -0
  227. package/src/ui/components/waveform/index.tsx +205 -0
  228. package/src/ui/globals.css +427 -0
  229. package/src/ui/lib/act.ts +60 -0
  230. package/src/ui/lib/age.ts +49 -0
  231. package/src/ui/lib/bound.ts +16 -0
  232. package/src/ui/lib/canvas-layout.ts +11 -0
  233. package/src/ui/lib/caret.ts +9 -0
  234. package/src/ui/lib/chip-lines.ts +3 -0
  235. package/src/ui/lib/closed.ts +8 -0
  236. package/src/ui/lib/code.tsx +184 -0
  237. package/src/ui/lib/columns.ts +39 -0
  238. package/src/ui/lib/commit.ts +24 -0
  239. package/src/ui/lib/container.ts +112 -0
  240. package/src/ui/lib/copy.ts +29 -0
  241. package/src/ui/lib/drag.ts +575 -0
  242. package/src/ui/lib/empty.tsx +85 -0
  243. package/src/ui/lib/field.ts +39 -0
  244. package/src/ui/lib/focus.ts +175 -0
  245. package/src/ui/lib/folds.ts +67 -0
  246. package/src/ui/lib/follow.ts +220 -0
  247. package/src/ui/lib/form.ts +19 -0
  248. package/src/ui/lib/guards.ts +38 -0
  249. package/src/ui/lib/heading.ts +14 -0
  250. package/src/ui/lib/ink.ts +26 -0
  251. package/src/ui/lib/lang.ts +7 -0
  252. package/src/ui/lib/leave.ts +14 -0
  253. package/src/ui/lib/lockup.tsx +145 -0
  254. package/src/ui/lib/measure.ts +22 -0
  255. package/src/ui/lib/media.ts +63 -0
  256. package/src/ui/lib/modality.ts +69 -0
  257. package/src/ui/lib/moment.ts +13 -0
  258. package/src/ui/lib/more.tsx +76 -0
  259. package/src/ui/lib/navigate.ts +210 -0
  260. package/src/ui/lib/noop.ts +3 -0
  261. package/src/ui/lib/not-found.tsx +40 -0
  262. package/src/ui/lib/paint.tsx +55 -0
  263. package/src/ui/lib/parts-line.tsx +54 -0
  264. package/src/ui/lib/picked.ts +18 -0
  265. package/src/ui/lib/player-store.ts +38 -0
  266. package/src/ui/lib/player.ts +139 -0
  267. package/src/ui/lib/portal.ts +12 -0
  268. package/src/ui/lib/read.tsx +269 -0
  269. package/src/ui/lib/region.tsx +49 -0
  270. package/src/ui/lib/reorder.ts +154 -0
  271. package/src/ui/lib/rest.ts +16 -0
  272. package/src/ui/lib/saved.ts +29 -0
  273. package/src/ui/lib/scramble.tsx +147 -0
  274. package/src/ui/lib/scrolls.ts +70 -0
  275. package/src/ui/lib/style.ts +6 -0
  276. package/src/ui/lib/swap.tsx +107 -0
  277. package/src/ui/lib/toast.ts +39 -0
  278. package/src/ui/lib/walk-classes.ts +16 -0
  279. package/src/ui/lib/window.tsx +376 -0
  280. package/src/ui/worker.d.ts +4 -0
@@ -0,0 +1,737 @@
1
+ import { Dialog } from "@base-ui/react/dialog";
2
+ import { cn } from "@slotform/ui-core/cn";
3
+ import type {
4
+ GroupSpec,
5
+ IconName,
6
+ PlaceSpec,
7
+ } from "@slotform/ui-core/descriptors";
8
+ import { BACK_GLYPH } from "@slotform/ui-core/list-state";
9
+ import { PAINT_ROWS } from "@slotform/ui-core/paint";
10
+ import { ShellHome } from "@slotform/ui-core/react/frame";
11
+ import {
12
+ FrameHolds,
13
+ useFrame,
14
+ useSelections,
15
+ } from "@slotform/ui-core/react/read";
16
+ import { useWords } from "@slotform/ui-core/react/words";
17
+ import {
18
+ type Datum,
19
+ isEnded,
20
+ isSelection,
21
+ paints,
22
+ } from "@slotform/ui-core/read";
23
+ import { flatPlaces, placeTrail, trailEnds } from "@slotform/ui-core/route";
24
+ import {
25
+ LAYER_CARD,
26
+ placeRow,
27
+ placeRowGlyph,
28
+ SHELL_BANNER,
29
+ SHELL_COLUMN,
30
+ SHELL_COLUMN_AT,
31
+ SHELL_COLUMN_FLOAT,
32
+ SHELL_COLUMN_MOTION,
33
+ SHELL_CONTAINER,
34
+ SHELL_FOOT,
35
+ SHELL_GROUP_LABEL,
36
+ SHELL_INSET,
37
+ SHELL_LAYER,
38
+ SHELL_LOCKUP,
39
+ SHELL_PAGE_SLIDE,
40
+ SHELL_PLACES,
41
+ SHELL_RAIL,
42
+ SHELL_RAIL_ENTRY,
43
+ SHELL_RAIL_GLYPH,
44
+ SHELL_RAIL_MOTION,
45
+ SHELL_RAIL_PANEL,
46
+ SHELL_RAIL_REGION,
47
+ SHELL_SIDEBAR,
48
+ SHELL_SIDEBAR_REGION,
49
+ SWITCHER_REGION,
50
+ text,
51
+ textStrong,
52
+ } from "@slotform/ui-core/variants";
53
+ import { type ReactNode, type Ref, useMemo, useState } from "react";
54
+ import { Icon } from "../../atoms/icon/index.tsx";
55
+ import type { Closed } from "../../lib/closed.ts";
56
+ import { PlaceTrail, ShellMenu } from "../../lib/container.ts";
57
+ import { useDocked } from "../../lib/folds.ts";
58
+ import { type AppLockup, useLockup } from "../../lib/lockup.tsx";
59
+ import { useTouch } from "../../lib/media.ts";
60
+ import { isRoute, useRoute } from "../../lib/navigate.ts";
61
+ import { PAINT_BOX, Painted } from "../../lib/paint.tsx";
62
+ import { FrameBody } from "../../lib/read.tsx";
63
+ import { Button } from "../button/index.tsx";
64
+ import { ContainerHost, ContainerMain } from "./host.tsx";
65
+ import { Panes } from "./panes.tsx";
66
+ import { usePreview } from "./preview.ts";
67
+ import { GroupRow, RailEntry } from "./rail.tsx";
68
+ import { GLYPH, LABEL, ROW_BOX } from "./row.ts";
69
+ import { type Switcher, SwitcherPick } from "./switcher.tsx";
70
+ import { PlaceTree } from "./tree.tsx";
71
+
72
+ // A page read from across a room draws its own room `Panes` outside the Shell.
73
+ export { Panes };
74
+
75
+ // The shell fills the viewport; the page inside scrolls its own body.
76
+ const BOX = "flex h-dvh overflow-hidden";
77
+ const SIDEBAR = "relative flex flex-col shrink-0 min-h-0";
78
+ // The switcher region is a bar: its row centred in the strip, the close act
79
+ // (on the touch layer) at its end.
80
+ const REGION = "flex shrink-0 items-center gap-gap";
81
+ const PLACES = "flex flex-col";
82
+ const GROUP = "flex flex-col";
83
+ // With groups the sidebar is one body over the room the frame keeps for it:
84
+ // the rail, its entries scrolling above its footer places, and the column.
85
+ const SPLIT = "relative flex shrink-0 min-h-0";
86
+ const RAIL_ENTRIES = "flex flex-col gap-gap grow min-h-0 overflow-y-auto";
87
+ // The body lets the page take presses where nothing of it stands: the rail
88
+ // always takes them, the column only while it is open (`SHELL_COLUMN_MOTION`).
89
+ const RAIL_HIT = "pointer-events-auto";
90
+ const COLUMN_BODY = "flex flex-col min-h-0";
91
+ // The place's part of the page, which slides as the sidebar docks or folds;
92
+ // the place grows in it as it does in `main`.
93
+ const PAGE = "flex flex-col grow min-h-0 min-w-0";
94
+ const FOOT = "shrink-0";
95
+ const RAIL_FOOT = "flex flex-col gap-gap shrink-0 pt-gap";
96
+ // The touch group view's head: the way back to the groups, then the heading.
97
+ const BACK = "flex items-center gap-gap";
98
+ // The column clears the top safe inset, so a banner or a page's head never
99
+ // stands under a notch.
100
+ const COLUMN = "relative flex flex-col min-w-0 grow pt-safe";
101
+ const BANNER_REGION = "flex flex-col";
102
+ // The app's name beside its mark when the shell has no switcher.
103
+ const NAME = "truncate";
104
+ // The touch places layer stands over the whole viewport on the sheet's rung;
105
+ // its places scroll as the sidebar's do.
106
+ const LAYER = "fixed inset-0 z-(--layer-sheet) flex flex-col";
107
+ const CLOSE = "ms-auto";
108
+
109
+ /** A group of places the sidebar names: its label (beside its icon on the docked or open rail, and the heading of its places on the touch layer), its icon (its entry on the rail), its switcher when it is a scope, and its places when a read gives them. */
110
+ export interface ShellGroup extends Omit<GroupSpec, "switcher"> {
111
+ /** The scope the group's places follow: it leads the group's column level with the app's switcher, and on the touch layer it stands under the heading. */
112
+ switcher?: Switcher;
113
+ /** The group's places, constants or a selection: the group stands where it stands in `groups`, whose order is the rail's: before the first plain group of places whose group `groups` lists after it, else after the plain ones. While the selection waits the heading draws over `PAINT_ROWS` painted place rows, inert; once it failed or is missing the group is the read's frame and draws the compact failed or missing shape with Retry in the rows' place (so the read counts as held and its failure is drawn once), and when it is loaded and empty the group draws no places, its `switcher` standing alone so its act can make the first. The group's `switcher` selections of the same read need no frame of their own. */
114
+ places?: Datum<readonly PlaceSpec[]>;
115
+ }
116
+
117
+ /** The app's frame. */
118
+ export interface ShellProps extends Closed {
119
+ /** The places, in order; the one at the current route is selected. */
120
+ places: readonly PlaceSpec[];
121
+ /** The groups, in the rail's order: every group a place names, which a place naming one `groups` does not list throws for, and the ones that carry a switcher or a read of their own (a group of its own stands before the plain group listed after it). A Shell that names any group draws a rail of them beside the column; one that names none draws the column alone. */
122
+ groups?: readonly ShellGroup[];
123
+ /** A `Banner` over the column, at the page inset. */
124
+ banner?: ReactNode;
125
+ /** What the app is looking at, and what it can switch to. */
126
+ switcher?: Switcher;
127
+ /** A part that stands under the place across the column (a `Dock`), whatever the route; without one the Shell draws nothing there. */
128
+ foot?: ReactNode;
129
+ /** The route's Panes, in order: each deeper one a step into what the one before it lists. */
130
+ children?: ReactNode;
131
+ }
132
+
133
+ /** The frame, with the route's Panes in a row (the place) on its canvas: the place's Pane, and a record's after it, the place's then at the list width giving way to its floor and the record's taking the rest, a hairline between them, and below `tablet` of the column only the last standing. A route renders its `Pane`s and no place of its own. A `foot` stands under the place across the column. On the desktop the sidebar beside the column: the mark and the switcher on one bar, then the places, a group's switcher under its heading. A Shell that names groups draws the sidebar as a rail of icon entries (the ungrouped places first, named by their first place, then each group, a press going to the group's first place; the footer places and the act that folds or docks the column at the rail's foot) beside the column of the current place's group, the app's switcher leading the rail and the group's leading the column level with it (an empty region for a group with none), so the column's first place stands level with the rail's first entry. Docked (the default) the rail stands wide with each entry's label and the column beside it in the frame's flow, and a pointer resting on an entry or a focus on it shows that group in the column; folded to the rail (the viewer's choice, kept from one visit to the next), the rail is its icons, the app's switcher its mark, and the sidebar opens over the page instead, each entry's label uncovered and that column sliding out beside it. The sidebar opens and shuts as one body on `base`, by clip and transform (snapping under reduced motion), and as the viewer docks or folds it the page slides from where it stood, its edge on the sidebar's end. The footer places and the dock act show nothing on hover or focus. A pointer heading for the column keeps the group shown while it crosses other entries; the column goes back once the pointer and the focus have left the rail and the column a moment, on Escape or when the route changes, and a menu or a sheet the column opened holds it while it is open. On touch the column alone, the same places on a layer over the viewport that the menu act leading a Pane's bar opens (the groups first, a tap showing a group's places with a way back) and that closes on its close act, Escape or going to a place. */
134
+ export function Shell({
135
+ places,
136
+ groups,
137
+ banner,
138
+ switcher,
139
+ foot,
140
+ children,
141
+ }: ShellProps) {
142
+ const touch = useTouch();
143
+ const words = useWords();
144
+ const at = useRoute();
145
+ // The places layer stands at the route it opened on: going to a place
146
+ // closes it.
147
+ const [openAt, setOpenAt] = useState<string>();
148
+ const open = openAt === at;
149
+ // The current place is the one that owns the address among every place the
150
+ // sidebar draws, a group's own included. The lookup is an enrichment, never
151
+ // a draw of the read's state: it reads quietly (`or`), so it paints and holds
152
+ // nothing, and a group whose places wait or failed contributes no candidate.
153
+ const owned = useMemo(
154
+ () =>
155
+ (groups ?? []).map((group) =>
156
+ isSelection(group.places) ? group.places.or([]) : (group.places ?? []),
157
+ ),
158
+ [groups],
159
+ );
160
+ const drawn = useSelections(owned);
161
+ const grouped = drawn.flatMap((each) => (each.painted ? [] : each.value));
162
+ const spec = [...places, ...grouped];
163
+ // A place's children are places too: the address is owned by the deepest,
164
+ // the trail's last.
165
+ const trail = placeTrail(spec, at);
166
+ const { here } = trailEnds(trail);
167
+ const route = here?.route;
168
+ const lockup = useLockup();
169
+ // A place that is a spot on its page (`#activity`) leads nowhere from an
170
+ // address nothing serves, so home is the first place that is a route.
171
+ const first = places.find((spec) => isRoute(spec.route));
172
+ const home = first && { label: first.label, href: first.route };
173
+ const close = () => setOpenAt(undefined);
174
+ const lead = leadOf(switcher, lockup);
175
+ const rows = groupsOf(places, groups);
176
+ const railed = (groups?.length ?? 0) > 0 || places.some((one) => one.group);
177
+ const entries = railed ? rail(rows, groups) : [];
178
+ const ends = places.filter((one) => one.end);
179
+ // The group the current place stands in: a place of the rows, else a place
180
+ // a group's own read gave. None for a footer place, or none at the address.
181
+ const owner = railed ? ownerOf(places, groups, drawn, route) : undefined;
182
+ const [docked, dock] = useDocked();
183
+ // A group's entry goes to its group's first place that is a route: a place
184
+ // of its groups, else the first its group's read gave, none while it waits.
185
+ const firstOf = (entry: Entry) => {
186
+ const first = entry.groups[0];
187
+ const at = (groups ?? []).findIndex((one) => one.label === first?.group);
188
+ const read = first?.read ? drawn[at] : undefined;
189
+ const specs = read
190
+ ? read.painted
191
+ ? []
192
+ : read.value
193
+ : (first?.places ?? []);
194
+ return specs.find((one) => isRoute(one.route))?.route;
195
+ };
196
+ // Docked (the default), the body stands open in the room the frame keeps
197
+ // for it; folded, the frame keeps the strip's room and a preview opens the
198
+ // body over the page. The viewer's dock or fold slides the page from where
199
+ // it stood (`slide`) until its slide ends.
200
+ const [slide, setSlide] = useState<"dock" | "fold">();
201
+ const preview = usePreview({
202
+ at,
203
+ docked,
204
+ owner,
205
+ entries: entries.map((one) => one.key),
206
+ });
207
+ const shown = entries.find((one) => one.key === preview.shown);
208
+ const held = entries.find((one) => one.key === preview.held);
209
+ const expanded = docked || shown !== undefined ? "" : undefined;
210
+ // The group the touch layer shows, once one is tapped: none each time it opens.
211
+ const [viewed, setViewed] = useState<string>();
212
+ const viewing = entries.find((one) => one.key === viewed);
213
+ const common = {
214
+ route,
215
+ trail,
216
+ onPlace: touch ? close : undefined,
217
+ };
218
+ const closer = touch ? (
219
+ <span className={CLOSE}>
220
+ <Button glyph icon="X" label={words.close} onAct={close} />
221
+ </span>
222
+ ) : undefined;
223
+ const plain = (
224
+ <PlacesBody lead={lead} ends={ends} end={closer} {...common}>
225
+ <Groups rows={rows} {...common} />
226
+ </PlacesBody>
227
+ );
228
+ const listed = (
229
+ <PlacesBody lead={lead} ends={ends} end={closer} {...common}>
230
+ {viewing === undefined ? (
231
+ <div className={cn(SHELL_PLACES, PLACES)}>
232
+ {entries.map((one) => (
233
+ <GroupRow
234
+ key={one.key}
235
+ icon={one.icon}
236
+ label={one.label}
237
+ current={one.key === owner}
238
+ onPress={() => setViewed(one.key)}
239
+ />
240
+ ))}
241
+ </div>
242
+ ) : (
243
+ <>
244
+ <div className={BACK}>
245
+ <Button
246
+ glyph
247
+ icon={BACK_GLYPH}
248
+ label={words.back}
249
+ onAct={() => setViewed(undefined)}
250
+ />
251
+ {viewing.group === undefined ? null : (
252
+ <Heading label={viewing.label} />
253
+ )}
254
+ </div>
255
+ {viewing.switcher ? (
256
+ <SwitcherPick switcher={viewing.switcher} />
257
+ ) : null}
258
+ <Groups rows={viewing.groups} {...common} />
259
+ </>
260
+ )}
261
+ </PlacesBody>
262
+ );
263
+ // The rail's entries scroll above its footer places and the dock act; the
264
+ // column stands beside it, docked or over the page. The app's switcher
265
+ // leads the rail, and coming onto it shows the current place's group; the
266
+ // group's switcher leads the column, in a region of its own whether or not
267
+ // the group has one.
268
+ const current = owner ?? entries[0]?.key;
269
+ const railLead = railed
270
+ ? leadOf(switcher, lockup, (wait) => {
271
+ if (current !== undefined) preview.point(current, wait);
272
+ })
273
+ : null;
274
+ // Footer entries carry their label as a tooltip while the rail draws none.
275
+ const named = expanded === undefined;
276
+ const railing = (
277
+ <nav
278
+ aria-label={words.places}
279
+ className={cn(SPLIT, docked ? SHELL_SIDEBAR_REGION : SHELL_RAIL_REGION)}
280
+ {...preview.nav}
281
+ >
282
+ <div className={SHELL_RAIL_PANEL}>
283
+ <div
284
+ data-expanded={expanded}
285
+ className={cn(
286
+ SHELL_RAIL,
287
+ SHELL_INSET,
288
+ SIDEBAR,
289
+ SHELL_RAIL_MOTION,
290
+ RAIL_HIT,
291
+ )}
292
+ >
293
+ <div className={cn(SWITCHER_REGION, REGION)}>{railLead}</div>
294
+ <div className={RAIL_ENTRIES}>
295
+ {entries.map((one) => (
296
+ <RailEntry
297
+ key={one.key}
298
+ icon={one.icon}
299
+ label={one.label}
300
+ current={one.key === owner ? "true" : undefined}
301
+ shown={one === shown}
302
+ href={firstOf(one)}
303
+ onExpand={(wait) => preview.point(one.key, wait)}
304
+ onLeave={preview.hold}
305
+ />
306
+ ))}
307
+ </div>
308
+ {/* The footer places and the dock act preview nothing: a pointer
309
+ reaching for them leaves the column as it stands, a group
310
+ crossed on the way included. */}
311
+ <div className={RAIL_FOOT}>
312
+ {ends.map((one) => (
313
+ <RailEntry
314
+ key={one.route}
315
+ icon={one.icon}
316
+ label={one.label}
317
+ current={one.route === route ? "page" : undefined}
318
+ href={one.route}
319
+ named={named}
320
+ onExpand={preview.hold}
321
+ />
322
+ ))}
323
+ <RailEntry
324
+ icon={docked ? "PanelLeftClose" : "PanelLeftOpen"}
325
+ label={docked ? words.foldSidebar : words.dockSidebar}
326
+ named={named}
327
+ onExpand={preview.hold}
328
+ // Folding shuts the body on what it shows; docking keeps
329
+ // the preview where the pointer has it.
330
+ onPress={() => {
331
+ if (docked) preview.back();
332
+ setSlide(docked ? "fold" : "dock");
333
+ dock(!docked);
334
+ }}
335
+ />
336
+ </div>
337
+ </div>
338
+ {held ? (
339
+ <div
340
+ data-expanded={expanded}
341
+ className={cn(
342
+ SHELL_SIDEBAR,
343
+ SHELL_INSET,
344
+ SHELL_COLUMN_AT,
345
+ COLUMN_BODY,
346
+ SHELL_COLUMN_MOTION,
347
+ !docked && SHELL_COLUMN_FLOAT,
348
+ )}
349
+ onPointerEnter={preview.column.onPointerEnter}
350
+ >
351
+ <div className={cn(SWITCHER_REGION, REGION)}>
352
+ {held.switcher ? <SwitcherPick switcher={held.switcher} /> : null}
353
+ </div>
354
+ <Groups
355
+ ref={preview.column.places}
356
+ rows={held.groups}
357
+ {...common}
358
+ />
359
+ </div>
360
+ ) : null}
361
+ </div>
362
+ </nav>
363
+ );
364
+ // The sidebar and the layer differ by density; the column, and the page
365
+ // in it, keep one tree position on both, so crossing the density line
366
+ // keeps the page.
367
+ const body = railed ? listed : plain;
368
+ const sidebar = touch ? null : railed ? (
369
+ railing
370
+ ) : (
371
+ <nav
372
+ aria-label={words.places}
373
+ className={cn(SHELL_SIDEBAR, SHELL_INSET, SIDEBAR)}
374
+ >
375
+ {body}
376
+ </nav>
377
+ );
378
+ const layer = touch ? (
379
+ <Dialog.Root
380
+ open={open}
381
+ onOpenChange={(next) => {
382
+ if (!next) close();
383
+ }}
384
+ modal
385
+ >
386
+ <Dialog.Portal>
387
+ <Dialog.Popup
388
+ aria-label={words.places}
389
+ className={cn(SHELL_LAYER, LAYER, LAYER_CARD)}
390
+ >
391
+ <nav
392
+ aria-label={words.places}
393
+ className={cn(SHELL_INSET, SIDEBAR, "grow")}
394
+ >
395
+ {body}
396
+ </nav>
397
+ </Dialog.Popup>
398
+ </Dialog.Portal>
399
+ </Dialog.Root>
400
+ ) : null;
401
+ const menu = touch
402
+ ? {
403
+ icon: "Menu" as const,
404
+ label: words.places,
405
+ onAct: () => {
406
+ setOpenAt(at);
407
+ setViewed(undefined);
408
+ },
409
+ }
410
+ : undefined;
411
+ return (
412
+ <ContainerHost>
413
+ <div
414
+ data-slide={slide}
415
+ className={cn(BOX, SHELL_CONTAINER)}
416
+ onAnimationEnd={(event) => {
417
+ if (event.animationName === "page-slide") setSlide(undefined);
418
+ }}
419
+ >
420
+ {sidebar}
421
+ <div className={cn(SHELL_COLUMN, COLUMN)}>
422
+ {banner ? (
423
+ <div className={cn(SHELL_BANNER, BANNER_REGION, SHELL_PAGE_SLIDE)}>
424
+ {banner}
425
+ </div>
426
+ ) : null}
427
+ <ContainerMain>
428
+ <ShellHome value={home}>
429
+ <ShellMenu value={menu}>
430
+ <PlaceTrail value={trail}>
431
+ <div className={cn(PAGE, SHELL_PAGE_SLIDE)}>
432
+ <Panes title={here?.label ?? lockup?.name}>
433
+ {children}
434
+ </Panes>
435
+ </div>
436
+ </PlaceTrail>
437
+ </ShellMenu>
438
+ </ShellHome>
439
+ </ContainerMain>
440
+ {foot ? (
441
+ <div className={cn(FOOT, SHELL_PAGE_SLIDE)}>{foot}</div>
442
+ ) : null}
443
+ {layer}
444
+ </div>
445
+ </div>
446
+ </ContainerHost>
447
+ );
448
+ }
449
+
450
+ // The switcher region's lead: the app's switcher with the mark in its glyph
451
+ // region, else the mark and the app's name. On the rail (`onRail`, which a
452
+ // pointer coming onto the switcher or a focus calls) the glyph keeps its control
453
+ // square and the rest is uncovered with the rail's labels.
454
+ function leadOf(
455
+ switcher: Switcher | undefined,
456
+ lockup: AppLockup | null,
457
+ onRail?: (wait: boolean) => void,
458
+ ): ReactNode {
459
+ const rail = onRail !== undefined;
460
+ // The sidebar is the dark calibration in both modes: the dark icon stands.
461
+ const glyph = lockup ? (
462
+ <img src={lockup.dark ?? lockup.src} alt="" className={SHELL_LOCKUP} />
463
+ ) : undefined;
464
+ if (switcher)
465
+ return <SwitcherPick switcher={switcher} glyph={glyph} onExpand={onRail} />;
466
+ if (!lockup) return null;
467
+ return (
468
+ <span className={cn(placeRow(), ROW_BOX, rail && SHELL_RAIL_ENTRY)}>
469
+ <span className={cn(placeRowGlyph(), GLYPH, rail && SHELL_RAIL_GLYPH)}>
470
+ {glyph}
471
+ </span>
472
+ <span
473
+ className={cn(
474
+ text({ role: "body" }),
475
+ textStrong({ role: "body" }),
476
+ NAME,
477
+ )}
478
+ >
479
+ {lockup.name}
480
+ </span>
481
+ </span>
482
+ );
483
+ }
484
+
485
+ // The sidebar's content, drawn in the sidebar and on the touch layer alike:
486
+ // the switcher region (the mark in the row's glyph region, the switcher's trigger
487
+ // after it, `end` at the bar's end), what the caller puts under it (the groups
488
+ // of places, or a group's heading over its places) and the footer places.
489
+ function PlacesBody(props: {
490
+ lead?: ReactNode;
491
+ ends: readonly PlaceSpec[];
492
+ route: string | undefined;
493
+ trail: readonly PlaceSpec[];
494
+ end?: ReactNode;
495
+ onPlace?: () => void;
496
+ children?: ReactNode;
497
+ }) {
498
+ const { lead, ends, route, trail, end, onPlace, children } = props;
499
+ const words = useWords();
500
+ return (
501
+ <>
502
+ {lead || end ? (
503
+ <div className={cn(SWITCHER_REGION, REGION)}>
504
+ {lead}
505
+ {end}
506
+ </div>
507
+ ) : null}
508
+ {children}
509
+ {ends.length > 0 ? (
510
+ <div className={cn(SHELL_FOOT, GROUP)}>
511
+ <PlaceTree
512
+ specs={ends}
513
+ label={words.places}
514
+ route={route}
515
+ trail={trail}
516
+ onPlace={onPlace}
517
+ />
518
+ </div>
519
+ ) : null}
520
+ </>
521
+ );
522
+ }
523
+
524
+ // The groups of places, scrolling between the switcher bar and the footer.
525
+ function Groups(props: {
526
+ // The column's places, which a pointer heading for them aims at.
527
+ ref?: Ref<HTMLDivElement>;
528
+ rows: readonly Group[];
529
+ route: string | undefined;
530
+ trail: readonly PlaceSpec[];
531
+ onPlace?: () => void;
532
+ }) {
533
+ const { ref, rows, route, trail, onPlace } = props;
534
+ return (
535
+ <div ref={ref} className={cn(SHELL_PLACES, PLACES)}>
536
+ {rows.map((one) => (
537
+ <GroupPlaces
538
+ key={one.key}
539
+ label={one.group}
540
+ places={one.read ?? one.places}
541
+ route={route}
542
+ trail={trail}
543
+ onPlace={onPlace}
544
+ />
545
+ ))}
546
+ </div>
547
+ );
548
+ }
549
+
550
+ function Heading({ label }: { label: string }) {
551
+ return (
552
+ <span className={cn(text({ role: "caption" }), SHELL_GROUP_LABEL)}>
553
+ {label}
554
+ </span>
555
+ );
556
+ }
557
+
558
+ type Group = {
559
+ key: string;
560
+ group?: string;
561
+ name: string;
562
+ icon: IconName;
563
+ places: PlaceSpec[];
564
+ read?: Datum<readonly PlaceSpec[]>;
565
+ };
566
+
567
+ // The sidebar draws the places of one group as a `Group`: docs/architecture/ui-core/layout.md, "Sidebar and groups".
568
+ function groupsOf(
569
+ places: readonly PlaceSpec[],
570
+ groups: readonly ShellGroup[] | undefined,
571
+ ) {
572
+ const out: Group[] = [];
573
+ const listed = groups ?? [];
574
+ for (const spec of places) {
575
+ if (spec.end) continue;
576
+ const last = out.at(-1);
577
+ if (last && last.group === spec.group) {
578
+ last.places.push(spec);
579
+ continue;
580
+ }
581
+ const group = listed.find((one) => one.label === spec.group);
582
+ if (spec.group !== undefined && !group)
583
+ throw new Error(
584
+ `Shell: the group "${spec.group}" of the place "${spec.label}" is not in \`groups\``,
585
+ );
586
+ out.push({
587
+ key: spec.route,
588
+ group: spec.group,
589
+ name: group?.label ?? spec.label,
590
+ icon: group?.icon ?? spec.icon,
591
+ places: [spec],
592
+ });
593
+ }
594
+ listed.forEach((spec, at) => {
595
+ if (!spec.places) return;
596
+ const after = listed.slice(at + 1).map((one) => one.label);
597
+ const before = out.findIndex(
598
+ (one) => one.group !== undefined && after.includes(one.group),
599
+ );
600
+ out.splice(before < 0 ? out.length : before, 0, {
601
+ key: `group:${spec.label}`,
602
+ group: spec.label,
603
+ name: spec.label,
604
+ icon: spec.icon,
605
+ places: [],
606
+ read: spec.places,
607
+ });
608
+ });
609
+ return out;
610
+ }
611
+
612
+ // A group on the rail: all its groups, named and drawn by its group, or for the
613
+ // ungrouped places by their first place, and its group's switcher, which leads
614
+ // its places. `key` names it apart from every other entry, the ungrouped
615
+ // places' included.
616
+ interface Entry {
617
+ key: string;
618
+ group: string | undefined;
619
+ label: string;
620
+ icon: IconName;
621
+ switcher: Switcher | undefined;
622
+ groups: Group[];
623
+ }
624
+
625
+ const UNGROUPED = "";
626
+ const entryKey = (group: string | undefined) =>
627
+ group === undefined ? UNGROUPED : `group:${group}`;
628
+
629
+ // The rail's entries: the ungrouped places first, then each group in the order
630
+ // of its first group.
631
+ function rail(
632
+ rows: readonly Group[],
633
+ groups: readonly ShellGroup[] | undefined,
634
+ ): Entry[] {
635
+ const out: Entry[] = [];
636
+ for (const each of rows) {
637
+ let entry = out.find((one) => one.group === each.group);
638
+ if (!entry) {
639
+ entry = {
640
+ key: entryKey(each.group),
641
+ group: each.group,
642
+ label: each.name,
643
+ icon: each.icon,
644
+ switcher: groups?.find((one) => one.label === each.group)?.switcher,
645
+ groups: [],
646
+ };
647
+ out.push(entry);
648
+ }
649
+ entry.groups.push(each);
650
+ }
651
+ return [
652
+ ...out.filter((one) => one.group === undefined),
653
+ ...out.filter((one) => one.group !== undefined),
654
+ ];
655
+ }
656
+
657
+ // The key of the rail entry the place at `route` stands in: a place of
658
+ // `places`, else one a group's own read gave. None for a footer place or no
659
+ // place.
660
+ function ownerOf(
661
+ places: readonly PlaceSpec[],
662
+ groups: readonly ShellGroup[] | undefined,
663
+ drawn: readonly (
664
+ | { painted: true }
665
+ | { painted: false; value: readonly PlaceSpec[] }
666
+ )[],
667
+ route: string | undefined,
668
+ ): string | undefined {
669
+ const holds = (specs: readonly PlaceSpec[]) =>
670
+ flatPlaces(specs).some((one) => one.route === route);
671
+ const own = places.find((one) => !one.end && holds([one]));
672
+ if (own) return entryKey(own.group);
673
+ const read = drawn.findIndex((each) => !each.painted && holds(each.value));
674
+ const group = groups?.[read]?.label;
675
+ return group === undefined ? undefined : entryKey(group);
676
+ }
677
+
678
+ const PAINTED_PLACES = Array.from({ length: PAINT_ROWS }, (_, at) => at);
679
+
680
+ // One group's places (`label` their group, which names their list), or
681
+ // `PAINT_ROWS` painted rows at the row height while their read waits.
682
+ function GroupPlaces(props: {
683
+ label: string | undefined;
684
+ places: Datum<readonly PlaceSpec[]>;
685
+ route: string | undefined;
686
+ trail: readonly PlaceSpec[];
687
+ onPlace?: () => void;
688
+ }) {
689
+ const { label, route, trail, onPlace } = props;
690
+ const words = useWords();
691
+ const [drawn] = useSelections([props.places] as const);
692
+ // The group is the frame of its places' read: it holds it, so the read's
693
+ // failure is drawn once, here, in the compact failed and missing shapes.
694
+ const frame = useFrame(isSelection(props.places) ? props.places : undefined);
695
+ const waits = paints(drawn);
696
+ const specs = drawn.painted ? [] : drawn.value;
697
+ const ended = isEnded(frame.shape);
698
+ if (!(waits || ended) && specs.length === 0) return null;
699
+ return (
700
+ <FrameHolds holds={frame.held}>
701
+ <div className={GROUP} aria-busy={(waits && frame.holds) || undefined}>
702
+ {ended ? (
703
+ <FrameBody frame={frame} fit="part" />
704
+ ) : waits ? (
705
+ PAINTED_PLACES.map((at) => (
706
+ <PaintedPlace key={`painted:${at}`} at={at} />
707
+ ))
708
+ ) : (
709
+ <PlaceTree
710
+ specs={specs}
711
+ label={label ?? words.places}
712
+ route={route}
713
+ trail={trail}
714
+ onPlace={onPlace}
715
+ />
716
+ )}
717
+ </div>
718
+ </FrameHolds>
719
+ );
720
+ }
721
+
722
+ // A place row while its read waits: the row's box, its glyph region and its
723
+ // label painted.
724
+ function PaintedPlace({ at }: { at: number }) {
725
+ return (
726
+ <span inert aria-hidden className={cn(placeRow(), ROW_BOX)}>
727
+ <span className={cn(placeRowGlyph(), GLYPH)}>
728
+ <span className={cn(PAINT_BOX, "*:invisible")}>
729
+ <Icon name="Square" />
730
+ </span>
731
+ </span>
732
+ <span className={cn(text({ role: "body" }), LABEL)}>
733
+ <Painted role="phrase" at={at} />
734
+ </span>
735
+ </span>
736
+ );
737
+ }