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/docs/util/url.md
CHANGED
|
@@ -19,14 +19,14 @@ These helpers work specifically with hierarchical `scheme://host` URLs (a strict
|
|
|
19
19
|
```ts
|
|
20
20
|
import { getURL, requireURL, getBasedURI, isURL, assertURL } from "shelving/util";
|
|
21
21
|
|
|
22
|
-
getURL("https://example.com/page");
|
|
23
|
-
getURL("not-a-url");
|
|
22
|
+
getURL("https://example.com/page"); // ImmutableURL
|
|
23
|
+
getURL("not-a-url"); // undefined
|
|
24
24
|
getURL("/page", "https://example.com/app/"); // https://example.com/app/page
|
|
25
25
|
getBasedURI("/page", "https://example.com/app/b"); // resolves as https://example.com/app/b/page
|
|
26
26
|
|
|
27
|
-
requireURL("https://example.com");
|
|
28
|
-
isURL(new URL("https://x.com"));
|
|
29
|
-
isURL(new URL("mailto:hi@example.com"));
|
|
27
|
+
requireURL("https://example.com"); // ImmutableURL or throws RequiredError
|
|
28
|
+
isURL(new URL("https://x.com")); // true
|
|
29
|
+
isURL(new URL("mailto:hi@example.com")); // false
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
### Base URLs
|
|
@@ -34,9 +34,9 @@ isURL(new URL("mailto:hi@example.com")); // false
|
|
|
34
34
|
```ts
|
|
35
35
|
import { getBaseURL, requireBaseURL, isBaseURL } from "shelving/util";
|
|
36
36
|
|
|
37
|
-
getBaseURL("https://example.com/app");
|
|
38
|
-
getBaseURL("https://example.com/app/");
|
|
39
|
-
isBaseURL(new URL("https://x.com/"));
|
|
37
|
+
getBaseURL("https://example.com/app"); // https://example.com/app/ (slash appended)
|
|
38
|
+
getBaseURL("https://example.com/app/"); // same ref (already a base URL)
|
|
39
|
+
isBaseURL(new URL("https://x.com/")); // true
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
### Path matching
|
|
@@ -65,10 +65,10 @@ import { isURLActive, isURLProud } from "shelving/util";
|
|
|
65
65
|
const current = "https://example.com/app/settings/profile";
|
|
66
66
|
|
|
67
67
|
isURLActive(current, "https://example.com/app/settings/profile"); // true (exact)
|
|
68
|
-
isURLActive(current, "https://example.com/app/settings");
|
|
68
|
+
isURLActive(current, "https://example.com/app/settings"); // false
|
|
69
69
|
|
|
70
|
-
isURLProud(current, "https://example.com/app/settings");
|
|
71
|
-
isURLProud(current, "https://example.com/other");
|
|
70
|
+
isURLProud(current, "https://example.com/app/settings"); // true (ancestor)
|
|
71
|
+
isURLProud(current, "https://example.com/other"); // false
|
|
72
72
|
```
|
|
73
73
|
|
|
74
74
|
|
package/docs/util/uuid.md
CHANGED
|
@@ -21,12 +21,12 @@ randomUUID(); // "550e8400e29b41d4a716446655440000" (no dashes)
|
|
|
21
21
|
|
|
22
22
|
// Parse and normalise an existing UUID.
|
|
23
23
|
getUUID("550e8400-e29b-41d4-a716-446655440000"); // "550e8400e29b41d4a716446655440000"
|
|
24
|
-
getUUID("INVALID");
|
|
25
|
-
getUUID("");
|
|
24
|
+
getUUID("INVALID"); // undefined
|
|
25
|
+
getUUID(""); // undefined
|
|
26
26
|
|
|
27
27
|
// Require a valid UUID or throw.
|
|
28
28
|
requireUUID("550e8400-e29b-41d4-a716-446655440000"); // "550e8400e29b41d4a716446655440000"
|
|
29
|
-
requireUUID("bad-value");
|
|
29
|
+
requireUUID("bad-value"); // throws RequiredError
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
|
package/docs/util/validate.md
CHANGED
|
@@ -21,14 +21,14 @@ These helpers define the `Validator<T>` interface and utility functions for appl
|
|
|
21
21
|
import { getValid, requireValid } from "shelving/util";
|
|
22
22
|
|
|
23
23
|
const positiveNumber = {
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
24
|
+
validate(v: unknown) {
|
|
25
|
+
if (typeof v !== "number" || v <= 0) throw "Must be a positive number";
|
|
26
|
+
return v;
|
|
27
|
+
},
|
|
28
28
|
};
|
|
29
29
|
|
|
30
|
-
getValid(-1, positiveNumber);
|
|
31
|
-
getValid(5, positiveNumber);
|
|
30
|
+
getValid(-1, positiveNumber); // undefined
|
|
31
|
+
getValid(5, positiveNumber); // 5
|
|
32
32
|
requireValid(-1, positiveNumber); // throws RequiredError("Must be a positive number")
|
|
33
33
|
```
|
|
34
34
|
|
|
@@ -50,8 +50,13 @@ validateDictionary({ a: 1, b: -1 }, positiveNumber);
|
|
|
50
50
|
import { validateData } from "shelving/util";
|
|
51
51
|
|
|
52
52
|
const validators = {
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
name: {
|
|
54
|
+
validate: (v: unknown) => {
|
|
55
|
+
if (typeof v !== "string") throw "Must be string";
|
|
56
|
+
return v;
|
|
57
|
+
},
|
|
58
|
+
},
|
|
59
|
+
age: positiveNumber,
|
|
55
60
|
};
|
|
56
61
|
|
|
57
62
|
validateData({ name: "Alice", age: 30, extra: true }, validators);
|
|
@@ -64,7 +69,7 @@ validateData({ name: "Alice", age: 30, extra: true }, validators);
|
|
|
64
69
|
import type { ValidatorType, ValidatorsType } from "shelving/util";
|
|
65
70
|
|
|
66
71
|
type MyNumber = ValidatorType<typeof positiveNumber>; // number
|
|
67
|
-
type MyShape = ValidatorsType<typeof validators>;
|
|
72
|
+
type MyShape = ValidatorsType<typeof validators>; // { name: string; age: number }
|
|
68
73
|
```
|
|
69
74
|
|
|
70
75
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "shelving",
|
|
3
|
-
"version": "1.322.
|
|
3
|
+
"version": "1.322.2",
|
|
4
4
|
"author": "Dave Houlbrooke <dave@shax.com>",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -9,9 +9,9 @@
|
|
|
9
9
|
"main": "./index.js",
|
|
10
10
|
"module": "./index.js",
|
|
11
11
|
"devDependencies": {
|
|
12
|
-
"@biomejs/biome": "^2.
|
|
12
|
+
"@biomejs/biome": "^2.6.8",
|
|
13
13
|
"@heroicons/react": "^2.2.0",
|
|
14
|
-
"@types/bun": "^1.4.
|
|
14
|
+
"@types/bun": "^1.4.4",
|
|
15
15
|
"@types/react": "^19.3.0",
|
|
16
16
|
"@types/react-dom": "^19.3.0",
|
|
17
17
|
"stylelint": "^17.16.0",
|
package/skills/shelving/SKILL.md
CHANGED
package/ui/README.md
CHANGED
|
@@ -10,8 +10,8 @@ The `ui` module exists so an app never hand-rolls the same form field, card, or
|
|
|
10
10
|
|
|
11
11
|
A few conventions run through every component:
|
|
12
12
|
|
|
13
|
-
- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button plain>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in
|
|
14
|
-
- **`className` is the escape hatch.** Most components accept an optional `className`, merged
|
|
13
|
+
- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button plain>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in _one place_ — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style`.
|
|
14
|
+
- **`className` is the escape hatch.** Most components accept an optional `className`, merged _after_ the classes the component computes for itself, so an app class reliably wins over the library's `@layer components` rules. It takes any `Classes` value — a string, an array, or a dictionary of `true` flags — and lands on the component's own root element. Use it for a composed one-off treatment that tokens and per-property hooks can't express (an animation, a bespoke gradient); tokens and hooks stay the primary theming surface. Formatting-only components (`<When>`, `<Prose>`, `<Scroll>`), the `*Layout` components, and `<Dialog>` deliberately don't take one — write a new layout, or style the content inside. See `ClassProps`.
|
|
15
15
|
- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `<Card>`, `<Section>`, `<Button>`, and `<Tag>` rather than shipping their own styling.
|
|
16
16
|
- **Sentence case.** Titles, headings, and button labels capitalise only the first word.
|
|
17
17
|
- **Theme with CSS.** An app-wide custom look is a CSS file, not a wall of props. Write a `theme.css` that overrides the base design-token variables (and, where needed, per-component hooks) at `:root`, and import it after the library styles. The recommended workflow is to spend time tuning those variables to match your design — see [Theming](#theming) below.
|
|
@@ -22,7 +22,7 @@ The styling system lives in `style/` and has four moving parts: design tokens, t
|
|
|
22
22
|
|
|
23
23
|
**Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours (`getColorClass()`), typography — font size, weight, family, and case (`getTypographyClass()`), spacing (`getSpaceClass()`), widths (`getWidthClass()`), radii (`getRadiusClass()`), strokes (`getStrokeClass()`), shadows (`getShadowClass()`), and durations (`getDurationClass()`). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
|
|
24
24
|
|
|
25
|
-
**The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and
|
|
25
|
+
**The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and _recomputed_ under `TINT_CLASS` — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the `TINT_CLASS` page.
|
|
26
26
|
|
|
27
27
|
**Cascade layers.** Styles are ordered by `@layer`, lowest to highest priority: `defaults` (`:root` tokens, the tint ladder, body baseline) → `components` (the bulk of the CSS: `.card`, `.button`, …) → `variants` (cross-cutting opt-in modifiers, which always beat components) → `overrides` (top-priority structural fixes like `:first-child` / `:last-child` margin collapses). Unlayered rules beat all layered rules, so a theme should set tokens at `:root` or wrap its rules in `@layer`.
|
|
28
28
|
|
|
@@ -51,7 +51,7 @@ Each base token lives in a themed module that documents the variables it defines
|
|
|
51
51
|
- `space` · `width` — layout spacing and widths (`--space-*`, `--width-*`).
|
|
52
52
|
- `radius` · `stroke` · `shadow` · `duration` — surface tokens (`--radius-*`, `--stroke-*`, `--shadow-*`, `--duration-*`).
|
|
53
53
|
|
|
54
|
-
The **tint ladder** is the one exception that doesn't follow the override-a-variable pattern: its 21 steps are
|
|
54
|
+
The **tint ladder** is the one exception that doesn't follow the override-a-variable pattern: its 21 steps are _recomputed_ from a single anchor inside every tinted scope, so you move the anchor (via `color=` / `status=`) rather than overriding individual steps. See `TINT_CLASS` for the full theming guide, and each component's **Styling** section for its per-property hooks.
|
|
55
55
|
|
|
56
56
|
## Finding your way around
|
|
57
57
|
|
package/ui/app/App.md
CHANGED
|
@@ -12,18 +12,18 @@ The smallest single-screen app — `<App>` wraps a layout and some content:
|
|
|
12
12
|
import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
|
|
13
13
|
|
|
14
14
|
function HelloApp() {
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
15
|
+
return (
|
|
16
|
+
<App app="My app">
|
|
17
|
+
<FixedLayout>
|
|
18
|
+
<Scroll vertical cover>
|
|
19
|
+
<Section width="narrow">
|
|
20
|
+
<Title>Hello</Title>
|
|
21
|
+
<Paragraph>Welcome to the app.</Paragraph>
|
|
22
|
+
</Section>
|
|
23
|
+
</Scroll>
|
|
24
|
+
</FixedLayout>
|
|
25
|
+
</App>
|
|
26
|
+
);
|
|
27
27
|
}
|
|
28
28
|
```
|
|
29
29
|
|
|
@@ -35,16 +35,18 @@ For a multi-page app, wrap the routes in `<Navigation>` and `<Router>`:
|
|
|
35
35
|
import { App, Navigation, Router } from "shelving/ui";
|
|
36
36
|
|
|
37
37
|
export function MyApp() {
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
38
|
+
return (
|
|
39
|
+
<App app="My app" root="https://example.com/" url="/">
|
|
40
|
+
<Navigation>
|
|
41
|
+
<Router
|
|
42
|
+
routes={{
|
|
43
|
+
"/": HomePage,
|
|
44
|
+
"/about": AboutPage,
|
|
45
|
+
}}
|
|
46
|
+
/>
|
|
47
|
+
</Navigation>
|
|
48
|
+
</App>
|
|
49
|
+
);
|
|
48
50
|
}
|
|
49
51
|
```
|
|
50
52
|
|
|
@@ -74,75 +76,103 @@ Nesting rules:
|
|
|
74
76
|
```tsx
|
|
75
77
|
import { useStore } from "shelving/react";
|
|
76
78
|
import {
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
79
|
+
App,
|
|
80
|
+
AppLayout,
|
|
81
|
+
Catcher,
|
|
82
|
+
DialogsContext,
|
|
83
|
+
Dialogs,
|
|
84
|
+
ErrorPage,
|
|
85
|
+
FixedLayout,
|
|
86
|
+
HorizontalTransition,
|
|
87
|
+
Navigation,
|
|
88
|
+
Notices,
|
|
89
|
+
PageLoader,
|
|
90
|
+
requireMetaURL,
|
|
91
|
+
RouteCache,
|
|
92
|
+
Router,
|
|
93
|
+
type ErrorProps,
|
|
94
|
+
type Routes,
|
|
95
|
+
Scroll,
|
|
96
|
+
StackButton,
|
|
80
97
|
} from "shelving/ui";
|
|
81
98
|
|
|
82
99
|
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
83
100
|
|
|
84
101
|
/** 1–2. Contexts and the app-level catcher. No layout here. */
|
|
85
102
|
export function MyApp() {
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
103
|
+
const session = useStore(SESSION).value;
|
|
104
|
+
return (
|
|
105
|
+
<App key={session?.id ?? "out"} app="My app" root="https://example.com/">
|
|
106
|
+
<Navigation stacks={STACKS} stack="/home">
|
|
107
|
+
<DialogsContext>
|
|
108
|
+
<Catcher as={AppError}>
|
|
109
|
+
<Shell signedIn={!!session} />
|
|
110
|
+
</Catcher>
|
|
111
|
+
<Dialogs />
|
|
112
|
+
<Notices />
|
|
113
|
+
</DialogsContext>
|
|
114
|
+
</Navigation>
|
|
115
|
+
</App>
|
|
116
|
+
);
|
|
100
117
|
}
|
|
101
118
|
|
|
102
119
|
/** 3–4. Pick the layout. Plain React, so any rule works. */
|
|
103
120
|
function Shell({ signedIn }: { signedIn: boolean }) {
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
121
|
+
const { path } = requireMetaURL();
|
|
122
|
+
if (!signedIn)
|
|
123
|
+
return (
|
|
124
|
+
<FixedLayout>
|
|
125
|
+
<Content routes={LOGIN_ROUTES} />
|
|
126
|
+
</FixedLayout>
|
|
127
|
+
);
|
|
128
|
+
return (
|
|
129
|
+
<AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
|
|
130
|
+
<Content routes={ROUTES} />
|
|
131
|
+
</AppLayout>
|
|
132
|
+
);
|
|
111
133
|
}
|
|
112
134
|
|
|
113
135
|
/** 5. The content of a layout's slot. */
|
|
114
136
|
function Content({ routes }: { routes: Routes }) {
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
137
|
+
return (
|
|
138
|
+
<HorizontalTransition>
|
|
139
|
+
<RouteCache>
|
|
140
|
+
<Scroll vertical cover>
|
|
141
|
+
<PageLoader>
|
|
142
|
+
<Router routes={routes} />
|
|
143
|
+
</PageLoader>
|
|
144
|
+
</Scroll>
|
|
145
|
+
</RouteCache>
|
|
146
|
+
</HorizontalTransition>
|
|
147
|
+
);
|
|
126
148
|
}
|
|
127
149
|
|
|
128
150
|
/** The tab bar, in the layout, outside the cache. */
|
|
129
151
|
function StackBar() {
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
152
|
+
return (
|
|
153
|
+
<>
|
|
154
|
+
<StackButton stack="/home" title="Home">
|
|
155
|
+
<HomeIcon />
|
|
156
|
+
</StackButton>
|
|
157
|
+
<StackButton stack="/discover" title="Discover">
|
|
158
|
+
<SearchIcon />
|
|
159
|
+
</StackButton>
|
|
160
|
+
<StackButton stack="/profile" title="Profile">
|
|
161
|
+
<ProfileIcon />
|
|
162
|
+
</StackButton>
|
|
163
|
+
</>
|
|
164
|
+
);
|
|
135
165
|
}
|
|
136
166
|
|
|
137
167
|
/** An error outside every layout: the app picks one here. */
|
|
138
168
|
function AppError({ reason }: ErrorProps) {
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
169
|
+
return (
|
|
170
|
+
<FixedLayout>
|
|
171
|
+
<Scroll vertical cover>
|
|
172
|
+
<ErrorPage reason={reason} />
|
|
173
|
+
</Scroll>
|
|
174
|
+
</FixedLayout>
|
|
175
|
+
);
|
|
146
176
|
}
|
|
147
177
|
```
|
|
148
178
|
|
package/ui/block/Card.md
CHANGED
|
@@ -5,6 +5,7 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
7
|
- Set `href` or `onClick` to make the whole card navigable — a stretched, visually-hidden overlay `<a>` / `<button>` covers the card while the children render normally inside. Real interactive elements inside the card (inline links, buttons) stay clickable and keyboard-focusable.
|
|
8
|
+
- The overlay sits at `z-index: 1`, and the links and buttons inside the card at `z-index: 2`. To put your own absolute layer over the card's content, put it after the content, with no `z-index` and no lasting `transform`. The links and buttons inside it are then lifted above the overlay too. A `transform` makes the layer a stacking context below the overlay. A high `z-index` works, but iOS WebKit can drop that layer for one frame when a page view transition starts.
|
|
8
9
|
- `color=` and `status=` move the tint anchor for the card's scope, so the surface, text, and hover shade all re-derive together — and nested components (`<Tag>`, `<Preformatted>`, `<Button>`) inherit the same tint.
|
|
9
10
|
- A card styles only the box. Lay out its contents with the usual block components (`<Subheading>`, `<Paragraph>`, `<Row>`, …).
|
|
10
11
|
- Cards have no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a given card.
|
|
@@ -18,9 +19,9 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
|
|
|
18
19
|
import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
19
20
|
|
|
20
21
|
<Card>
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
</Card
|
|
22
|
+
<Subheading>Storage</Subheading>
|
|
23
|
+
<Paragraph>1.2 GB of 5 GB used.</Paragraph>
|
|
24
|
+
</Card>;
|
|
24
25
|
```
|
|
25
26
|
|
|
26
27
|
### Navigable card
|
|
@@ -30,9 +31,9 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
|
30
31
|
|
|
31
32
|
// The entire card is a link; `title` labels the overlay for screen readers.
|
|
32
33
|
<Card href="/projects/shelving" title="Open Shelving">
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
</Card
|
|
34
|
+
<Subheading>Shelving</Subheading>
|
|
35
|
+
<Paragraph>TypeScript data toolkit.</Paragraph>
|
|
36
|
+
</Card>;
|
|
36
37
|
```
|
|
37
38
|
|
|
38
39
|
### Status and colour
|
|
@@ -58,28 +59,28 @@ import { Card, Subheading } from "shelving/ui";
|
|
|
58
59
|
|
|
59
60
|
`Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the card or an ancestor scope) to recolour everything at once — surface, text, and hover shade re-derive together; reach for a per-property hook for a single surgical change.
|
|
60
61
|
|
|
61
|
-
| Variable
|
|
62
|
-
|
|
63
|
-
| `--card-background`
|
|
64
|
-
| `--card-hover-background` | Surface fill when a navigable card is hovered
|
|
65
|
-
| `--card-color`
|
|
66
|
-
| `--card-border`
|
|
67
|
-
| `--card-stroke`
|
|
68
|
-
| `--card-radius`
|
|
69
|
-
| `--card-padding`
|
|
70
|
-
| `--card-indent`
|
|
71
|
-
| `--card-space`
|
|
72
|
-
| `--card-shadow`
|
|
73
|
-
| `--card-transition`
|
|
74
|
-
| `--card-focus-border`
|
|
62
|
+
| Variable | Styles | Default |
|
|
63
|
+
| ------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
64
|
+
| `--card-background` | Surface fill | `var(--tint-90)` |
|
|
65
|
+
| `--card-hover-background` | Surface fill when a navigable card is hovered | `var(--tint-95)` |
|
|
66
|
+
| `--card-color` | Text colour | `var(--tint-00)` |
|
|
67
|
+
| `--card-border` | Border shorthand | `var(--card-stroke) solid var(--tint-80)` |
|
|
68
|
+
| `--card-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
|
|
69
|
+
| `--card-radius` | Corner radius | `var(--radius-normal)` (16px) |
|
|
70
|
+
| `--card-padding` | Inner top and bottom padding (one length) | `var(--space-normal)` (16px) |
|
|
71
|
+
| `--card-indent` | Inner left and right padding (one length) | `var(--space-normal)` (16px) |
|
|
72
|
+
| `--card-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
|
|
73
|
+
| `--card-shadow` | Drop shadow | `none` |
|
|
74
|
+
| `--card-transition` | Transition | `all var(--duration-fast)` (150ms) |
|
|
75
|
+
| `--card-focus-border` | Focus outline, drawn on the navigable overlay so it shows above children like `<Panel>` | `var(--stroke-focus) solid var(--color-focus)` |
|
|
75
76
|
|
|
76
77
|
**Global tokens it reads** — move these to retheme broadly rather than overriding ladder steps directly: the tint ladder `--tint-00` / `--tint-80` / `--tint-90` / `--tint-95`, plus `--space-normal`, `--space-paragraph`, `--radius-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
|
|
77
78
|
|
|
78
79
|
```css
|
|
79
80
|
/* Theme: raised cards with tighter corners. */
|
|
80
81
|
:root {
|
|
81
|
-
|
|
82
|
-
|
|
82
|
+
--card-shadow: var(--shadow-normal);
|
|
83
|
+
--card-radius: var(--radius-small);
|
|
83
84
|
}
|
|
84
85
|
```
|
|
85
86
|
|
package/ui/block/Details.md
CHANGED
|
@@ -18,8 +18,8 @@ A collapsible panel. The title is always visible. The content shows when the use
|
|
|
18
18
|
import { Details, Paragraph } from "shelving/ui";
|
|
19
19
|
|
|
20
20
|
<Details title="What is shelving?">
|
|
21
|
-
|
|
22
|
-
</Details
|
|
21
|
+
<Paragraph>A TypeScript data toolkit.</Paragraph>
|
|
22
|
+
</Details>;
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
### Open by default
|
|
@@ -28,8 +28,8 @@ import { Details, Paragraph } from "shelving/ui";
|
|
|
28
28
|
import { Details, Paragraph } from "shelving/ui";
|
|
29
29
|
|
|
30
30
|
<Details title="Release notes" open>
|
|
31
|
-
|
|
32
|
-
</Details
|
|
31
|
+
<Paragraph>Bug fixes and small improvements.</Paragraph>
|
|
32
|
+
</Details>;
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
### Exclusive group (FAQ)
|
|
@@ -50,14 +50,14 @@ import { Details, Paragraph } from "shelving/ui";
|
|
|
50
50
|
|
|
51
51
|
`Details` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` to an ancestor scope to recolour the chevron and divider together.
|
|
52
52
|
|
|
53
|
-
| Variable
|
|
54
|
-
|
|
55
|
-
| `--details-space`
|
|
56
|
-
| `--details-border`
|
|
57
|
-
| `--details-marker-color` | Colour of the browser's marker on a raw `<details>` in `.prose` | `var(--tint-80)`
|
|
58
|
-
| `--details-radius`
|
|
59
|
-
| `--details-icon-color`
|
|
60
|
-
| `--details-transition`
|
|
61
|
-
| `--details-gap`
|
|
53
|
+
| Variable | Styles | Default |
|
|
54
|
+
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------- |
|
|
55
|
+
| `--details-space` | Outer block margin, and the padding above a divider | `var(--space-paragraph)` (16px) |
|
|
56
|
+
| `--details-border` | Divider between panels next to each other | `var(--stroke-normal) solid var(--tint-90)` |
|
|
57
|
+
| `--details-marker-color` | Colour of the browser's marker on a raw `<details>` in `.prose` | `var(--tint-80)` |
|
|
58
|
+
| `--details-radius` | Corner radius of the title's focus ring | `var(--radius-xsmall)` (8px) |
|
|
59
|
+
| `--details-icon-color` | Chevron colour | `var(--tint-50)` |
|
|
60
|
+
| `--details-transition` | Open/close animation and chevron turn | `all var(--duration-fast)` (150ms) |
|
|
61
|
+
| `--details-gap` | Space between the title and the content | `var(--space-paragraph)` (16px) |
|
|
62
62
|
|
|
63
63
|
**Global tokens it reads:** the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-normal`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--duration-fast` and `--size-icon` (chevron size, from `getFlexClass`).
|
package/ui/block/Grid.md
CHANGED
|
@@ -17,11 +17,19 @@ A grid container that arranges its children in equal-width columns. Renders a `<
|
|
|
17
17
|
import { Card, Grid, Paragraph } from "shelving/ui";
|
|
18
18
|
|
|
19
19
|
<Grid gap="small">
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
</
|
|
20
|
+
<Card>
|
|
21
|
+
<Paragraph>Running</Paragraph>
|
|
22
|
+
</Card>
|
|
23
|
+
<Card>
|
|
24
|
+
<Paragraph>Cycling</Paragraph>
|
|
25
|
+
</Card>
|
|
26
|
+
<Card>
|
|
27
|
+
<Paragraph>Swimming</Paragraph>
|
|
28
|
+
</Card>
|
|
29
|
+
<Card>
|
|
30
|
+
<Paragraph>Rowing</Paragraph>
|
|
31
|
+
</Card>
|
|
32
|
+
</Grid>;
|
|
25
33
|
```
|
|
26
34
|
|
|
27
35
|
### A list of tiles
|
|
@@ -30,8 +38,10 @@ import { Card, Grid, Paragraph } from "shelving/ui";
|
|
|
30
38
|
import { Grid } from "shelving/ui";
|
|
31
39
|
|
|
32
40
|
<Grid as="ul" columns={3} gap="normal">
|
|
33
|
-
|
|
34
|
-
</
|
|
41
|
+
{badges.map(badge => (
|
|
42
|
+
<li key={badge.id}>{badge.name}</li>
|
|
43
|
+
))}
|
|
44
|
+
</Grid>;
|
|
35
45
|
```
|
|
36
46
|
|
|
37
47
|
### Days of the week
|
|
@@ -40,8 +50,10 @@ import { Grid } from "shelving/ui";
|
|
|
40
50
|
import { Grid } from "shelving/ui";
|
|
41
51
|
|
|
42
52
|
<Grid as="ol" columns={7} gap="xsmall">
|
|
43
|
-
|
|
44
|
-
</
|
|
53
|
+
{days.map(day => (
|
|
54
|
+
<li key={day.date}>{day.label}</li>
|
|
55
|
+
))}
|
|
56
|
+
</Grid>;
|
|
45
57
|
```
|
|
46
58
|
|
|
47
59
|
## Styling
|
package/ui/block/Heading.md
CHANGED
|
@@ -35,29 +35,29 @@ import { Title, Heading, Subheading } from "shelving/ui";
|
|
|
35
35
|
```tsx live
|
|
36
36
|
import { Heading } from "shelving/ui";
|
|
37
37
|
|
|
38
|
-
<Heading color="red">Danger zone</Heading
|
|
38
|
+
<Heading color="red">Danger zone</Heading>;
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
## Styling
|
|
42
42
|
|
|
43
43
|
`Heading` exposes hooks for its rhythm and type. It inherits text colour by default (so it picks up the surrounding tint); set `--heading-color` only to override that.
|
|
44
44
|
|
|
45
|
-
| Variable
|
|
46
|
-
|
|
47
|
-
| `--heading-color`
|
|
48
|
-
| `--heading-space-before` | Top margin
|
|
49
|
-
| `--heading-space`
|
|
50
|
-
| `--heading-font`
|
|
51
|
-
| `--heading-weight`
|
|
52
|
-
| `--heading-size`
|
|
53
|
-
| `--heading-leading`
|
|
45
|
+
| Variable | Styles | Default |
|
|
46
|
+
| ------------------------ | ------------- | ------------------------------- |
|
|
47
|
+
| `--heading-color` | Text colour | `inherit` |
|
|
48
|
+
| `--heading-space-before` | Top margin | `var(--space-section)` (2rem) |
|
|
49
|
+
| `--heading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
|
|
50
|
+
| `--heading-font` | Font family | `var(--font-title)` |
|
|
51
|
+
| `--heading-weight` | Font weight | `var(--weight-strong)` (700) |
|
|
52
|
+
| `--heading-size` | Font size | `var(--size-xxlarge)` |
|
|
53
|
+
| `--heading-leading` | Line height | `var(--leading)` |
|
|
54
54
|
|
|
55
55
|
**Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-xxlarge`, and `--leading`. (`<Title>` and `<Subheading>` share this component and expose the parallel `--title-*` / `--subheading-*` hooks.)
|
|
56
56
|
|
|
57
57
|
```css
|
|
58
58
|
/* Theme: serif headings, a touch larger. */
|
|
59
59
|
:root {
|
|
60
|
-
|
|
61
|
-
|
|
60
|
+
--heading-font: var(--font-serif);
|
|
61
|
+
--heading-size: 3rem;
|
|
62
62
|
}
|
|
63
63
|
```
|
package/ui/block/List.md
CHANGED
|
@@ -26,18 +26,18 @@ import { List } from "shelving/ui";
|
|
|
26
26
|
```tsx
|
|
27
27
|
import { List } from "shelving/ui";
|
|
28
28
|
|
|
29
|
-
<List gap="small">{items.map(item => item.label)}</List
|
|
29
|
+
<List gap="small">{items.map(item => item.label)}</List>;
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
## Styling
|
|
33
33
|
|
|
34
34
|
`List` paints from the [tint ladder](/ui/TINT_CLASS) for its markers only; apply `color=` (on the list or an ancestor scope) to recolour the markers, or reach for a per-property hook for a single change.
|
|
35
35
|
|
|
36
|
-
| Variable
|
|
37
|
-
|
|
38
|
-
| `--list-space`
|
|
39
|
-
| `--list-gap`
|
|
40
|
-
| `--list-indent`
|
|
41
|
-
| `--list-marker-color` | Bullet / number colour
|
|
36
|
+
| Variable | Styles | Default |
|
|
37
|
+
| --------------------- | ------------------------------------ | ------------------------------------- |
|
|
38
|
+
| `--list-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
|
|
39
|
+
| `--list-gap` | Space between items | `var(--space-xsmall)` |
|
|
40
|
+
| `--list-indent` | Inline start padding (marker gutter) | `1.125em` unordered / `1.8em` ordered |
|
|
41
|
+
| `--list-marker-color` | Bullet / number colour | `var(--tint-80)` |
|
|
42
42
|
|
|
43
43
|
**Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, and the tint-ladder step `--tint-80`. The `gap` variant comes from the shared `shelving/ui` styling system.
|