@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.
- package/LICENSE +21 -0
- package/README.md +44 -2
- package/dist/density.d.ts +4 -0
- package/dist/density.d.ts.map +1 -0
- package/dist/density.js +8 -0
- package/dist/density.js.map +1 -0
- package/dist/index.d.ts +400 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +388 -0
- package/dist/index.js.map +1 -0
- package/dist/node/canvas.d.ts +3 -0
- package/dist/node/canvas.d.ts.map +1 -0
- package/dist/node/canvas.js +13 -0
- package/dist/node/canvas.js.map +1 -0
- package/dist/node/codegen.d.ts +6 -0
- package/dist/node/codegen.d.ts.map +1 -0
- package/dist/node/codegen.js +70 -0
- package/dist/node/codegen.js.map +1 -0
- package/dist/node/css-escape.d.ts +8 -0
- package/dist/node/css-escape.d.ts.map +1 -0
- package/dist/node/css-escape.js +12 -0
- package/dist/node/css-escape.js.map +1 -0
- package/dist/node/fonts.d.ts +6 -0
- package/dist/node/fonts.d.ts.map +1 -0
- package/dist/node/fonts.js +219 -0
- package/dist/node/fonts.js.map +1 -0
- package/dist/node/lint.d.ts +3 -0
- package/dist/node/lint.d.ts.map +1 -0
- package/dist/node/lint.js +23 -0
- package/dist/node/lint.js.map +1 -0
- package/dist/node/mode.d.ts +9 -0
- package/dist/node/mode.d.ts.map +1 -0
- package/dist/node/mode.js +38 -0
- package/dist/node/mode.js.map +1 -0
- package/dist/node/theme.d.ts +13 -0
- package/dist/node/theme.d.ts.map +1 -0
- package/dist/node/theme.js +160 -0
- package/dist/node/theme.js.map +1 -0
- package/dist/types.d.ts +250 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +80 -0
- package/dist/types.js.map +1 -0
- package/guide/acts.md +61 -0
- package/guide/audio.md +77 -0
- package/guide/blocks.md +82 -0
- package/guide/canvas-choosing.md +34 -0
- package/guide/canvas-editing.md +36 -0
- package/guide/canvas-layout.md +46 -0
- package/guide/canvas-opening.md +47 -0
- package/guide/canvas-overview.md +24 -0
- package/guide/canvas-states.md +37 -0
- package/guide/canvas-view.md +46 -0
- package/guide/canvas.md +94 -0
- package/guide/containers.md +60 -0
- package/guide/content.md +40 -0
- package/guide/controls.md +89 -0
- package/guide/density.md +48 -0
- package/guide/dock.md +42 -0
- package/guide/drag.md +38 -0
- package/guide/figures.md +25 -0
- package/guide/forms.md +82 -0
- package/guide/pane-bar.md +11 -0
- package/guide/pane.md +50 -0
- package/guide/reference.md +74 -0
- package/guide/rules.md +109 -0
- package/guide/section.md +29 -0
- package/guide/shell.md +26 -0
- package/guide/shots.md +37 -0
- package/guide/sidebar.md +30 -0
- package/guide/table.md +119 -0
- package/lint/no-arbitrary-value.grit +9 -0
- package/lint/no-class-on-component.grit +12 -0
- package/lint/no-density.grit +8 -0
- package/lint/no-host-look.grit +38 -0
- package/lint/no-img.grit +10 -0
- package/lint/no-navigate-act.grit +22 -0
- package/lint/no-raw-style.grit +8 -0
- package/package.json +150 -3
- package/src/density.ts +9 -0
- package/src/index.ts +503 -0
- package/src/node/canvas.ts +14 -0
- package/src/node/codegen.ts +100 -0
- package/src/node/css-escape.ts +27 -0
- package/src/node/fonts.ts +260 -0
- package/src/node/lint.ts +25 -0
- package/src/node/mode.ts +64 -0
- package/src/node/theme.ts +232 -0
- package/src/types.ts +120 -0
- package/src/ui/atoms/avatar/base.tsx +42 -0
- package/src/ui/atoms/button/glyph.tsx +244 -0
- package/src/ui/atoms/button/link.tsx +81 -0
- package/src/ui/atoms/button/look.ts +32 -0
- package/src/ui/atoms/button/reason.tsx +69 -0
- package/src/ui/atoms/chip/base.tsx +85 -0
- package/src/ui/atoms/count/base.tsx +27 -0
- package/src/ui/atoms/icon/index.tsx +51 -0
- package/src/ui/atoms/message/waiting.tsx +19 -0
- package/src/ui/atoms/prose/painted.tsx +35 -0
- package/src/ui/atoms/row/badges.tsx +226 -0
- package/src/ui/atoms/row/leading.tsx +166 -0
- package/src/ui/atoms/row/lock.tsx +17 -0
- package/src/ui/atoms/row/marks.tsx +79 -0
- package/src/ui/atoms/section/card.tsx +27 -0
- package/src/ui/atoms/spinner/index.tsx +42 -0
- package/src/ui/atoms/status/base.tsx +51 -0
- package/src/ui/atoms/status/change.tsx +29 -0
- package/src/ui/atoms/status/dot.tsx +45 -0
- package/src/ui/atoms/switch/checkbox.tsx +121 -0
- package/src/ui/atoms/turn.tsx +28 -0
- package/src/ui/components/action-bar/base.tsx +276 -0
- package/src/ui/components/action-bar/index.tsx +20 -0
- package/src/ui/components/avatar/index.tsx +21 -0
- package/src/ui/components/banner/index.tsx +207 -0
- package/src/ui/components/banner/pending.tsx +109 -0
- package/src/ui/components/bar-chart/index.tsx +701 -0
- package/src/ui/components/button/base.tsx +214 -0
- package/src/ui/components/button/face.tsx +84 -0
- package/src/ui/components/button/index.tsx +206 -0
- package/src/ui/components/canvas/connection.tsx +26 -0
- package/src/ui/components/canvas/edges.tsx +116 -0
- package/src/ui/components/canvas/elk.ts +260 -0
- package/src/ui/components/canvas/floor.ts +173 -0
- package/src/ui/components/canvas/geometry.ts +772 -0
- package/src/ui/components/canvas/ground.tsx +97 -0
- package/src/ui/components/canvas/group.tsx +156 -0
- package/src/ui/components/canvas/hit.ts +40 -0
- package/src/ui/components/canvas/index.tsx +497 -0
- package/src/ui/components/canvas/label.tsx +53 -0
- package/src/ui/components/canvas/layout.ts +543 -0
- package/src/ui/components/canvas/lift.ts +272 -0
- package/src/ui/components/canvas/look.ts +129 -0
- package/src/ui/components/canvas/node.tsx +689 -0
- package/src/ui/components/canvas/open.ts +243 -0
- package/src/ui/components/canvas/opening.ts +240 -0
- package/src/ui/components/canvas/view.ts +621 -0
- package/src/ui/components/canvas/viewport.ts +417 -0
- package/src/ui/components/canvas/zoom.tsx +113 -0
- package/src/ui/components/card/index.tsx +20 -0
- package/src/ui/components/chip/index.tsx +24 -0
- package/src/ui/components/code/frame.ts +2 -0
- package/src/ui/components/code/index.tsx +234 -0
- package/src/ui/components/columns/index.tsx +51 -0
- package/src/ui/components/count/index.tsx +17 -0
- package/src/ui/components/diff/index.tsx +249 -0
- package/src/ui/components/diff/word.tsx +104 -0
- package/src/ui/components/dock/index.tsx +262 -0
- package/src/ui/components/file-row/index.tsx +213 -0
- package/src/ui/components/form/base.tsx +280 -0
- package/src/ui/components/form/derive.tsx +269 -0
- package/src/ui/components/form/index.tsx +49 -0
- package/src/ui/components/form/saved.tsx +39 -0
- package/src/ui/components/form-field/index.tsx +658 -0
- package/src/ui/components/gallery/index.tsx +83 -0
- package/src/ui/components/gate/index.tsx +183 -0
- package/src/ui/components/image/base.tsx +245 -0
- package/src/ui/components/image/index.tsx +58 -0
- package/src/ui/components/input/base.tsx +246 -0
- package/src/ui/components/input/code.tsx +108 -0
- package/src/ui/components/input/drop.ts +37 -0
- package/src/ui/components/input/file.tsx +154 -0
- package/src/ui/components/input/index.tsx +132 -0
- package/src/ui/components/input/prose.tsx +107 -0
- package/src/ui/components/input/refusal.tsx +30 -0
- package/src/ui/components/item-header/base.tsx +410 -0
- package/src/ui/components/menu/base.tsx +319 -0
- package/src/ui/components/message/attachments.tsx +101 -0
- package/src/ui/components/message/base.tsx +266 -0
- package/src/ui/components/message-input/index.tsx +377 -0
- package/src/ui/components/missing/base.tsx +45 -0
- package/src/ui/components/pane/head.tsx +399 -0
- package/src/ui/components/pane/index.tsx +325 -0
- package/src/ui/components/picker/base.tsx +1551 -0
- package/src/ui/components/picker/index.tsx +224 -0
- package/src/ui/components/picker/list.tsx +423 -0
- package/src/ui/components/picker/segments.tsx +183 -0
- package/src/ui/components/prose/index.tsx +259 -0
- package/src/ui/components/qr-code/index.tsx +65 -0
- package/src/ui/components/row/acts.tsx +126 -0
- package/src/ui/components/row/fact.tsx +54 -0
- package/src/ui/components/row/index.tsx +1370 -0
- package/src/ui/components/row/progress.tsx +38 -0
- package/src/ui/components/row/status.tsx +54 -0
- package/src/ui/components/row/title.ts +7 -0
- package/src/ui/components/rules/index.tsx +290 -0
- package/src/ui/components/section/band.tsx +39 -0
- package/src/ui/components/section/head.tsx +267 -0
- package/src/ui/components/section/index.tsx +409 -0
- package/src/ui/components/section/rows.tsx +356 -0
- package/src/ui/components/sheet/base.tsx +272 -0
- package/src/ui/components/sheet/confirm.tsx +79 -0
- package/src/ui/components/sheet/docked.tsx +218 -0
- package/src/ui/components/sheet/form.tsx +76 -0
- package/src/ui/components/sheet/head.tsx +120 -0
- package/src/ui/components/sheet/index.tsx +45 -0
- package/src/ui/components/sheet/layer.tsx +168 -0
- package/src/ui/components/sheet/outlet.tsx +58 -0
- package/src/ui/components/sheet/task.tsx +41 -0
- package/src/ui/components/shell/cut.tsx +116 -0
- package/src/ui/components/shell/drag.tsx +45 -0
- package/src/ui/components/shell/host.tsx +71 -0
- package/src/ui/components/shell/index.tsx +737 -0
- package/src/ui/components/shell/panes.tsx +76 -0
- package/src/ui/components/shell/preview.ts +230 -0
- package/src/ui/components/shell/rail.tsx +163 -0
- package/src/ui/components/shell/row.ts +11 -0
- package/src/ui/components/shell/switcher.tsx +143 -0
- package/src/ui/components/shell/tree.tsx +252 -0
- package/src/ui/components/slider/base.tsx +139 -0
- package/src/ui/components/slider/index.tsx +57 -0
- package/src/ui/components/stages/index.tsx +198 -0
- package/src/ui/components/stats/count-links.tsx +47 -0
- package/src/ui/components/stats/index.tsx +203 -0
- package/src/ui/components/stats/meter.tsx +213 -0
- package/src/ui/components/stats/parts.ts +10 -0
- package/src/ui/components/step-count/index.tsx +45 -0
- package/src/ui/components/switch/base.tsx +86 -0
- package/src/ui/components/switch/index.tsx +38 -0
- package/src/ui/components/table/columns.tsx +131 -0
- package/src/ui/components/table/index.tsx +2215 -0
- package/src/ui/components/text/index.tsx +37 -0
- package/src/ui/components/thread/index.tsx +503 -0
- package/src/ui/components/thread/latest.tsx +59 -0
- package/src/ui/components/toast/index.tsx +113 -0
- package/src/ui/components/toast/layer.tsx +26 -0
- package/src/ui/components/toolbar/filters.tsx +161 -0
- package/src/ui/components/toolbar/index.tsx +125 -0
- package/src/ui/components/waveform/index.tsx +205 -0
- package/src/ui/globals.css +427 -0
- package/src/ui/lib/act.ts +60 -0
- package/src/ui/lib/age.ts +49 -0
- package/src/ui/lib/bound.ts +16 -0
- package/src/ui/lib/canvas-layout.ts +11 -0
- package/src/ui/lib/caret.ts +9 -0
- package/src/ui/lib/chip-lines.ts +3 -0
- package/src/ui/lib/closed.ts +8 -0
- package/src/ui/lib/code.tsx +184 -0
- package/src/ui/lib/columns.ts +39 -0
- package/src/ui/lib/commit.ts +24 -0
- package/src/ui/lib/container.ts +112 -0
- package/src/ui/lib/copy.ts +29 -0
- package/src/ui/lib/drag.ts +575 -0
- package/src/ui/lib/empty.tsx +85 -0
- package/src/ui/lib/field.ts +39 -0
- package/src/ui/lib/focus.ts +175 -0
- package/src/ui/lib/folds.ts +67 -0
- package/src/ui/lib/follow.ts +220 -0
- package/src/ui/lib/form.ts +19 -0
- package/src/ui/lib/guards.ts +38 -0
- package/src/ui/lib/heading.ts +14 -0
- package/src/ui/lib/ink.ts +26 -0
- package/src/ui/lib/lang.ts +7 -0
- package/src/ui/lib/leave.ts +14 -0
- package/src/ui/lib/lockup.tsx +145 -0
- package/src/ui/lib/measure.ts +22 -0
- package/src/ui/lib/media.ts +63 -0
- package/src/ui/lib/modality.ts +69 -0
- package/src/ui/lib/moment.ts +13 -0
- package/src/ui/lib/more.tsx +76 -0
- package/src/ui/lib/navigate.ts +210 -0
- package/src/ui/lib/noop.ts +3 -0
- package/src/ui/lib/not-found.tsx +40 -0
- package/src/ui/lib/paint.tsx +55 -0
- package/src/ui/lib/parts-line.tsx +54 -0
- package/src/ui/lib/picked.ts +18 -0
- package/src/ui/lib/player-store.ts +38 -0
- package/src/ui/lib/player.ts +139 -0
- package/src/ui/lib/portal.ts +12 -0
- package/src/ui/lib/read.tsx +269 -0
- package/src/ui/lib/region.tsx +49 -0
- package/src/ui/lib/reorder.ts +154 -0
- package/src/ui/lib/rest.ts +16 -0
- package/src/ui/lib/saved.ts +29 -0
- package/src/ui/lib/scramble.tsx +147 -0
- package/src/ui/lib/scrolls.ts +70 -0
- package/src/ui/lib/style.ts +6 -0
- package/src/ui/lib/swap.tsx +107 -0
- package/src/ui/lib/toast.ts +39 -0
- package/src/ui/lib/walk-classes.ts +16 -0
- package/src/ui/lib/window.tsx +376 -0
- package/src/ui/worker.d.ts +4 -0
package/guide/figures.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Figures: Stats and BarChart
|
|
2
|
+
|
|
3
|
+
The parts that draw numbers, each a card of its own: `Stats`, figures in cells, and `BarChart`,
|
|
4
|
+
columns over time or over buckets. The other blocks are [blocks](./blocks.md).
|
|
5
|
+
|
|
6
|
+
## Stats
|
|
7
|
+
|
|
8
|
+
Figures in cells. `items` are cells `{ label, value, line? }`, the `line` a sentence under the figure (a selection paints until its read lands). A cell whose `value` is a selection is the frame of that read, as a meter is: given no `Pane` `read` to hold it, a failed cell draws the failure mark, "This didn't load." and a retry on its own. Each cell is one of:
|
|
9
|
+
|
|
10
|
+
- plain, with a `unit` after the figure's last digit (the spare space stands after the pair).
|
|
11
|
+
- a link: `href` makes the whole cell a link; `counts` makes sub-counts links of their own. Never both.
|
|
12
|
+
- a meter: `bound` is the limit, so `value` is drawn as a share of it, with sub-counts (`counts`) but no `unit` or `href`. `mark` is a tick on the track where the fill turns amber; `goal` makes the bound a target reached, not a limit.
|
|
13
|
+
|
|
14
|
+
## BarChart
|
|
15
|
+
|
|
16
|
+
Columns over time, or over buckets (hours, plans, countries).
|
|
17
|
+
|
|
18
|
+
- `label`: what the chart counts, read aloud and never drawn.
|
|
19
|
+
- `items` and `bar`: the bars oldest first and the regions that read each (`key`, `value`, `parts`, `at`, `label`, `partial`, `selected`). `bar.label` names a bucket under its bar, in the time line's place: every bar is named when the names fit, and every second, third… one when they would touch (`bar.at` times a chart of moments instead); `bar.partial` hatches a bar whose period is not over; `bar.selected` stands the bar of the open record in the selection wash.
|
|
20
|
+
- `keys`: the names a bar's parts stack by, bottom first. Present, the chart is stacked and the names are its legend.
|
|
21
|
+
- `unit`: what the values count, drawn after the total. `{ one, other }` for a plural, `{ currency: "USD" }` for money.
|
|
22
|
+
- `level`: the bars are a level, not a flow (open flags per round): the head draws the last bar's value, never a sum.
|
|
23
|
+
|
|
24
|
+
From 50 bars the chart scrolls sideways at a fixed bar width and draws its times in place of the bucket names.
|
|
25
|
+
|
package/guide/forms.md
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Forms
|
|
2
|
+
|
|
3
|
+
A `Form` (`components/form`) takes the procedure it submits and the labels of the fields it shows; the procedure's input schema (`slotform generate` writes it to `.slotform/schema.ts`) gives everything else. This page is what a `Form` and its fields take, how each schema shape draws, and how it steps and commits; when a screen holds a `Form` is `rules.md`, and what both platforms share (the schema's checks, the server's refusal, a settings page, a form in a `Sheet` or a `Gate`) is `node_modules/@slotform/ui-core/guide/forms.md`.
|
|
4
|
+
|
|
5
|
+
```tsx
|
|
6
|
+
<Form
|
|
7
|
+
act={orpc.requests.submit}
|
|
8
|
+
given={{ organizationId: organization.id }}
|
|
9
|
+
fields={{
|
|
10
|
+
title: { label: "What should change?" },
|
|
11
|
+
why: { label: "Why?", control: "prose" },
|
|
12
|
+
kind: { label: "Kind of request" },
|
|
13
|
+
dueDate: { label: "By when?" },
|
|
14
|
+
}}
|
|
15
|
+
submit={{ label: "Submit" }}
|
|
16
|
+
onDone={(request) => navigate(`${base}/requests/${request.id}`)}
|
|
17
|
+
/>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## The form's props
|
|
21
|
+
|
|
22
|
+
| Prop | Is |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| `act` | the procedure the form submits: its input schema gives every field its control, its optionality and its issue line |
|
|
25
|
+
| `given` | the input keys the screen supplies (a scope id, a record id), sent and never drawn; a required key that is neither a field nor given throws |
|
|
26
|
+
| `fields` | the fields, keyed by the input's keys (a key the input lacks is a type error), in the order they stand ([a field's props](#a-fields-props)) |
|
|
27
|
+
| `groups` | `{ title, description?, fields, values?, empty? }[]` in place of `fields`: the fields under bands. A group's `values` are its fields' first values in place of the form's, and a selection of them is the group's own read: its fields paint while it waits, its failure or a missing record stands in their place, and `empty` is the sentence when it is empty, while the other groups and the bar stand |
|
|
28
|
+
| `values` | the fields' first values, for a form about a record: a selection paints the controls until its read lands and is the form's `read` unless one is given |
|
|
29
|
+
| `read`, `empty` | the form's frame read and its empty sentence |
|
|
30
|
+
| `onDone` | hears the output and the input it sent once the procedure resolves; a promise it returns keeps the submit pending, and the fields as sent, until it settles. Then, where the form stays (on a page, its submit going nowhere), the fields go back to `values`, and a sheet drops its edits as it opens again |
|
|
31
|
+
| `after` | a function of the input the fields make now (`given` and each field that holds a value, as the procedure would take it): the node it returns stands after the fields at the card inset, so a live preview of what the form would send (a bulk edit's before and after) is right with the first values, follows every change and starts over when a sheet reopens, and no screen holds the input in state |
|
|
32
|
+
| `can` | the ability the caller needs, `[action, subject]` (`can={["create", "request"]}`), asked in the organization of the route's scope: a caller who may not has the fields disabled and the submit blocked with the word `denied`, and the form paints, inert, until the ability's read lands |
|
|
33
|
+
| `submit` | `{ label, done, to, destructive }`: the bar's filled act's words (default "Save"), its toast, its route, and `destructive` for a form that rejects, abandons or closes something |
|
|
34
|
+
| `acts` | the other acts standing in the bar before the submit (a Cancel, a destructive Decline with `confirm`), each an act of any bar ([acts](./acts.md#actionbar)); a `Gate`'s form passes them through |
|
|
35
|
+
| `steps` | `true`: the form asks one step at a time ([steps](#steps)) |
|
|
36
|
+
| `commit` | `"submit"` (the default) or `"field"`: each field sends `given` and its own key as the viewer commits it, and the form draws no bar (`node_modules/@slotform/ui-core/guide/forms.md#a-settings-page-commits-by-field`); with `acts` they stand in a bar of their own under the fields, the last of them filled |
|
|
37
|
+
|
|
38
|
+
## A field's props
|
|
39
|
+
|
|
40
|
+
| Prop | Is |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `label` | the field's name over its control, a short phrase; a label that is a question ("By when?") is its own blocked reason |
|
|
43
|
+
| `description` | a sentence under the control, a constant or a selection |
|
|
44
|
+
| `control` | what the schema cannot say: `mono`, `prose`, `source`, `code`, `secret`, `date`, `list`, `segments`, `lines`, `json`, `file` ([the schema decides](#the-schema-decides-the-control)) |
|
|
45
|
+
| `options` | the choices of a string the schema does not list (a read of records), or the labels of an enum's members; a function of the draft, `(draft) => options`, narrows them by the fields before it as the draft changes and may answer a read, so the pick paints while it waits; a chosen value no longer among them is cleared |
|
|
46
|
+
| `empty` | what a pick reads while it holds nothing: an optional pick's empty choice (default "None"), a required pick's placeholder (default "Choose"); say what empty means where "None" would mislead ("Any status") |
|
|
47
|
+
| `locked` | the field stands inert with this reason under it, as a row's `lock` does |
|
|
48
|
+
| `accept` | on a `file` field: the MIME types, families and extensions it takes |
|
|
49
|
+
| `name` | on a `file` field: the input's string key that receives the picked file's name, for an input of `{ file, fileName }` |
|
|
50
|
+
|
|
51
|
+
## The schema decides the control
|
|
52
|
+
|
|
53
|
+
| The schema says | The field draws |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| a string | a line of text (`control: "mono"` the line in the mono, `Input kind="source"`, for a machine name a person types: a path, a host, a flag, an identifier, so the value reads as the issue under it quotes it (`node_modules/@slotform/ui-core/guide/face-type.md`, **Type**); `"prose"` many lines, `"source"` many lines in mono, `"code"` the one-time code boxes (`Input kind="code"`, as many as the schema's fixed length: `z.string().length(n)`, else the field throws naming its key; the submit stays blocked until every box is filled), `"secret"` a masked line (`Input kind="secret"`: an API key, a token; the box is never filled: the secret is never read back. A secret the server holds is told in `values` by its masked form (the last characters, never the secret): the form draws no box for it but the sentence "Saved, ends in 1234" (the last four characters of the masked form, in the meta ink) with a quiet Replace, which opens the empty box with focus, and a quiet Remove that asks first and then sends the field alone as `null` where the schema takes it, else as the empty string (so the field must be optional or nullable); Enter in the box commits and never removes; omit it from `values` and the field stands as unset, and an untouched saved secret is left out of the input), `"date"` a date line; a `format: date` string is one already) |
|
|
56
|
+
| an enum, or a string with `options` | one choice: the Select (`control: "list"` the option list, a radio per option; `"segments"` the segmented row; both on a field that always holds a value, required or with a schema `default`, since neither has an empty choice, and over the schema's values or a fixed `options` list, never a read or a function of the draft, else the field throws naming its key) |
|
|
57
|
+
| a boolean | a switch |
|
|
58
|
+
| a number | a numeric line |
|
|
59
|
+
| a list of an enum, or of strings with `options` | a pick of several (`control: "list"` the option list, a checkbox per option) |
|
|
60
|
+
| a list of strings, numbers, booleans or `null` with `control: "lines"` | a text area, one item per line (each line trimmed, blank lines dropped); the array is sent, each line read as the item type the schema allows (`true`/`false` a boolean, `null` null, a number a number, else the text), and a line that fits none stands as the field's issue ("Line 3 isn't a value this list takes."); `values` joins the array with newlines; empty sends `null` where nullable, else `[]` |
|
|
61
|
+
| an object, a list of objects, or any value with `control: "json"` | a mono text area (`Input kind="prose" source`) holding the JSON text, parsed when the form commits (the submit, or the field's commit); a parse error stands as the field's issue, the parser's message and position; the parsed value is sent; `values` pretty-prints with two-space indent; empty sends `null` where nullable, else the key absent where optional (a required field has nothing to send) |
|
|
62
|
+
| a date (`date-time`) | a date line (`Input kind="date"`), sent as a `Date` |
|
|
63
|
+
| a string with `control: "file"` | a file pick (`Input kind="file"`) over the `accept` the field gives (JSON Schema has no form for it); the picked file is read into the string, as text, or as base64 where the schema entry is `contentEncoding: "base64"` (a `z.base64()`); `name: "fileName"` names the input's string key that receives the picked file's name |
|
|
64
|
+
| optional | the pick offers an empty choice; the field left empty is not sent (`null` where nullable), a pick committed empty by field included; in a submit form the word `optional` stands under its label, on a second line of the label column, in the meta ink; a form that commits by field marks no field, optional or required |
|
|
65
|
+
| a pick or a switch with a schema `default` (zod `.default()`) | always holds a value, so it is required: it starts on the default, offers no empty choice and carries no `optional` word; only a truly optional or nullable field says `optional` |
|
|
66
|
+
| a filled pick | its trigger is named "label, value" (WCAG 2.5.3: the name holds the words the trigger shows, so axe's label-content-name-mismatch passes); an empty one is named by its label |
|
|
67
|
+
| a pick whose options read failed or is missing | the sentence and Retry stand on one control-high line in the value column, in the trigger's place and level with the label, never a blank trigger with the line under it |
|
|
68
|
+
| required | the submit stays blocked while the field is empty, its reason naming the field by its label ("Give the project directory.", "Pick the region."), the words `giveField` and `pickField`; a value of the wrong type (a number that is not one, a date no calendar has) blocks it the same way, "Check the retry limit." (`checkField`) |
|
|
69
|
+
|
|
70
|
+
A shape no control draws (an object or a list of objects without `json`, a list of anything but an enum without `lines`, a union) throws naming the key, as does a `lines` or `json` hint the schema does not fit.
|
|
71
|
+
|
|
72
|
+
## Change marks
|
|
73
|
+
|
|
74
|
+
A field whose value differs from its first draws its change mark at its value line's start: `added` where it was empty and holds a value, `removed` where it held one and is empty (a switch's off is its empty), `changed` otherwise. The mark follows the same by-value edit the leave asks about, so a value put back drops it; the app passes nothing.
|
|
75
|
+
|
|
76
|
+
## Steps
|
|
77
|
+
|
|
78
|
+
`steps` asks one step at a time: a step is a group, or a field when the form has no groups. The open step's fields stand over the bar, whose filled act is Continue, blocked with its reason until every field in the step holds a value its schema accepts; the last step's act is the submit, and a step not reached yet is not drawn. Continue folds the step to one summary row (a check, the group's title or the field's label, then each answer in field order a middle dot apart, cut with an ellipsis, and an Edit act that unfolds the step and focuses its first control) and opens the next, whose first control takes focus. A refusal of a field in a folded step unfolds it. A form that commits by field takes no `steps`.
|
|
79
|
+
|
|
80
|
+
## The bar
|
|
81
|
+
|
|
82
|
+
A `Form`'s submit is always the bar's filled act, and a `Form` has no quiet form of it. The bar is an `ActionBar` the form draws itself ([acts](./acts.md#actionbar)). A submit that waits for a change is the blocked submit (`blocked`, a reason the viewer can act on).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# The Pane's bar
|
|
2
|
+
|
|
3
|
+
The line over a `Pane`'s body: its trail, its title, its acts and its way back. What the `Pane` takes is [pane](./pane.md).
|
|
4
|
+
|
|
5
|
+
The bar holds the trail, the title, the context pick, the acts and the more menu on one line at every width. The first `acts` entry stands at its icon and the rest lead `more`, the act named More, its touch sheet titled by the Pane's title (`node_modules/@slotform/ui-core/guide/links.md#acts-fold-by-one-rule`). The title keeps two fifths of the row.
|
|
6
|
+
|
|
7
|
+
The trail is the place's path in the `Shell`'s tree, which the `Shell` gives the Panes, so a route passes none: a record's Pane draws every place above the record's place, then that place, a slash, and the record's name; a place's own Pane deep in the tree draws the places above it, then its own name as its title; a top-level place's Pane draws its title alone. A place that is a page is a link and a folder is text. On the desktop the top place and the current one stay while the places between stand where the Pane is wide enough and fold into one `…` act where it is not. On touch the trail stands at the start of the record head's overline, or as the overline over a deep place's title.
|
|
8
|
+
|
|
9
|
+
The place's Pane has no Back or Close: the sidebar moves between places. A record's Pane has Close at the bar's end on the desktop and Back at its start below `tablet` of the place; both return to the place's Pane as it stood, its tab and filters kept, because the return route carries the address's query. Its Expand act folds the place's Pane away so the record takes the place, and turns into Collapse, which brings the list back. A Pane that opens from a press in another takes the keyboard on its first control.
|
|
10
|
+
|
|
11
|
+
A failed Pane is the whole page with Retry as its one act, and a missing one is the page with its way back (beside another Pane, its Back in place of Close): its bar draws none of its `acts` and no more menu, and names what is missing where its title's read ended (the `noun` capitalised, else "Not found"), keeping the record's place and the way back. Its foot and docked sheet stand, since they answer to their own reads.
|
package/guide/pane.md
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Pane
|
|
2
|
+
|
|
3
|
+
One column of a place, of two kinds, one of each at most: the place's own, titled by the place's name, and a record's after it, titled by the record's name (`node_modules/@slotform/ui-core/guide/places.md#two-kinds-of-pane`). This page is what a `Pane` takes, its record's head, its body and its foot; its bar is [pane-bar](./pane-bar.md), and the `Panes` that hold it are [shell](./shell.md#panes).
|
|
4
|
+
|
|
5
|
+
| Prop | Is |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `title` | the record's name, a short phrase or a selection of its read, on a record's Pane; the place's Pane takes none, the place's name titles it |
|
|
8
|
+
| `record` | `{ overline, facts, description, image }`, the record's head, given with `title` |
|
|
9
|
+
| `noun` | the record's kind ("project"), for "Couldn't find this project." and the failed bar's name |
|
|
10
|
+
| `missing` | the sentence in place of the one `noun` words, when the read answers not found |
|
|
11
|
+
| `acts` | icon acts (`IconAct`, `IconLinkAct`) in the bar, the one used most first |
|
|
12
|
+
| `more` | the acts past them, in the bar's menu |
|
|
13
|
+
| `context` | a `Picker`'s props but `fit`, for a page read in a context the viewer picks (Live, a change set, a version), drawn as a pill after the title |
|
|
14
|
+
| `state` | the context's tone, a dot before the pick's label: `active` for Live, `attention` for a draft, `idle` for a version |
|
|
15
|
+
| `foot` | what docks under the body, the body scrolling under it |
|
|
16
|
+
| `sheet` | a task that docks in the foot's place while it is `open`; closing hands focus back to the foot's input |
|
|
17
|
+
| `read` | the frame's read (`node_modules/@slotform/ui-core/guide/frames.md`) |
|
|
18
|
+
| `empty` | what the page says when the `read` is empty, in place of the body; given only with `read` |
|
|
19
|
+
| `fill` | the body's one child is a filler, a `Thread` or a `Canvas`, that takes the free height |
|
|
20
|
+
| `children` | the Pane's sections, a sections gap apart |
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
<Pane title={deploy.at((d) => d.commit)} record={head} noun="deploy">…</Pane>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## The record's head
|
|
27
|
+
|
|
28
|
+
The body opens with the record's name, whole and wrapping, between `overline` (the parts that place it, joined by a middle dot; never a place of the trail, which the bar holds) and `facts`, a `RecordFact` list (`node_modules/@slotform/ui-core/guide/facts.md#a-record-heads-facts`); the `description` stands as plain text under them, and the `image` (`{ src, alt }`: a person's photo, a product shot) is a square tile beside all of it at the top, painted while its `src` is a read, an `ImageOff` glyph where it failed or the address is empty. The overline is one text line cut with an ellipsis at its end; on touch the trail leads it, cut at its own start so the nearest place shows.
|
|
29
|
+
|
|
30
|
+
## The body
|
|
31
|
+
|
|
32
|
+
The body is a two-column grid: every `Section` and `Form` in it passes the columns down to its rows, so the labelled rows of one Pane share one label column, as wide as the widest label up to one short measure, past which a long label wraps at its words inside the column. The value column keeps a short measure at least, so a pick keeps its words; a labelled value with a description beside a pick or a switch keeps the description at the short measure, and stands the control under it at the line's end where both do not fit. A definition row and a form field stand label over value in a Pane narrower than `definitionsOneRow` (two short measures, the stack gap and the page inset: about 340 to 360 px at the default size), and label beside value from that width; the Pane's width decides, never the pointer. With `fill` the body is a flex column that gives the filler the free height, and its Sections keep their own label columns.
|
|
33
|
+
|
|
34
|
+
Width follows content: a `Table`, a line `Diff`, a code block, a `Canvas`, a `BarChart`, `Columns` and a `Gallery` mark themselves `data-wide` and span the body, while definition rows, forms and prose keep the reading width. Widths are voice decision 17 (`node_modules/@slotform/ui-core/guide/voice.md`).
|
|
35
|
+
|
|
36
|
+
A Pane with no `empty` leaves its empty read to its Sections, which draw their own. A record that is not there is `node_modules/@slotform/ui-core/guide/frames.md#a-record-that-is-not-there`; on the web its missing shape is an empty's one form, the sentence in the meta ink over the way back as an outlined button, both centred. The page for an unknown address is a record's Pane titled "Not found"; under a record's Pane it is that Pane's body, the missing sentence.
|
|
37
|
+
|
|
38
|
+
## The foot
|
|
39
|
+
|
|
40
|
+
The route gives the foot, so the Pane decides it from its props and nothing in its body hands anything up. A `Table`'s chosen bar is an `ActionBar` with `chosen` ([acts](./acts.md#the-chosen-bar)). A `Thread` that fills its Pane stands its composer at the foot itself; one standing among a Pane's sections keeps its composer under its log, and where the field should stay in reach however long the list (on touch, above the tab bar) the route gives the Pane the composer as its `foot` (`<Composer {...composer} />`) and the docked sheet as its `sheet`, and the `Thread` neither:
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
const touch = useTouch();
|
|
44
|
+
|
|
45
|
+
<Pane title="Now" foot={touch ? <Composer {...composer} /> : undefined} sheet={touch ? question : undefined}>
|
|
46
|
+
<Section title="Ask"><Thread items={lines} message={message} composer={touch ? undefined : composer} sheet={touch ? undefined : question} /></Section>
|
|
47
|
+
</Pane>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
A docked `sheet` takes the foot over while it is open.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Web UI reference
|
|
2
|
+
|
|
3
|
+
`reactUi()` renders the `@slotform/ui-core` contract into the web app's stylesheet, loads the
|
|
4
|
+
fonts, sets the mode before first paint and mounts the words. It sits beside `vite()` and
|
|
5
|
+
`react()` in `slotform.config.ts`. A web app that owns no server gives `api({ server })` the Slotform app it
|
|
6
|
+
talks to (`node_modules/@slotform/api/guide/config.md`) and carries no deploy target.
|
|
7
|
+
|
|
8
|
+
## Components
|
|
9
|
+
|
|
10
|
+
Each roster component is imported from its own subpath, its name in kebab case:
|
|
11
|
+
|
|
12
|
+
```tsx
|
|
13
|
+
import { Section } from "@slotform/react-ui/components/section";
|
|
14
|
+
import { Pane } from "@slotform/react-ui/components/pane";
|
|
15
|
+
import { toast } from "@slotform/react-ui/lib/toast";
|
|
16
|
+
import { useWords } from "@slotform/ui-core/react/words";
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`navigate(route)` (`lib/navigate`) opens a route of the app from a handler the way a `Button` with an `href` does, in the router with no document load. `toast()` and `confirm()`, and the act types and hooks, are [acts](./acts.md).
|
|
20
|
+
`age(moment, now)` (`lib/age`) words an ISO moment as its age from `now` ("2 minutes ago") and
|
|
21
|
+
`ageShort(moment, now)` in its short form ("2 min", for a meta like "Waiting for you · 12 min");
|
|
22
|
+
read `now` from the shared clock, `useClock((now) => age(moment, now))` (`@slotform/ui-core/react/clock`), and the age
|
|
23
|
+
ticks on its own, the part drawing again only when its words change. A row's trailing age takes
|
|
24
|
+
the ISO moment itself, `trailing: { age: item.madeAt }`: the row words it short and ticks it, so
|
|
25
|
+
pass the moment, never a worded string. `useTouch()` (`lib/media`) says whether the touch density is
|
|
26
|
+
drawing. The icon set is Lucide, drawn from `lucide-react`: every `icon` a component takes is an
|
|
27
|
+
`IconName`, a Lucide PascalCase name.
|
|
28
|
+
|
|
29
|
+
`player` and `usePlayer()` (`lib/player`), the `Dock` and the `Waveform` play and draw sound: [audio](./audio.md).
|
|
30
|
+
|
|
31
|
+
## Reads
|
|
32
|
+
|
|
33
|
+
A read, a `Form` and an act's refusal run on the `QueryProvider` that `query()` mounts; without
|
|
34
|
+
`query()` in the config a component given plain values still draws, and a read or a `Form` throws
|
|
35
|
+
naming the provider. The web needs no `QueryProvider listen`, since TanStack reads the window's
|
|
36
|
+
online and visibility events.
|
|
37
|
+
|
|
38
|
+
A still frame sets `data-still` on its box, a collection's own box too.
|
|
39
|
+
|
|
40
|
+
## Long collections
|
|
41
|
+
|
|
42
|
+
A collection windows by itself: from `VIRTUAL_FROM` loaded rows (`@slotform/ui-core/window`) under
|
|
43
|
+
a scroller, only the rows near the view and `OVERSCAN` past each edge are drawn, spacers holding
|
|
44
|
+
the space of the rest. No prop turns it on or off. The scrollers are a `Pane`'s body, a `Sheet`'s
|
|
45
|
+
body (docked or not), a `Gate`'s page and a `Thread`'s log, the nearest one winning, so a `Section`'s
|
|
46
|
+
sheet in a `Sheet` windows against the `Sheet`. A `Section`'s sheet (rows, labelled or not, flat
|
|
47
|
+
or a tree), a `Table` at both widths, a `Thread`, trees, a `Picker`'s options (its `list` fit included),
|
|
48
|
+
and a `BarChart` (sideways, at a fixed bar width) window. A row is exactly one element. A collection that crosses the count
|
|
49
|
+
(a Show more) keeps the rows it drew.
|
|
50
|
+
|
|
51
|
+
## Options
|
|
52
|
+
|
|
53
|
+
| Option | Default | What it does |
|
|
54
|
+
| --- | --- | --- |
|
|
55
|
+
| `theme` | the calibrated defaults | Six knobs: `hue` (`{ accent?, cast? }`; the accent 264, the cast the neutrals' hue, the accent's unless set), `radius` (the control's corner radius in px, 6; a layer takes a third more), `fonts` (`{ sans?, mono? }` family names; IBM Plex Sans (sans) and IBM Plex Mono (mono) unless set), `size` (the desktop body in px, 13, 12 to 18: every type size, space and size scales with it), `defaultMode` (where a viewer with no stored choice starts, ahead of `prefers-color-scheme`) and `loading` (`{ text?, figure?, id? }`, each `"pulse"` or `"scramble"`: how that kind of waiting region is painted, the skeleton's breath or generated characters; omitted, all pulse. A technical voice scrambles figures and ids, `{ figure: "scramble", id: "scramble" }`; a shape always pulses). |
|
|
56
|
+
| `words` | English | Every word a component draws on its own, every key required. Read with `useWords()`. |
|
|
57
|
+
| `fonts` | IBM Plex Sans upright and italic on the `wght` axis, IBM Plex Mono at 400, 500 and 600 | The font files to load, each preloaded with a metric fallback face (a `local()` face over the system font of the same metrics, `Liberation` and `Arimo` standing in for Arial on Linux); `[]` loads none. Which family binds to `sans` or `mono` is `theme.fonts`. The default list is `defaultFonts`, from `@slotform/react-ui/node/fonts`. |
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
reactUi({
|
|
61
|
+
theme: { hue: { accent: 120 }, defaultMode: "dark" },
|
|
62
|
+
words: { ...ENGLISH, back: "Zurück" },
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`ENGLISH` is the default words record, from `@slotform/ui-core/tokens`.
|
|
67
|
+
|
|
68
|
+
## Modes
|
|
69
|
+
|
|
70
|
+
The `dark` class on `<html>` is the mode; `.light` on an element inside it restores the light
|
|
71
|
+
colours for that subtree. The mode script sets `dark` before first paint from the stored choice,
|
|
72
|
+
else `theme.defaultMode`, else the system; a mode that came from the system follows it while the
|
|
73
|
+
page is open (a screen on a dark schedule changes with it), unless a choice is stored by then. Under
|
|
74
|
+
`prefers-reduced-motion: reduce` every transition duration is 0 ms.
|
package/guide/rules.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Rules for the web UI
|
|
2
|
+
|
|
3
|
+
Every app `.tsx` follows these rules. The design system is the roster
|
|
4
|
+
(`node_modules/@slotform/ui-core/src/roster.ts`, each component's entry in `src/roster/<component>.ts`; cells, states and tokens in ui-core's `DESIGN.md`)
|
|
5
|
+
plus the app's own `ui/` directory (any `ui/` path segment); everything else composes components
|
|
6
|
+
and never restyles them.
|
|
7
|
+
|
|
8
|
+
## Pick the component first
|
|
9
|
+
|
|
10
|
+
Find the roster component that owns the shape: the container (`Shell`, `Pane`, `Gate`),
|
|
11
|
+
the rhythm (`Section`), the row (a `Section`'s `items`, a `Form`'s fields), the
|
|
12
|
+
control, the text role (`Text`). A host element that rebuilds one of these is drift. A composed
|
|
13
|
+
region is data its molecule renders, never nodes. A shape no component owns takes the nearest one the
|
|
14
|
+
roster draws (`node_modules/@slotform/cli/guide/shortfall.md`).
|
|
15
|
+
|
|
16
|
+
A Pane stands in a place, as the place's own or a record's (`node_modules/@slotform/ui-core/guide/places.md#two-kinds-of-pane`).
|
|
17
|
+
A record opens beside its list and its tabs stay in its Pane: the record's route is a child of the list's,
|
|
18
|
+
the list's route renders an `<Outlet />` after its Pane, and the record's one inside its Pane's body.
|
|
19
|
+
|
|
20
|
+
```tsx
|
|
21
|
+
// routes/projects.tsx: the place's Pane, then whatever record is open
|
|
22
|
+
<><ProjectsPane /><Outlet /></>
|
|
23
|
+
// routes/projects/$project.tsx: the record's Pane; the tab routes render inside its body
|
|
24
|
+
<Pane title={project.at((p) => p.name)} record={head} noun="project" acts={[edit]}>
|
|
25
|
+
<Tabs /><Outlet />
|
|
26
|
+
</Pane>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
A place whose body is one record (a project's overview, a settings record) is the place's Pane, titled by
|
|
30
|
+
the place; the record's name shows in the sidebar's switcher. The `Shell`: [shell](./shell.md); a `Pane`: [pane](./pane.md).
|
|
31
|
+
|
|
32
|
+
## One `Button`, one `Input`, one `Switch`
|
|
33
|
+
|
|
34
|
+
The controls and their fields: `node_modules/@slotform/ui-core/guide/controls.md`; their props: [controls](./controls.md).
|
|
35
|
+
|
|
36
|
+
## Tone is one vocabulary
|
|
37
|
+
|
|
38
|
+
A status, a `Banner` and a toast take one `tone`, and a status is a `StatusMark`: `node_modules/@slotform/ui-core/guide/tone.md`. A message the viewer must read again is a [`Banner`](./containers.md#banner).
|
|
39
|
+
|
|
40
|
+
## Sound is the player's
|
|
41
|
+
|
|
42
|
+
A track a viewer plays is `player.play(track)` (`lib/player`), never an `<audio>`, a `new Audio()` or a
|
|
43
|
+
seek slider built by hand: [audio](./audio.md).
|
|
44
|
+
|
|
45
|
+
## A route act is a link
|
|
46
|
+
|
|
47
|
+
A route act is a `LinkAct`, and side-by-side acts fold by one rule: `node_modules/@slotform/ui-core/guide/links.md`.
|
|
48
|
+
The check flags an `onAct` that only calls `navigate(...)` (`no-navigate-act`). A link draws as an `<a href>`
|
|
49
|
+
in its act's look ([controls](./controls.md#button)).
|
|
50
|
+
|
|
51
|
+
## A record's decision is an `ActionBar`
|
|
52
|
+
|
|
53
|
+
Acts that stand together at the end of what they decide (a record's Approve and Decline, a step's
|
|
54
|
+
Back and Continue, a pane body's Discard and Save) are one `ActionBar`, never `Button`s the screen
|
|
55
|
+
lines up: [acts](./acts.md#actionbar).
|
|
56
|
+
|
|
57
|
+
## A form is its procedure and its field labels
|
|
58
|
+
|
|
59
|
+
A `Form`'s props: [forms](./forms.md); what both platforms share: `node_modules/@slotform/ui-core/guide/forms.md`.
|
|
60
|
+
|
|
61
|
+
A screen stands one filled act (`node_modules/@slotform/ui-core/guide/face-surfaces.md`, **Controls**), and a `Form`'s submit is always one. So a `Form`
|
|
62
|
+
beside the Pane's filled act lives in a sheet the Pane's act, or a row's, opens; a `Form` in the Pane's
|
|
63
|
+
body is the Pane's one decision, and the Pane gives no filled act. Settings with no decision are
|
|
64
|
+
`commit: "field"`, with no bar.
|
|
65
|
+
|
|
66
|
+
## A `Section` never stands in a `Section`
|
|
67
|
+
|
|
68
|
+
A parted page is `Section`s in a `Pane`, a parted form is `groups`: [section](./section.md).
|
|
69
|
+
|
|
70
|
+
## Collections take data
|
|
71
|
+
|
|
72
|
+
Rows are data: `node_modules/@slotform/ui-core/guide/rows.md`; what a row says of itself: `node_modules/@slotform/ui-core/guide/facts.md`.
|
|
73
|
+
A list of things is a `Section` of `Row`s ([section](./section.md)), records read across columns a `Table`
|
|
74
|
+
([table](./table.md)).
|
|
75
|
+
|
|
76
|
+
## Drag, drop and reorder
|
|
77
|
+
|
|
78
|
+
A drag is data, on the web only: [drag](./drag.md).
|
|
79
|
+
|
|
80
|
+
## Pictures side by side are a `Gallery`
|
|
81
|
+
|
|
82
|
+
Which component draws pictures, and a code a camera reads: `node_modules/@slotform/ui-core/guide/pictures.md`; a `Gallery`'s and a `QrCode`'s props: [blocks](./blocks.md#gallery).
|
|
83
|
+
|
|
84
|
+
## A region that reads is a frame
|
|
85
|
+
|
|
86
|
+
A region that reads is a frame: `node_modules/@slotform/ui-core/guide/frames.md`; how it waits, and how an act paints by its own datum: `node_modules/@slotform/ui-core/guide/waiting.md`.
|
|
87
|
+
|
|
88
|
+
## An act holds its attempt
|
|
89
|
+
|
|
90
|
+
Acts, their wiring and their order: `node_modules/@slotform/ui-core/guide/acts.md`; a sheet an act opens: `node_modules/@slotform/ui-core/guide/sheets.md`; the web's act types, the `ActionBar` and toasts: [acts](./acts.md).
|
|
91
|
+
|
|
92
|
+
## Words are the config's, sentences are props
|
|
93
|
+
|
|
94
|
+
A word a component draws on its own comes from `reactUi({ words })`: `node_modules/@slotform/ui-core/guide/words.md`.
|
|
95
|
+
|
|
96
|
+
## A text prop takes one of four sizes
|
|
97
|
+
|
|
98
|
+
The four sizes and what a component does past them: `node_modules/@slotform/ui-core/guide/words.md#a-text-prop-takes-one-of-four-sizes`.
|
|
99
|
+
|
|
100
|
+
## The app's `ui/`
|
|
101
|
+
|
|
102
|
+
A shape that needs the app's nouns: `node_modules/@slotform/ui-core/guide/rows.md#the-apps-ui`.
|
|
103
|
+
|
|
104
|
+
## What the check enforces
|
|
105
|
+
|
|
106
|
+
`pnpm check` fails the lint rules on the app's own sources (the directory its routes sit in), from
|
|
107
|
+
`.slotform/biome.json` (`node_modules/@slotform/cli/guide/commands.md`). The rules are `LINT_RULES` in `plugins/react-ui/src/node/lint.ts`, each a
|
|
108
|
+
`plugins/react-ui/lint/<rule>.grit` whose header states what it forbids. The rest stays a rule a
|
|
109
|
+
reviewer holds.
|
package/guide/section.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Section
|
|
2
|
+
|
|
3
|
+
A titled stretch of a page, over its rows (`items`) or its parts (`children`): what a `Section` takes
|
|
4
|
+
and how its rows draw. What a row carries is `node_modules/@slotform/ui-core/guide/rows.md`.
|
|
5
|
+
|
|
6
|
+
| Prop | Is |
|
|
7
|
+
| --- | --- |
|
|
8
|
+
| `title` | a short phrase, or a selection of the read the section holds; a Section with `items` and no `title` is the sheet alone |
|
|
9
|
+
| `description` | a sentence under the title |
|
|
10
|
+
| `folded` | makes the title fold the body, and is the initial fold (`true` starts folded, `false` open; later changes are not read); the title stays the heading size folded or not |
|
|
11
|
+
| `onToggle` | hears whether it is now open |
|
|
12
|
+
| `act`, `more` | the head's one icon act and its other acts in a menu; a foldable section's `more` does not fold it |
|
|
13
|
+
| `items` | the sheet's rows, `Row`s (`node_modules/@slotform/ui-core/guide/rows.md#a-rows-fields`), a constant or a selection |
|
|
14
|
+
| `groups` | the bands over them, `{ key, label, act? }`, a row's `group` naming a band's `key`; a constant or a selection |
|
|
15
|
+
| `reorder` | lets the rows be moved ([drag, drop and reorder](./drag.md)) |
|
|
16
|
+
| `read` | the read of a Section over parts (`children`); a Section with `items` frames its own selections and takes none |
|
|
17
|
+
| `empty` | what it says when empty, `{ sentence, act? }`: the sentence in the meta ink over its act as an outlined button (a `LinkAct` too), both centred; a Section with a `description` takes an `empty` of its `act` alone |
|
|
18
|
+
|
|
19
|
+
`Row` is `import type { Row } from "@slotform/react-ui/components/section"`. A `Section` never stands in a `Section`, and its title is one size (the heading) everywhere, a sheet's body and a fold included.
|
|
20
|
+
|
|
21
|
+
A `Section` with `items` is a frame of its rows' reads: `items` and `groups` each take a constant or a selection, so the sheet paints until they land and a failure of either stands once in the sheet's place. A second read the rows depend on is the `Pane`'s or an enclosing frame's (`node_modules/@slotform/ui-core/guide/frames.md`). A row's `pick` whose `options` are a selection of another read paints blocked while the options wait or after they failed, and the sheet says "This didn't load" with Retry once, over the rows.
|
|
22
|
+
|
|
23
|
+
## How a row draws
|
|
24
|
+
|
|
25
|
+
The badges follow the title on its line where the row is one line, without wrapping, the last one that does not fit cut with an ellipsis, and stand under the title where it is two (on touch, wherever the row has a status, a warning, a lock, a chip or a mark with words, and a row with only words below the row's one-line width); under a `wrap` title they wrap freely. A cut badge shows the cut text in a tooltip on a pointer, and a fact that is one `{ code }` run among others is cut in its middle with its tail whole. In a room place, a row whose only mark is a status keeps it at the end group's start after the words. A blocked tick's reason is the first badge, plain.
|
|
26
|
+
|
|
27
|
+
`title: { code, copy: true }` is a copyable identifier, cut in its middle where it is too long for its space; with `wrap`, and in a fact whose `label` stands before it, it stands whole on as many lines as it takes, at a path's or URL's separators first, then anywhere. A lone `{ code }` fact, where the facts stand under the title, wraps whole at a path's slashes first, so a long path keeps its file's extension.
|
|
28
|
+
|
|
29
|
+
A Section over a tree counts its top-level rows; `counted` says otherwise for one row.
|
package/guide/shell.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Shell
|
|
2
|
+
|
|
3
|
+
The container of the app: a sidebar of places on the desktop, the column alone on touch. A Shell whose places name groups draws the sidebar as a rail of groups beside the group column; one that names none draws the one sidebar. How the sidebar draws, its rail and its tree, is [sidebar](./sidebar.md); the `Panes` it holds are below.
|
|
4
|
+
|
|
5
|
+
## Props
|
|
6
|
+
|
|
7
|
+
- `places`: the places in order, each a `PlaceSpec` (`node_modules/@slotform/ui-core/guide/places.md#placespec`); the current route's is selected. The sidebar's places scroll between the switcher bar and the footer group (the places with `end`), which stay fixed; with groups the footer places stand at the rail's foot as icon links.
|
|
8
|
+
- `groups`: `{ label, icon, switcher?, places? }`, named by a place's `group`; a place naming a group `groups` does not list throws. A group's `places` are a constant or a selection that returns the whole tree: while it waits the heading draws over painted place rows, all inert, and once it failed or is missing the group draws the compact failed or missing shape with Retry in the rows' place. The `icon` is the group's entry on the rail, the `label` its accessible name there, shown beside the icon while the rail is docked or open, and the heading of its places on the touch layer; a `switcher` leads the group's column, and draws under the heading on the touch layer.
|
|
9
|
+
- `switcher`: what the app is looking at and what it can switch to, an `OptionPick` (`label`, `options`, `value`, `onChange`, `placeholder`) whose `options` and `value` are constants or selections, and whose `act` ("New organization") ends its list under a hairline: an act that runs, a sheet it opens, or a link. While a selection waits the switcher paints its avatar and name and keeps its chevron, inert; a value no option matches, or a read that ended, draws the switcher with no name, never its own label as one. With groups it leads the rail, its name and chevron beside its mark while the rail is docked or open, its mark alone on the shut strip; its open menu holds the rail open.
|
|
10
|
+
- `banner`: a `Banner` over the column.
|
|
11
|
+
- `foot`: a part under the place across the column, whatever the route (a `Dock`, [dock](./dock.md)); without one the Shell draws nothing there.
|
|
12
|
+
- `children`: the route's `Pane`s: the place's own, then a record's.
|
|
13
|
+
|
|
14
|
+
## Panes
|
|
15
|
+
|
|
16
|
+
`Panes` (`components/shell`) holds a place's Panes. The `Shell` draws it and gives it the current place's name, so a route inside a `Shell` writes none.
|
|
17
|
+
|
|
18
|
+
| Prop | Is |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| `distance` | `"room"`: the place is read from across a room and draws the room set ([density](./density.md)); only its last Pane stands |
|
|
21
|
+
| `title` | the page's `h1`, drawn apart from sight; a room page with no `Shell` states it once (`<Panes distance="room" title="Deploys">`) |
|
|
22
|
+
| `children` | the place's Pane, then a record's |
|
|
23
|
+
|
|
24
|
+
The place holds two Panes at most, the place's own, then a record's, and throws on a second of a kind. The place's Pane alone fills the place; with a record open it holds `list` (520 px at the default theme `size`) and the record takes the rest. A place's Pane that fills with a `Canvas` is the place's main object: it takes the spare space and the record holds `list`. Below `tablet` of the place only the last Pane stands.
|
|
25
|
+
|
|
26
|
+
The page's one `h1` is the Panes's, the label of the place the sidebar marks current (the app's name where none is). Every `Pane`'s title is an `h2` and its `Section`s start at `h3`, whether the `Pane` stands alone or beside others, so a route passes no level. A `Gate` in a room `Panes` is its own `h1`.
|
package/guide/shots.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Shots and audits
|
|
2
|
+
|
|
3
|
+
How a review that shoots screens holds motion still, and how it audits them with axe. The run that
|
|
4
|
+
shoots an app's screens is `node_modules/@slotform/screens/guide/test-run.md`.
|
|
5
|
+
|
|
6
|
+
## Shots at rest
|
|
7
|
+
|
|
8
|
+
A review that shoots screens (`slotform screens test` does, and so may an app's own browser driver) holds
|
|
9
|
+
motion still with the one setup Slotform's own run uses: emulate `prefers-reduced-motion: reduce` (every
|
|
10
|
+
rung is 0 ms and the pulse stills; CDP's `Emulation.setEmulatedMedia` with the feature
|
|
11
|
+
`prefers-reduced-motion: reduce`, which `slotform screens` sets). The spinner keeps
|
|
12
|
+
turning under it, which is no motion a shot can hold; a driver that wants it still too injects, once
|
|
13
|
+
per page, unlayered:
|
|
14
|
+
|
|
15
|
+
```css
|
|
16
|
+
*, *::before, *::after { transition: none !important; animation: none !important; }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
That rule does not reach an animation that carries state rather than motion. One is a scroll-driven
|
|
20
|
+
animation that decides whether something stands (a record's touch-bar name, `touch:record-name-waits`,
|
|
21
|
+
hidden until the head's name has scrolled under the bar): it has no duration for reduced motion to
|
|
22
|
+
zero, and a shot with it off would show only its fallback, the name always standing. Such an
|
|
23
|
+
animation is written `!important` in a cascade layer (the component's utility is in `utilities`), and
|
|
24
|
+
an important declaration in a layer beats an unlayered important one, so the setup above leaves it
|
|
25
|
+
running without knowing its name. A driver injects its rule unlayered, never into a `@layer`, and a part
|
|
26
|
+
that adds an animation that carries state does the same.
|
|
27
|
+
|
|
28
|
+
The marks that change are no such animation: a swapped mark's old one and an act's fading glyph are
|
|
29
|
+
hidden in their own style and animate `from` their rest, and the new mark and the pending spinner
|
|
30
|
+
animate `from` hidden, so a setup that turns animations off draws the new mark and the spinner alone,
|
|
31
|
+
never the old one under it, and an old mark whose removal a busy page delays is already invisible. A
|
|
32
|
+
part that adds an exit writes it so (a `from` keyframe over an end state in its style), never a `to`
|
|
33
|
+
keyframe that leaves the part standing once animations are off.
|
|
34
|
+
|
|
35
|
+
## Auditing with axe
|
|
36
|
+
|
|
37
|
+
Run every axe rule, as Slotform's run does: the page-level ones (`region`) and `target-size` included, nothing excluded for an open popup (`node_modules/@slotform/screens/guide/test-run.md`, "Limits").
|
package/guide/sidebar.md
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# The sidebar
|
|
2
|
+
|
|
3
|
+
How the `Shell`'s sidebar draws: the rail of groups and the places' tree. What the `Shell` takes is [shell](./shell.md).
|
|
4
|
+
|
|
5
|
+
## The rail of groups
|
|
6
|
+
|
|
7
|
+
The rail and the column each lead with a switcher region at a Pane bar's height, the app's switcher in the rail's and the group's in the column's (empty for a group with none), so the column's switcher stands level with the app's and its first place level with the rail's first entry. A group whose places landed empty keeps its switcher, so its act can make the first, and the switcher draws its `placeholder` while it has nothing to switch to.
|
|
8
|
+
|
|
9
|
+
The rail's first entry is the ungrouped places, named and drawn by their first place; the others follow in `groups`' order. A press on an entry goes to its group's first place. Docked (the default), the rail stands with its labels and the column of the current place's group beside it, until the viewer folds it to the icons with the act at the rail's foot; the choice holds from one visit to the next, and the same act docks it again. As it docks or folds, the page takes its new space at once and slides from where it stood, its edge on the sidebar's end.
|
|
10
|
+
|
|
11
|
+
Hovering or focusing an entry shows its group's column: docked, in the column's place at once; folded, after a short dwell (so a sweep across the rail changes nothing), by opening the sidebar over the page, the rail's labels uncovered and the column sliding out from behind it, another entry's group then showing at once. The sidebar opens and shuts as one body on `base` `out`, by clip and transform alone, snapping under reduced motion. A pointer heading for the column keeps the group shown while it crosses other entries (a menu aim: the switch waits until the pointer rests or turns away). The column goes back (to the current place's group, or to the rail) once the pointer and the focus have left the rail and the column a moment, on Escape, or when the route changes. A menu the column opened (a switcher's), or a sheet one of its acts opened, holds it open, so a project can be switched, or an asset made, from the hover. A footer place's entry and the dock act expand nothing: on the folded rail each shows its label as a tooltip, and a footer place's entry goes to its place.
|
|
12
|
+
|
|
13
|
+
On touch the places layer lists the groups first; a tap shows that group's places with a way back to the list.
|
|
14
|
+
|
|
15
|
+
## The tree
|
|
16
|
+
|
|
17
|
+
A place with `children` is a branch (`node_modules/@slotform/ui-core/guide/places.md#placespec`). A branch has a fold act at the end of its row; its children stand one `stack` space in per level. The browser keeps the viewer's open and folded branches per branch route; a branch they never chose is open when the current place is at or under it, else folded. The places on the path to the current one (its folded ancestors too) take the selected ink, while only the current one takes the wash and the bar.
|
|
18
|
+
|
|
19
|
+
Every run of places, flat or nested, the footer group included, is a WAI-ARIA tree with one tab stop (the current place's row, else the first):
|
|
20
|
+
|
|
21
|
+
| Key | Does |
|
|
22
|
+
| --- | --- |
|
|
23
|
+
| Up, Down | moves between the visible rows |
|
|
24
|
+
| Right | opens a folded branch, steps into an open one |
|
|
25
|
+
| Left | folds a branch, steps out to the parent |
|
|
26
|
+
| Home, End | the first and the last visible row |
|
|
27
|
+
| Enter | opens the place |
|
|
28
|
+
| Space | nothing |
|
|
29
|
+
|
|
30
|
+
A branch whose route is a spot (`#folder-7`) is no page: pressing it, or Enter on it, only opens and folds it. Only open branches mount their children, so a place inside a folded branch takes no pointer drop until the branch opens; how a drag reaches it is [drag](./drag.md).
|