shelving 1.322.0 → 1.322.2
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/docs/api/APIProvider.md +2 -2
- package/docs/api/CachedAPIProvider.md +6 -8
- package/docs/api/ClientAPIProvider.md +5 -5
- package/docs/api/DebugAPIProvider.md +3 -5
- package/docs/api/HydratingAPIProvider.md +2 -2
- package/docs/api/JSONAPIProvider.md +3 -5
- package/docs/api/LoggingAPIProvider.md +7 -9
- package/docs/api/MockAPIProvider.md +4 -4
- package/docs/api/MockEndpointAPIProvider.md +5 -7
- package/docs/api/ThroughAPIProvider.md +15 -10
- package/docs/api/ValidationAPIProvider.md +3 -5
- package/docs/api/XMLAPIProvider.md +3 -3
- package/docs/api.md +48 -44
- package/docs/bun.md +9 -9
- package/docs/db/DBProvider.md +6 -6
- package/docs/db/MemoryDBProvider.md +3 -3
- package/docs/db/PostgresProvider.md +6 -4
- package/docs/db/SQLProvider.md +6 -3
- package/docs/db/SQLiteProvider.md +9 -4
- package/docs/db/StorageDBProvider.md +2 -2
- package/docs/db/ThroughDBProvider.md +6 -6
- package/docs/db/UndoDBProvider.md +2 -2
- package/docs/db.md +32 -32
- package/docs/error/NetworkError.md +5 -5
- package/docs/error/RequestError.md +4 -4
- package/docs/error/RequiredError.md +2 -2
- package/docs/error/ResponseError.md +1 -1
- package/docs/error/UnexpectedError.md +1 -1
- package/docs/error/UnsupportedError.md +3 -3
- package/docs/error/ValueError.md +2 -2
- package/docs/error.md +20 -19
- package/docs/extract.md +14 -14
- package/docs/firebase.md +6 -6
- package/docs/guides/building-with-shelving.md +113 -85
- package/docs/guides/styleguide.md +29 -29
- package/docs/index.md +3 -2
- package/docs/llms-full.txt +2541 -2295
- package/docs/markup.md +15 -17
- package/docs/react/createAPIContext.md +12 -12
- package/docs/react/createDBContext.md +21 -15
- package/docs/react/useInstance.md +2 -2
- package/docs/react/useLazy.md +1 -1
- package/docs/react/useMap.md +10 -6
- package/docs/react/useReduce.md +2 -2
- package/docs/react/useSequence.md +2 -2
- package/docs/react/useStore.md +10 -10
- package/docs/react.md +22 -16
- package/docs/schema/ArraySchema.md +6 -6
- package/docs/schema/BooleanSchema.md +5 -5
- package/docs/schema/ChoiceSchema.md +1 -1
- package/docs/schema/CurrencyAmountSchema.md +2 -2
- package/docs/schema/DataSchema.md +5 -5
- package/docs/schema/NullableSchema.md +4 -4
- package/docs/schema/NumberSchema.md +4 -4
- package/docs/schema/OptionalSchema.md +1 -1
- package/docs/schema/StringSchema.md +7 -7
- package/docs/schema.md +21 -21
- package/docs/sequence/DeferredSequence.md +1 -1
- package/docs/sequence/InspectSequence.md +8 -6
- package/docs/sequence/LazySequence.md +3 -3
- package/docs/sequence/Sequence.md +6 -6
- package/docs/sequence/ThroughSequence.md +4 -2
- package/docs/sequence.md +3 -3
- package/docs/store/ArrayStore.md +6 -6
- package/docs/store/BooleanStore.md +2 -2
- package/docs/store/BusyStore.md +1 -1
- package/docs/store/DataStore.md +5 -5
- package/docs/store/DictionaryStore.md +4 -4
- package/docs/store/FetchStore.md +6 -6
- package/docs/store/PathStore.md +4 -4
- package/docs/store/PayloadFetchStore.md +1 -5
- package/docs/store/Store.md +8 -6
- package/docs/store/URLStore.md +5 -5
- package/docs/store.md +15 -15
- package/docs/test.md +6 -6
- package/docs/ui/App.md +99 -69
- package/docs/ui/AppLayout.md +35 -26
- package/docs/ui/BackButton.md +13 -11
- package/docs/ui/Button.md +73 -64
- package/docs/ui/Card.md +23 -22
- package/docs/ui/Catcher.md +3 -3
- package/docs/ui/ClassProps.md +1 -1
- package/docs/ui/Code.md +11 -11
- package/docs/ui/CollapseTransition.md +5 -5
- package/docs/ui/Deleted.md +6 -6
- package/docs/ui/Details.md +13 -13
- package/docs/ui/Dialog.md +42 -28
- package/docs/ui/Dialogs.md +4 -0
- package/docs/ui/DocumentationButtons.md +2 -2
- package/docs/ui/DocumentationCard.md +2 -2
- package/docs/ui/DocumentationFrame.md +4 -4
- package/docs/ui/DocumentationLive.md +11 -11
- package/docs/ui/DocumentationPage.md +3 -3
- package/docs/ui/Emphasis.md +4 -4
- package/docs/ui/Empty.md +2 -2
- package/docs/ui/FadeTransition.md +9 -9
- package/docs/ui/Field.md +14 -14
- package/docs/ui/FixedLayout.md +27 -25
- package/docs/ui/Form.md +41 -39
- package/docs/ui/FormStore.md +6 -2
- package/docs/ui/Grid.md +21 -9
- package/docs/ui/HTML.md +10 -8
- package/docs/ui/Head.md +2 -3
- package/docs/ui/Heading.md +12 -12
- package/docs/ui/HorizontalTransition.md +10 -10
- package/docs/ui/Icon.md +4 -4
- package/docs/ui/ImageInput.md +12 -12
- package/docs/ui/Inserted.md +6 -6
- package/docs/ui/Link.md +11 -11
- package/docs/ui/List.md +7 -7
- package/docs/ui/Loading.md +6 -6
- package/docs/ui/Mark.md +11 -9
- package/docs/ui/Markup.md +4 -4
- package/docs/ui/Menu.md +24 -24
- package/docs/ui/MenuItem.md +29 -29
- package/docs/ui/Modal.md +57 -45
- package/docs/ui/Navigation.md +28 -26
- package/docs/ui/NavigationStore.md +18 -18
- package/docs/ui/Notice.md +15 -15
- package/docs/ui/Notices.md +17 -17
- package/docs/ui/Page.md +13 -13
- package/docs/ui/Panel.md +8 -8
- package/docs/ui/Paragraph.md +5 -5
- package/docs/ui/Progress.md +11 -11
- package/docs/ui/Prose.md +6 -6
- package/docs/ui/QueryRadiosInput.md +2 -2
- package/docs/ui/RouteCache.md +27 -27
- package/docs/ui/Router.md +70 -61
- package/docs/ui/SchemaInput.md +20 -20
- package/docs/ui/Scroll.md +16 -16
- package/docs/ui/Section.md +13 -10
- package/docs/ui/SidebarLayout.md +27 -27
- package/docs/ui/Small.md +4 -4
- package/docs/ui/Span.md +3 -1
- package/docs/ui/StackButton.md +13 -7
- package/docs/ui/Strong.md +4 -4
- package/docs/ui/Subheading.md +12 -12
- package/docs/ui/TINT_CLASS.md +11 -11
- package/docs/ui/Table.md +40 -29
- package/docs/ui/Tag.md +15 -15
- package/docs/ui/Title.md +13 -13
- package/docs/ui/Transition.md +22 -22
- package/docs/ui/TreeApp.md +8 -8
- package/docs/ui/TreeMarkup.md +2 -2
- package/docs/ui/TreeMenu.md +3 -3
- package/docs/ui/TreeSidebar.md +1 -1
- package/docs/ui/VerticalTransition.md +8 -8
- package/docs/ui/getClass.md +10 -10
- package/docs/ui/getColorClass.md +23 -23
- package/docs/ui/getDurationClass.md +5 -5
- package/docs/ui/getGridClass.md +2 -2
- package/docs/ui/getHeightClass.md +4 -4
- package/docs/ui/getRadiusClass.md +9 -9
- package/docs/ui/getShadowClass.md +6 -6
- package/docs/ui/getSpaceClass.md +13 -13
- package/docs/ui/getStrokeClass.md +6 -6
- package/docs/ui/getTypographyClass.md +38 -38
- package/docs/ui/getWidthClass.md +4 -4
- package/docs/ui/notify.md +11 -11
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui.md +4 -4
- package/docs/util/array.md +35 -29
- package/docs/util/async.md +2 -2
- package/docs/util/base64.md +7 -7
- package/docs/util/boolean.md +10 -10
- package/docs/util/buffer.md +5 -5
- package/docs/util/bytes.md +9 -9
- package/docs/util/class.md +10 -6
- package/docs/util/color.md +13 -13
- package/docs/util/constants.md +2 -2
- package/docs/util/crypto.md +1 -1
- package/docs/util/currency.md +2 -2
- package/docs/util/data.md +18 -18
- package/docs/util/date.md +22 -22
- package/docs/util/debug/debug.md +12 -12
- package/docs/util/dictionary.md +21 -18
- package/docs/util/diff.md +6 -6
- package/docs/util/dispose/dispose.md +5 -5
- package/docs/util/duration.md +9 -9
- package/docs/util/element.md +1 -1
- package/docs/util/entity.md +6 -6
- package/docs/util/entry.md +21 -8
- package/docs/util/env.md +2 -2
- package/docs/util/equal.md +16 -16
- package/docs/util/error.md +4 -4
- package/docs/util/file.md +8 -8
- package/docs/util/filter.md +9 -5
- package/docs/util/format.md +18 -18
- package/docs/util/function.md +4 -4
- package/docs/util/geo.md +13 -13
- package/docs/util/hash.md +3 -3
- package/docs/util/http.md +1 -1
- package/docs/util/hydrate/hydrate.md +7 -4
- package/docs/util/item.md +4 -4
- package/docs/util/iterate.md +11 -11
- package/docs/util/jwt.md +1 -6
- package/docs/util/link.md +5 -5
- package/docs/util/map.md +17 -11
- package/docs/util/merge.md +2 -5
- package/docs/util/null.md +20 -10
- package/docs/util/number.md +16 -16
- package/docs/util/object.md +25 -22
- package/docs/util/path.md +17 -17
- package/docs/util/query.md +23 -25
- package/docs/util/random.md +7 -7
- package/docs/util/regexp.md +16 -16
- package/docs/util/sequence.md +16 -10
- package/docs/util/serialise/serialise.md +6 -6
- package/docs/util/set.md +10 -10
- package/docs/util/sort.md +10 -11
- package/docs/util/source.md +11 -7
- package/docs/util/start.md +8 -8
- package/docs/util/string.md +14 -14
- package/docs/util/template.md +3 -3
- package/docs/util/timeout.md +5 -5
- package/docs/util/transform.md +6 -6
- package/docs/util/tree.md +13 -13
- package/docs/util/undefined.md +3 -3
- package/docs/util/units.md +15 -15
- package/docs/util/update.md +16 -16
- package/docs/util/uri.md +12 -12
- package/docs/util/url.md +11 -11
- package/docs/util/uuid.md +3 -3
- package/docs/util/validate.md +14 -9
- package/package.json +3 -3
- package/skills/shelving/SKILL.md +1 -0
- package/ui/README.md +4 -4
- package/ui/app/App.md +99 -69
- package/ui/block/Card.md +23 -22
- package/ui/block/Details.md +13 -13
- package/ui/block/Grid.md +21 -9
- package/ui/block/Heading.md +12 -12
- package/ui/block/List.md +7 -7
- package/ui/block/Panel.md +8 -8
- package/ui/block/Paragraph.md +5 -5
- package/ui/block/Prose.md +6 -6
- package/ui/block/Section.md +13 -10
- package/ui/block/Subheading.md +12 -12
- package/ui/block/Title.md +13 -13
- package/ui/button/Button.md +73 -64
- package/ui/dialog/Dialog.md +42 -28
- package/ui/dialog/Dialogs.d.ts +4 -0
- package/ui/dialog/Dialogs.js +4 -0
- package/ui/dialog/Dialogs.tsx +4 -0
- package/ui/dialog/Modal.md +57 -45
- package/ui/docs/DocumentationButtons.md +2 -2
- package/ui/docs/DocumentationCard.md +2 -2
- package/ui/docs/DocumentationFrame.md +4 -4
- package/ui/docs/DocumentationLive.md +11 -11
- package/ui/docs/DocumentationPage.md +3 -3
- package/ui/form/Field.md +14 -14
- package/ui/form/Form.md +41 -39
- package/ui/form/FormStore.md +6 -2
- package/ui/form/Progress.md +11 -11
- package/ui/inline/Code.md +11 -11
- package/ui/inline/Deleted.md +6 -6
- package/ui/inline/Emphasis.md +4 -4
- package/ui/inline/Inserted.md +6 -6
- package/ui/inline/Link.md +11 -11
- package/ui/inline/Mark.md +11 -9
- package/ui/inline/Small.md +4 -4
- package/ui/inline/Span.md +3 -1
- package/ui/inline/Strong.md +4 -4
- package/ui/input/ImageInput.md +12 -12
- package/ui/input/QueryRadiosInput.md +2 -2
- package/ui/input/SchemaInput.md +20 -20
- package/ui/layout/AppLayout.md +35 -26
- package/ui/layout/AppLayout.module.css +3 -16
- package/ui/layout/FixedLayout.md +27 -25
- package/ui/layout/SidebarLayout.md +27 -27
- package/ui/layout/SidebarLayout.module.css +1 -0
- package/ui/menu/Menu.md +24 -24
- package/ui/menu/MenuItem.md +29 -29
- package/ui/misc/Catcher.md +3 -3
- package/ui/misc/Icon.md +4 -4
- package/ui/misc/Loading.md +6 -6
- package/ui/misc/Markup.md +4 -4
- package/ui/misc/Tag.md +15 -15
- package/ui/notice/Empty.md +2 -2
- package/ui/notice/Notice.md +15 -15
- package/ui/notice/Notices.md +17 -17
- package/ui/page/HTML.md +10 -8
- package/ui/page/Head.md +2 -3
- package/ui/page/Page.md +13 -13
- package/ui/router/BackButton.md +13 -11
- package/ui/router/Navigation.md +28 -26
- package/ui/router/NavigationStore.md +18 -18
- package/ui/router/RouteCache.md +27 -27
- package/ui/router/Router.md +70 -61
- package/ui/router/StackButton.md +13 -7
- package/ui/style/Scroll.md +16 -16
- package/ui/style/TINT_CLASS.md +11 -11
- package/ui/style/getColorClass.md +23 -23
- package/ui/style/getDurationClass.md +5 -5
- package/ui/style/getGridClass.md +2 -2
- package/ui/style/getHeightClass.md +4 -4
- package/ui/style/getRadiusClass.md +9 -9
- package/ui/style/getShadowClass.md +6 -6
- package/ui/style/getSpaceClass.md +13 -13
- package/ui/style/getStrokeClass.md +6 -6
- package/ui/style/getTypographyClass.md +38 -38
- package/ui/style/getWidthClass.md +4 -4
- package/ui/table/Table.md +40 -30
- package/ui/transition/CollapseTransition.md +5 -5
- package/ui/transition/FadeTransition.md +9 -9
- package/ui/transition/HorizontalTransition.md +10 -10
- package/ui/transition/Transition.md +22 -22
- package/ui/transition/VerticalTransition.md +8 -8
- package/ui/tree/TreeApp.md +8 -8
- package/ui/tree/TreeMarkup.md +2 -2
- package/ui/tree/TreeMenu.md +3 -3
- package/ui/tree/TreeSidebar.md +1 -1
- package/ui/util/ClassProps.md +1 -1
- package/ui/util/getClass.md +10 -10
- package/ui/util/notify.md +11 -11
- package/ui/util/requireContext.md +1 -1
package/ui/misc/Catcher.md
CHANGED
|
@@ -29,7 +29,7 @@ import { Catcher, ErrorPage, RetryButton } from "shelving/ui";
|
|
|
29
29
|
|
|
30
30
|
// Custom error renderer plus a retry button anywhere in the subtree.
|
|
31
31
|
<Catcher as={ErrorPage}>
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
</Catcher
|
|
32
|
+
<RiskyComponent />
|
|
33
|
+
<RetryButton small />
|
|
34
|
+
</Catcher>;
|
|
35
35
|
```
|
package/ui/misc/Icon.md
CHANGED
|
@@ -20,9 +20,9 @@ import { Icon } from "shelving/ui";
|
|
|
20
20
|
|
|
21
21
|
## Styling
|
|
22
22
|
|
|
23
|
-
| Variable
|
|
24
|
-
|
|
25
|
-
| `--icon-color` | Icon colour
|
|
26
|
-
| `--icon-size`
|
|
23
|
+
| Variable | Styles | Default |
|
|
24
|
+
| -------------- | ------------------- | ------------------------------------------------------------------------------- |
|
|
25
|
+
| `--icon-color` | Icon colour | `var(--tint-50)` (the status tint, e.g. `--color-failure` for `status="error"`) |
|
|
26
|
+
| `--icon-size` | Icon width / height | `var(--size-icon)` (1.5rem) |
|
|
27
27
|
|
|
28
28
|
**Global tokens it reads** — the status tint anchor `--tint-50`, `--size-icon` (the unset-`size` default), plus the size tokens `--size-small` / `--size-normal` / `--size-large` / `--size-xlarge` / `--size-xxlarge` used by the `size` prop.
|
package/ui/misc/Loading.md
CHANGED
|
@@ -32,11 +32,11 @@ import { Icon, LOADING, Loading } from "shelving/ui";
|
|
|
32
32
|
|
|
33
33
|
Size, centring, and overall colour come from wrapping it in `<Icon>` — its `--icon-color` / `--icon-size` hooks and `color` / `status` / `size` / `tint` variants drive the spinner (see the `Icon` Styling section). On top of that, the two arcs expose their own hooks:
|
|
34
34
|
|
|
35
|
-
| Variable
|
|
36
|
-
|
|
37
|
-
| `--loading-track`
|
|
38
|
-
| `--loading-indicator`
|
|
39
|
-
| `--loading-stroke-width` | Stroke width of both arcs
|
|
40
|
-
| `--loading-length`
|
|
35
|
+
| Variable | Styles | Default |
|
|
36
|
+
| ------------------------ | --------------------------------------- | ---------------- |
|
|
37
|
+
| `--loading-track` | Track (background arc) stroke | `var(--tint-70)` |
|
|
38
|
+
| `--loading-indicator` | Indicator (moving arc) stroke | `var(--tint-80)` |
|
|
39
|
+
| `--loading-stroke-width` | Stroke width of both arcs | `2.5` |
|
|
40
|
+
| `--loading-length` | `stroke-dasharray` of the indicator arc | `28 100` |
|
|
41
41
|
|
|
42
42
|
**Global tokens it reads** — the tint-ladder steps `--tint-70` / `--tint-80` for the arc strokes (rebound by the `color` / `status` / `tint` variants on the wrapping `<Icon>`).
|
package/ui/misc/Markup.md
CHANGED
|
@@ -15,8 +15,8 @@ Parses a markup string and renders the resulting React nodes inline. Defaults to
|
|
|
15
15
|
import { Prose, Markup } from "shelving/ui";
|
|
16
16
|
|
|
17
17
|
<Prose>
|
|
18
|
-
|
|
19
|
-
</Prose
|
|
18
|
+
<Markup>{article.body}</Markup>
|
|
19
|
+
</Prose>;
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
```tsx
|
|
@@ -24,6 +24,6 @@ import { Markup } from "shelving/ui";
|
|
|
24
24
|
|
|
25
25
|
// Custom rule set or base URL via MarkupOptions props.
|
|
26
26
|
<Markup rules={INLINE_ONLY} root="https://example.com">
|
|
27
|
-
|
|
28
|
-
</Markup
|
|
27
|
+
{comment.body}
|
|
28
|
+
</Markup>;
|
|
29
29
|
```
|
package/ui/misc/Tag.md
CHANGED
|
@@ -22,20 +22,20 @@ import { Tag } from "shelving/ui";
|
|
|
22
22
|
|
|
23
23
|
`Tag` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the tag or an ancestor scope) to recolour the whole tag at once.
|
|
24
24
|
|
|
25
|
-
| Variable
|
|
26
|
-
|
|
27
|
-
| `--tag-background`
|
|
28
|
-
| `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)`
|
|
29
|
-
| `--tag-color`
|
|
30
|
-
| `--tag-padding`
|
|
31
|
-
| `--tag-indent`
|
|
32
|
-
| `--tag-border`
|
|
33
|
-
| `--tag-radius`
|
|
34
|
-
| `--tag-font`
|
|
35
|
-
| `--tag-size`
|
|
36
|
-
| `--tag-weight`
|
|
37
|
-
| `--tag-leading`
|
|
38
|
-
| `--tag-case`
|
|
39
|
-
| `--tag-focus-border`
|
|
25
|
+
| Variable | Styles | Default |
|
|
26
|
+
| ------------------------ | ----------------------------------------------- | ---------------------------------------------- |
|
|
27
|
+
| `--tag-background` | Surface fill | `var(--tint-50)` |
|
|
28
|
+
| `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
|
|
29
|
+
| `--tag-color` | Text colour | `var(--tint-100)` |
|
|
30
|
+
| `--tag-padding` | Inner top and bottom padding (one length) | `0` |
|
|
31
|
+
| `--tag-indent` | Inner left and right padding (one length) | `var(--space-xxsmall)` (4px) |
|
|
32
|
+
| `--tag-border` | Border shorthand | `0` |
|
|
33
|
+
| `--tag-radius` | Corner radius | `var(--radius-xxsmall)` |
|
|
34
|
+
| `--tag-font` | Font family | `var(--font-body)` |
|
|
35
|
+
| `--tag-size` | Font size | `var(--size-small)` |
|
|
36
|
+
| `--tag-weight` | Font weight | `var(--weight-strong)` |
|
|
37
|
+
| `--tag-leading` | Line height | `var(--leading)` |
|
|
38
|
+
| `--tag-case` | Text transform | `var(--case-label)` |
|
|
39
|
+
| `--tag-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
|
|
40
40
|
|
|
41
41
|
**Global tokens it reads** — the tint ladder `--tint-50` / `--tint-55` / `--tint-100`, plus `--space-xxsmall`, `--radius-xxsmall`, `--font-body`, `--size-small`, `--weight-strong`, `--leading`, `--case-label`, `--stroke-normal`, `--stroke-focus`, and `--color-focus`.
|
package/ui/notice/Empty.md
CHANGED
|
@@ -17,7 +17,7 @@ import { Empty, Paragraph } from "shelving/ui";
|
|
|
17
17
|
|
|
18
18
|
<Empty>
|
|
19
19
|
<Paragraph>No challenges yet.</Paragraph>
|
|
20
|
-
</Empty
|
|
20
|
+
</Empty>;
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
### Loading list
|
|
@@ -27,7 +27,7 @@ import { EMPTY_LOADING, Loader } from "shelving/ui";
|
|
|
27
27
|
|
|
28
28
|
<Loader fallback={EMPTY_LOADING}>
|
|
29
29
|
<LoadChallenges />
|
|
30
|
-
</Loader
|
|
30
|
+
</Loader>;
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
## Styling
|
package/ui/notice/Notice.md
CHANGED
|
@@ -22,26 +22,26 @@ import { Notice } from "shelving/ui";
|
|
|
22
22
|
import { LOADING_NOTICE } from "shelving/ui";
|
|
23
23
|
|
|
24
24
|
<Suspense fallback={LOADING_NOTICE}>
|
|
25
|
-
|
|
26
|
-
</Suspense
|
|
25
|
+
<SlowPanel />
|
|
26
|
+
</Suspense>;
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
## Styling
|
|
30
30
|
|
|
31
31
|
`Notice` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Its `status` (or a `color=` / `status=` on an ancestor scope) sets the tint that the surface, border, and text all derive from; reach for a per-property hook for a single change.
|
|
32
32
|
|
|
33
|
-
| Variable
|
|
34
|
-
|
|
35
|
-
| `--notice-background` | Surface fill
|
|
36
|
-
| `--notice-color`
|
|
37
|
-
| `--notice-border`
|
|
38
|
-
| `--notice-stroke`
|
|
39
|
-
| `--notice-shadow`
|
|
40
|
-
| `--notice-radius`
|
|
41
|
-
| `--notice-padding`
|
|
42
|
-
| `--notice-indent`
|
|
43
|
-
| `--notice-space`
|
|
44
|
-
| `--notice-size`
|
|
45
|
-
| `--notice-weight`
|
|
33
|
+
| Variable | Styles | Default |
|
|
34
|
+
| --------------------- | ---------------------------------------------- | ------------------------------------------- |
|
|
35
|
+
| `--notice-background` | Surface fill | `var(--tint-90)` |
|
|
36
|
+
| `--notice-color` | Text colour | `var(--tint-50)` |
|
|
37
|
+
| `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |
|
|
38
|
+
| `--notice-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
|
|
39
|
+
| `--notice-shadow` | Drop shadow, for example `var(--shadow-small)` | `none` |
|
|
40
|
+
| `--notice-radius` | Corner radius | `var(--radius-xsmall)` |
|
|
41
|
+
| `--notice-padding` | Inner top and bottom padding (one length) | `var(--space-small)` (12px) |
|
|
42
|
+
| `--notice-indent` | Inner left and right padding (one length) | `var(--space-small)` (12px) |
|
|
43
|
+
| `--notice-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` |
|
|
44
|
+
| `--notice-size` | Font size | `var(--size-normal)` |
|
|
45
|
+
| `--notice-weight` | Font weight | `var(--weight-strong)` |
|
|
46
46
|
|
|
47
47
|
**Global tokens it reads** — the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-small`, `--radius-xsmall`, `--stroke-normal`, `--size-normal`, and `--weight-strong`.
|
package/ui/notice/Notices.md
CHANGED
|
@@ -19,25 +19,25 @@ Mount once near the root of your app:
|
|
|
19
19
|
import { Notices } from "shelving/ui";
|
|
20
20
|
|
|
21
21
|
export function AppLayout({ children }) {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
22
|
+
return (
|
|
23
|
+
<>
|
|
24
|
+
{children}
|
|
25
|
+
<Notices />
|
|
26
|
+
</>
|
|
27
|
+
);
|
|
28
28
|
}
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
Show the list in the top-left corner:
|
|
32
32
|
|
|
33
33
|
```tsx
|
|
34
|
-
<Notices position="top-left"
|
|
34
|
+
<Notices position="top-left" />;
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
Show the list at the top of the screen, in the centre:
|
|
38
38
|
|
|
39
39
|
```tsx
|
|
40
|
-
<Notices position="top-center"
|
|
40
|
+
<Notices position="top-center" />;
|
|
41
41
|
```
|
|
42
42
|
|
|
43
43
|
Dispatch notices from anywhere — no context required:
|
|
@@ -50,8 +50,8 @@ notifyError("Could not connect.");
|
|
|
50
50
|
|
|
51
51
|
// Wrap an async callback — dispatches success or error automatically.
|
|
52
52
|
callNotified(async () => {
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
await saveProfile(data);
|
|
54
|
+
return "Profile updated.";
|
|
55
55
|
});
|
|
56
56
|
```
|
|
57
57
|
|
|
@@ -71,12 +71,12 @@ notice.close(); // Or close it immediately.
|
|
|
71
71
|
|
|
72
72
|
`Notices` positions the list in the place that `position` sets. Each notice is only as wide as its content and is aligned to the side of that corner, or to the centre. The list is never wider than `--notices-width`, and keeps `--notices-offset` clear at both sides on a narrow screen. The offset also adds the safe area of the device (`env(safe-area-inset-*)`). Clicks pass through the gaps between notices to the page. Each item is a `<Notice>`, which has its own hooks. Override these hooks at `:root` (or any ancestor scope) to retheme.
|
|
73
73
|
|
|
74
|
-
| Variable
|
|
75
|
-
|
|
76
|
-
| `--notices-offset`
|
|
77
|
-
| `--notices-width`
|
|
78
|
-
| `--notices-shadow`
|
|
79
|
-
| `--notices-gap`
|
|
80
|
-
| `--notices-transition-duration` | Length of the slide in, slide out, and move
|
|
74
|
+
| Variable | Styles | Default |
|
|
75
|
+
| ------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
|
|
76
|
+
| `--notices-offset` | Distance of the list from the top or bottom edge, and from the left and right edges | `var(--space-normal)` (16px) |
|
|
77
|
+
| `--notices-width` | Maximum width of the list and of each notice | `var(--width-narrow)` |
|
|
78
|
+
| `--notices-shadow` | Drop shadow under each notice in the list (sets `--notice-shadow`) | `var(--shadow-normal)` |
|
|
79
|
+
| `--notices-gap` | Gap between notices | `var(--space-small)` (12px) |
|
|
80
|
+
| `--notices-transition-duration` | Length of the slide in, slide out, and move | `var(--duration-fast)` (150ms) |
|
|
81
81
|
|
|
82
82
|
**Global tokens it reads** — move these to retheme broadly: `--space-normal`, `--space-small`, `--shadow-normal`, `--width-narrow`, and `--duration-fast`.
|
package/ui/page/HTML.md
CHANGED
|
@@ -16,14 +16,16 @@ import { Navigation, Router } from "shelving/ui";
|
|
|
16
16
|
|
|
17
17
|
// Server-side render — pass the request URL to <HTML>.
|
|
18
18
|
renderToString(
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
19
|
+
<HTML app="My App" root="https://example.com/" url={requestUrl} language="en">
|
|
20
|
+
<Navigation>
|
|
21
|
+
<Router
|
|
22
|
+
routes={{
|
|
23
|
+
"/": HomePage,
|
|
24
|
+
"/about": AboutPage,
|
|
25
|
+
}}
|
|
26
|
+
/>
|
|
27
|
+
</Navigation>
|
|
28
|
+
</HTML>,
|
|
27
29
|
);
|
|
28
30
|
```
|
|
29
31
|
|
package/ui/page/Head.md
CHANGED
package/ui/page/Page.md
CHANGED
|
@@ -14,11 +14,11 @@ Wraps one page (or screen) inside an app, applying its per-page metadata. It mer
|
|
|
14
14
|
import { Page, Section } from "shelving/ui";
|
|
15
15
|
|
|
16
16
|
function UserPage({ id }: { id: string }) {
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
17
|
+
return (
|
|
18
|
+
<Page title="User profile" url={`/users/${id}`} description="View user details.">
|
|
19
|
+
<Section>…</Section>
|
|
20
|
+
</Page>
|
|
21
|
+
);
|
|
22
22
|
}
|
|
23
23
|
```
|
|
24
24
|
|
|
@@ -28,12 +28,12 @@ A page renders no layout. The layout goes outside the page, above the router, so
|
|
|
28
28
|
import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
|
|
29
29
|
|
|
30
30
|
<FixedLayout>
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
</FixedLayout
|
|
31
|
+
<Scroll vertical cover>
|
|
32
|
+
<Page title="Sign in">
|
|
33
|
+
<Block height="full" middle width="narrow">
|
|
34
|
+
<LoginForm />
|
|
35
|
+
</Block>
|
|
36
|
+
</Page>
|
|
37
|
+
</Scroll>
|
|
38
|
+
</FixedLayout>;
|
|
39
39
|
```
|
package/ui/router/BackButton.md
CHANGED
|
@@ -18,28 +18,30 @@ The back button for a page header. It goes back to the page before this one in t
|
|
|
18
18
|
import { BackButton } from "shelving/ui";
|
|
19
19
|
|
|
20
20
|
function PostPage({ id }: { id: string }) {
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
21
|
+
return (
|
|
22
|
+
<>
|
|
23
|
+
<header>
|
|
24
|
+
<BackButton href="/home" />
|
|
25
|
+
<h1>Post</h1>
|
|
26
|
+
</header>
|
|
27
|
+
{/* … */}
|
|
28
|
+
</>
|
|
29
|
+
);
|
|
30
30
|
}
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
With a label:
|
|
34
34
|
|
|
35
35
|
```tsx
|
|
36
|
-
<BackButton href="/profile">Back to profile</BackButton
|
|
36
|
+
<BackButton href="/profile">Back to profile</BackButton>;
|
|
37
37
|
```
|
|
38
38
|
|
|
39
39
|
To go back to one fixed page (not to the page before), use a link with `className="back"`:
|
|
40
40
|
|
|
41
41
|
```tsx
|
|
42
|
-
<Button href="/profile" className="back">
|
|
42
|
+
<Button href="/profile" className="back">
|
|
43
|
+
Profile
|
|
44
|
+
</Button>;
|
|
43
45
|
```
|
|
44
46
|
|
|
45
47
|
## Styling
|
package/ui/router/Navigation.md
CHANGED
|
@@ -33,10 +33,10 @@ Stacks and slides use the browser [Navigation API](https://developer.mozilla.org
|
|
|
33
33
|
import { App, Navigation, Router } from "shelving/ui";
|
|
34
34
|
|
|
35
35
|
<App root="https://example.com/">
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
</App
|
|
36
|
+
<Navigation>
|
|
37
|
+
<Router routes={ROUTES} />
|
|
38
|
+
</Navigation>
|
|
39
|
+
</App>;
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
### App with a tab bar
|
|
@@ -48,27 +48,29 @@ import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCach
|
|
|
48
48
|
|
|
49
49
|
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
50
50
|
|
|
51
|
-
const TABS =
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
51
|
+
const TABS = (
|
|
52
|
+
<>
|
|
53
|
+
<StackButton stack="/home">Home</StackButton>
|
|
54
|
+
<StackButton stack="/discover">Discover</StackButton>
|
|
55
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
56
|
+
</>
|
|
57
|
+
);
|
|
56
58
|
|
|
57
59
|
<App root="https://example.com/">
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
</App
|
|
60
|
+
<Navigation stacks={STACKS}>
|
|
61
|
+
<AppLayout nav={TABS}>
|
|
62
|
+
<HorizontalTransition>
|
|
63
|
+
<RouteCache>
|
|
64
|
+
<Scroll vertical cover>
|
|
65
|
+
<PageLoader>
|
|
66
|
+
<Router routes={ROUTES} />
|
|
67
|
+
</PageLoader>
|
|
68
|
+
</Scroll>
|
|
69
|
+
</RouteCache>
|
|
70
|
+
</HorizontalTransition>
|
|
71
|
+
</AppLayout>
|
|
72
|
+
</Navigation>
|
|
73
|
+
</App>;
|
|
72
74
|
```
|
|
73
75
|
|
|
74
76
|
The tab bar is in the layout, outside the cache, so it stays still while pages slide. See "Composing an app" on `<App>` for the full nesting rules.
|
|
@@ -114,9 +116,9 @@ Read the store from anywhere in the tree with `requireNavigation()`:
|
|
|
114
116
|
import { requireNavigation } from "shelving/ui";
|
|
115
117
|
|
|
116
118
|
const nav = requireNavigation();
|
|
117
|
-
nav.forward("/home/post/1");
|
|
118
|
-
nav.back("/home");
|
|
119
|
-
nav.replace("/login");
|
|
119
|
+
nav.forward("/home/post/1"); // Open a page in the current stack.
|
|
120
|
+
nav.back("/home"); // Go back to a page.
|
|
121
|
+
nav.replace("/login"); // Change the URL of the current page.
|
|
120
122
|
```
|
|
121
123
|
|
|
122
124
|
See `NavigationStore` for what each method does.
|
|
@@ -14,12 +14,12 @@ The store that holds the current URL, drives browser history, and keeps one stac
|
|
|
14
14
|
|
|
15
15
|
## Methods
|
|
16
16
|
|
|
17
|
-
| Method
|
|
18
|
-
|
|
19
|
-
| `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace.
|
|
20
|
-
| `back(href, stack?)`
|
|
21
|
-
| `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages.
|
|
22
|
-
| `history(stack?)`
|
|
17
|
+
| Method | What it does | Slide |
|
|
18
|
+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
|
19
|
+
| `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
|
|
20
|
+
| `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
|
|
21
|
+
| `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
|
|
22
|
+
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
23
23
|
|
|
24
24
|
`stack` defaults to the current stack.
|
|
25
25
|
|
|
@@ -48,13 +48,13 @@ Why depth? A browser history entry cannot be changed or removed. So when you go
|
|
|
48
48
|
|
|
49
49
|
For example, with tabs `/home` and `/profile`:
|
|
50
50
|
|
|
51
|
-
| Step
|
|
52
|
-
|
|
53
|
-
| Start at `/home`
|
|
54
|
-
| Open a post
|
|
55
|
-
| Tap the Profile tab | `/profile` (depth 0)
|
|
56
|
-
| Tap the Home tab
|
|
57
|
-
| Tap the back button | `/home` (depth 0)
|
|
51
|
+
| Step | New history entry | Home stack | Profile stack |
|
|
52
|
+
| ------------------- | ------------------------ | ----------------------- | ------------- |
|
|
53
|
+
| Start at `/home` | `/home` (depth 0) | `/home` | — |
|
|
54
|
+
| Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
|
|
55
|
+
| Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
|
|
56
|
+
| Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
|
|
57
|
+
| Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
|
|
58
58
|
|
|
59
59
|
When the page you go back to is the entry just before the current one, `back()` goes back in the browser history and pushes nothing.
|
|
60
60
|
|
|
@@ -66,8 +66,8 @@ The browser back and forward buttons walk the history entries one at a time, as
|
|
|
66
66
|
import { Button, requireNavigation } from "shelving/ui";
|
|
67
67
|
|
|
68
68
|
function LogoutButton() {
|
|
69
|
-
|
|
70
|
-
|
|
69
|
+
const nav = requireNavigation();
|
|
70
|
+
return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
|
|
71
71
|
}
|
|
72
72
|
```
|
|
73
73
|
|
|
@@ -78,9 +78,9 @@ import { useStore } from "shelving/react";
|
|
|
78
78
|
import { requireNavigation } from "shelving/ui";
|
|
79
79
|
|
|
80
80
|
function TabTitle() {
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
81
|
+
const nav = requireNavigation();
|
|
82
|
+
const stack = useStore(nav.stack).value;
|
|
83
|
+
return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
|
|
84
84
|
}
|
|
85
85
|
```
|
|
86
86
|
|
package/ui/router/RouteCache.md
CHANGED
|
@@ -27,26 +27,26 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
27
27
|
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
28
28
|
|
|
29
29
|
<AppLayout nav={<StackBar />}>
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
</AppLayout
|
|
30
|
+
<HorizontalTransition>
|
|
31
|
+
<RouteCache>
|
|
32
|
+
<Scroll vertical cover>
|
|
33
|
+
<PageLoader>
|
|
34
|
+
<Router routes={ROUTES} />
|
|
35
|
+
</PageLoader>
|
|
36
|
+
</Scroll>
|
|
37
|
+
</RouteCache>
|
|
38
|
+
</HorizontalTransition>
|
|
39
|
+
</AppLayout>;
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
Keep fewer pages:
|
|
43
43
|
|
|
44
44
|
```tsx
|
|
45
45
|
<RouteCache maxCached={5}>
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
</RouteCache
|
|
46
|
+
<Scroll vertical cover>
|
|
47
|
+
<Router routes={ROUTES} />
|
|
48
|
+
</Scroll>
|
|
49
|
+
</RouteCache>;
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
|
|
@@ -56,19 +56,19 @@ import { useState } from "react";
|
|
|
56
56
|
import { Form, requireNavigation } from "shelving/ui";
|
|
57
57
|
|
|
58
58
|
function NewPostPage() {
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
59
|
+
const nav = requireNavigation();
|
|
60
|
+
const [formKey, setFormKey] = useState(0);
|
|
61
|
+
return (
|
|
62
|
+
<Form
|
|
63
|
+
key={formKey}
|
|
64
|
+
schema={POST_SCHEMA}
|
|
65
|
+
onSubmit={async data => {
|
|
66
|
+
const id = await createPost(data);
|
|
67
|
+
setFormKey(k => k + 1);
|
|
68
|
+
nav.forward(`/post/${id}`);
|
|
69
|
+
}}
|
|
70
|
+
/>
|
|
71
|
+
);
|
|
72
72
|
}
|
|
73
73
|
```
|
|
74
74
|
|