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
|
@@ -8,7 +8,7 @@ Follow the file and folder names in this guide exactly. The layout works because
|
|
|
8
8
|
|
|
9
9
|
1. **Three top-level packages.** All source code lives in `shared/`, `api/`, or `app/`. `shared/` is the contract layer; `api/` is the server; `app/` is the client.
|
|
10
10
|
2. **The contract lives in `shared/`.** Database schemas, endpoint definitions, domain logic, and utilities used by both sides are defined once in `shared/` and imported by both `api/` and `app/`. Neither side ever redeclares a type or a validation rule the other side also needs.
|
|
11
|
-
3. **Schema-first.** Data shapes are defined as Shelving schemas (runtime validators), and TypeScript types are
|
|
11
|
+
3. **Schema-first.** Data shapes are defined as Shelving schemas (runtime validators), and TypeScript types are _derived_ from them with `ValidatorType`. You never write a type by hand and a validator separately.
|
|
12
12
|
4. **Hard boundaries, mechanically enforced.** `app/` must never import from `api/`, and `api/` must never import from `app/`. This is enforced by the linter, not by convention (see [Boundaries](#boundaries)).
|
|
13
13
|
5. **Dependency injection via a context object, owned by the composition root.** Handlers and services never construct their own providers (database, external APIs). They receive a single context object, so the same code runs against real providers in production, debug/in-memory providers locally, and mock providers in tests. The full context type (`APIContext`) is defined in `api/` — never in `shared/`. Shared code stays generic over a context type `C`, and declares only small named context slices — reusable ones like `DatabaseContext` in `shared/util/context.ts`, adapter-specific ones alongside each adapter (see [Dependency injection](#dependency-injection-context-slices-and-the-composition-root)).
|
|
14
14
|
6. **Group by domain, not by file type.** Feature code sits in a folder named after the domain entity it handles, with its components, styles, helpers, and tests together.
|
|
@@ -186,7 +186,7 @@ The composition root's `APIContext` satisfies `CRMContext` structurally, so the
|
|
|
186
186
|
|
|
187
187
|
Flat folder, one file per topic (`phone.ts`, `cookie.ts`, `env.ts`, …), each with a co-located `<topic>.test.ts`. Two files deserve special mention:
|
|
188
188
|
|
|
189
|
-
- **`shared/util/env.ts`** — parses
|
|
189
|
+
- **`shared/util/env.ts`** — parses _public_ environment variables only. It starts with a comment warning that these values are inlined into client bundles. Required values throw at module load: `if (!process.env.API_URL) throw new ReferenceError(...)`. Export parsed values (e.g. `URL` objects via `requireURL`), not raw strings.
|
|
190
190
|
- **`shared/util/context.ts`** — declares small, descriptive, **reusable context slices** — `DatabaseContext { db: DBProvider }` and the like — that shared service callbacks reuse when they need context. What it must **never** declare is the full server context: the "large bundle" shape is owned by `api/util/context.ts`, where `APIContext` composes these slices into its final shape. Nothing in `app/` ever imports the full server context, and defining it in `shared/` forces generic shared code to depend on the whole application environment. See [Dependency injection](#dependency-injection-context-slices-and-the-composition-root).
|
|
191
191
|
|
|
192
192
|
## Dependency injection: context slices and the composition root
|
|
@@ -197,7 +197,7 @@ Everything server-side receives its dependencies through a single context object
|
|
|
197
197
|
|
|
198
198
|
The server's full DI context is defined in **`api/util/context.ts`**, named `APIContext`, with `APIHandlers = EndpointHandlers<APIContext>` alongside. It does **not** live in `shared/`. This mirrors `app/util/context.ts` — each side owns its own context file. Nothing in `app/` ever imports the server context, and defining it in `shared/` forces generic shared code to depend on the whole application environment.
|
|
199
199
|
|
|
200
|
-
What `shared/`
|
|
200
|
+
What `shared/` _does_ declare is **slices**: small, descriptive interfaces that each name one capability. The full context only ever exists at the composition root, as a composition of slices.
|
|
201
201
|
|
|
202
202
|
### Shared code never names the full context
|
|
203
203
|
|
|
@@ -304,12 +304,12 @@ One file per domain entity; functions named as verbs (`createOrder`, not `orderC
|
|
|
304
304
|
|
|
305
305
|
### `api/config/` — server-side configuration
|
|
306
306
|
|
|
307
|
-
Mirrors `shared/config/` folder-for-folder. Where `shared/config/<area>/` defines
|
|
307
|
+
Mirrors `shared/config/` folder-for-folder. Where `shared/config/<area>/` defines _what the data looks like_ (schemas — needed by the client to render forms), `api/config/<area>/` defines _what the server does with it_ (processors, forwarding/mapping to external systems — server-only because it encodes business rules and touches secret-bearing providers). The `api/config/<area>/index.ts` barrel uses `satisfies { [K in keyof typeof SHARED_CONFIG]: ... }` to force a compile error if a shared config entry is missing its server counterpart.
|
|
308
308
|
|
|
309
309
|
### `api/util/` — server-only utilities
|
|
310
310
|
|
|
311
311
|
- **`api/util/context.ts`** — defines `APIContext` (the DI context interface, composed by extending the reusable slices from `shared/util/context.ts` and each adapter's own slice) and `APIHandlers = EndpointHandlers<APIContext>`. See [Dependency injection](#dependency-injection-context-slices-and-the-composition-root).
|
|
312
|
-
- **`api/util/env.ts`** — parses
|
|
312
|
+
- **`api/util/env.ts`** — parses _secret_ environment variables (API keys etc.). Starts with a comment: "these values are server-side secrets — only import this file in API code, never in APP code."
|
|
313
313
|
- **`api/util/middleware.ts`** — request middleware as higher-order functions named `with*`: `withCORS(handler)`, `withLogging(handler)`. Each takes a `RequestHandler` and returns a new one.
|
|
314
314
|
- **`api/util/test.ts`** — the mock-context factory described above, plus shared test fixtures.
|
|
315
315
|
|
|
@@ -399,12 +399,12 @@ With no layout, the document body scrolls. This is fine for a site or a small ap
|
|
|
399
399
|
|
|
400
400
|
```tsx
|
|
401
401
|
<App app="My site" root="https://example.com/">
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
</App
|
|
402
|
+
<Navigation>
|
|
403
|
+
<PageLoader>
|
|
404
|
+
<Router routes={ROUTES} />
|
|
405
|
+
</PageLoader>
|
|
406
|
+
</Navigation>
|
|
407
|
+
</App>;
|
|
408
408
|
```
|
|
409
409
|
|
|
410
410
|
#### A full-screen app with its own scroll box
|
|
@@ -413,12 +413,12 @@ Use `<FixedLayout>`. It locks the body and gives one full-screen content slot in
|
|
|
413
413
|
|
|
414
414
|
```tsx
|
|
415
415
|
<FixedLayout>
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
</FixedLayout
|
|
416
|
+
<Scroll vertical cover>
|
|
417
|
+
<PageLoader>
|
|
418
|
+
<Router routes={ROUTES} />
|
|
419
|
+
</PageLoader>
|
|
420
|
+
</Scroll>
|
|
421
|
+
</FixedLayout>;
|
|
422
422
|
```
|
|
423
423
|
|
|
424
424
|
#### Content in the middle of the screen
|
|
@@ -427,10 +427,10 @@ A layout never centres. The page centres its own content with `<Block height="fu
|
|
|
427
427
|
|
|
428
428
|
```tsx
|
|
429
429
|
<Page title="Log in">
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
</Page
|
|
430
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
431
|
+
<LoginForm />
|
|
432
|
+
</Block>
|
|
433
|
+
</Page>;
|
|
434
434
|
```
|
|
435
435
|
|
|
436
436
|
#### A sidebar
|
|
@@ -439,22 +439,22 @@ Use `<SidebarLayout sidebar>`. On a narrow screen the sidebar becomes a drawer w
|
|
|
439
439
|
|
|
440
440
|
```tsx
|
|
441
441
|
<SidebarLayout sidebar={<Menu />}>
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
</SidebarLayout
|
|
442
|
+
<Scroll vertical cover>
|
|
443
|
+
<Router routes={ROUTES} />
|
|
444
|
+
</Scroll>
|
|
445
|
+
</SidebarLayout>;
|
|
446
446
|
```
|
|
447
447
|
|
|
448
448
|
#### A tab bar
|
|
449
449
|
|
|
450
|
-
Use `<AppLayout nav>`. It puts the content slot above a bar, at every screen size.
|
|
450
|
+
Use `<AppLayout nav>`. It puts the content slot above a bar, at every screen size. Pages slide in the content slot above the bar, so the bar stays still. Set `nav={false}` to hide the bar.
|
|
451
451
|
|
|
452
452
|
```tsx
|
|
453
453
|
<AppLayout nav={<StackBar />}>
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
</AppLayout
|
|
454
|
+
<Scroll vertical cover>
|
|
455
|
+
<Router routes={ROUTES} />
|
|
456
|
+
</Scroll>
|
|
457
|
+
</AppLayout>;
|
|
458
458
|
```
|
|
459
459
|
|
|
460
460
|
#### A custom layout with a custom scroll area
|
|
@@ -469,21 +469,38 @@ A frame does not scroll, centre, cache or transition. The app puts those in the
|
|
|
469
469
|
|
|
470
470
|
```tsx
|
|
471
471
|
export function TopBarLayout({ bar, children }: TopBarLayoutProps): ReactElement {
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
472
|
+
return (
|
|
473
|
+
<div className={LAYOUT_CLASS}>
|
|
474
|
+
<header className={BAR_CLASS}>{bar}</header>
|
|
475
|
+
<main className={CONTENT_CLASS}>{children}</main>
|
|
476
|
+
</div>
|
|
477
|
+
);
|
|
478
478
|
}
|
|
479
479
|
```
|
|
480
480
|
|
|
481
481
|
```css
|
|
482
482
|
@layer components {
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
483
|
+
html:has(.layout) {
|
|
484
|
+
height: 100dvh;
|
|
485
|
+
overflow: hidden;
|
|
486
|
+
}
|
|
487
|
+
body:has(.layout) {
|
|
488
|
+
position: fixed;
|
|
489
|
+
inset: 0;
|
|
490
|
+
margin: 0;
|
|
491
|
+
}
|
|
492
|
+
.layout {
|
|
493
|
+
position: absolute;
|
|
494
|
+
inset: 0;
|
|
495
|
+
display: flex;
|
|
496
|
+
flex-direction: column;
|
|
497
|
+
}
|
|
498
|
+
.content {
|
|
499
|
+
position: relative;
|
|
500
|
+
flex: 1;
|
|
501
|
+
min-height: 0;
|
|
502
|
+
overflow: hidden;
|
|
503
|
+
}
|
|
487
504
|
}
|
|
488
505
|
```
|
|
489
506
|
|
|
@@ -499,12 +516,12 @@ By default a page unmounts when you leave it, so its scroll position, toggles an
|
|
|
499
516
|
|
|
500
517
|
```tsx
|
|
501
518
|
<RouteCache>
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
</RouteCache
|
|
519
|
+
<Scroll vertical cover>
|
|
520
|
+
<PageLoader>
|
|
521
|
+
<Router routes={ROUTES} />
|
|
522
|
+
</PageLoader>
|
|
523
|
+
</Scroll>
|
|
524
|
+
</RouteCache>;
|
|
508
525
|
```
|
|
509
526
|
|
|
510
527
|
Keep the layout **outside** the cache, so the chrome has one copy and keeps its own state. Clear a create form after it saves, because the cache keeps its input. See `<RouteCache>`.
|
|
@@ -515,12 +532,14 @@ Put a page transition, for example `<HorizontalTransition>`, **around** `<RouteC
|
|
|
515
532
|
|
|
516
533
|
```tsx
|
|
517
534
|
<AppLayout nav={<StackBar />}>
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
</
|
|
535
|
+
<HorizontalTransition>
|
|
536
|
+
<RouteCache>
|
|
537
|
+
<Scroll vertical cover>
|
|
538
|
+
…
|
|
539
|
+
</Scroll>
|
|
540
|
+
</RouteCache>
|
|
541
|
+
</HorizontalTransition>
|
|
542
|
+
</AppLayout>;
|
|
524
543
|
```
|
|
525
544
|
|
|
526
545
|
#### Tab stacks, like a phone app
|
|
@@ -540,12 +559,12 @@ All pages in one stack share one layout, because they share one cache. So a page
|
|
|
540
559
|
|
|
541
560
|
```tsx
|
|
542
561
|
function Shell() {
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
562
|
+
const { path } = requireMetaURL();
|
|
563
|
+
return (
|
|
564
|
+
<AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
|
|
565
|
+
<Content />
|
|
566
|
+
</AppLayout>
|
|
567
|
+
);
|
|
549
568
|
}
|
|
550
569
|
```
|
|
551
570
|
|
|
@@ -555,8 +574,17 @@ The layout picker is plain React, so any rule works: the session, the path, or b
|
|
|
555
574
|
|
|
556
575
|
```tsx
|
|
557
576
|
function Shell({ signedIn }: { signedIn: boolean }) {
|
|
558
|
-
|
|
559
|
-
|
|
577
|
+
if (!signedIn)
|
|
578
|
+
return (
|
|
579
|
+
<FixedLayout>
|
|
580
|
+
<Content routes={LOGIN_ROUTES} />
|
|
581
|
+
</FixedLayout>
|
|
582
|
+
);
|
|
583
|
+
return (
|
|
584
|
+
<AppLayout nav={<StackBar />}>
|
|
585
|
+
<Content routes={ROUTES} />
|
|
586
|
+
</AppLayout>
|
|
587
|
+
);
|
|
560
588
|
}
|
|
561
589
|
```
|
|
562
590
|
|
|
@@ -568,13 +596,13 @@ A page, an error page or a loading state never renders a layout. `<PageLoader>`
|
|
|
568
596
|
|
|
569
597
|
```tsx
|
|
570
598
|
function AppError({ reason }: ErrorProps) {
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
599
|
+
return (
|
|
600
|
+
<FixedLayout>
|
|
601
|
+
<Scroll vertical cover>
|
|
602
|
+
<ErrorPage reason={reason} />
|
|
603
|
+
</Scroll>
|
|
604
|
+
</FixedLayout>
|
|
605
|
+
);
|
|
578
606
|
}
|
|
579
607
|
```
|
|
580
608
|
|
|
@@ -587,7 +615,7 @@ Three mechanisms keep the packages honest:
|
|
|
587
615
|
- Files under `api/**` may not import `app/**` — "API code must not import client modules".
|
|
588
616
|
- `shared/**` imports neither, by construction (nothing in it references the other packages).
|
|
589
617
|
2. **The env split.** Public env vars are parsed only in `shared/util/env.ts`; secret env vars only in `api/util/env.ts`. A secret can never leak into a client bundle because the only file that reads it is un-importable from `app/`.
|
|
590
|
-
3. **Path aliases.** Cross-package imports of `shared/` go through bare aliases defined in `tsconfig.json` `paths`, which also enforce that folders with barrels are imported
|
|
618
|
+
3. **Path aliases.** Cross-package imports of `shared/` go through bare aliases defined in `tsconfig.json` `paths`, which also enforce that folders with barrels are imported _as_ the barrel:
|
|
591
619
|
|
|
592
620
|
```jsonc
|
|
593
621
|
"paths": {
|
|
@@ -660,12 +688,12 @@ This is a **key part of the workflow**, not an afterthought. Every code pull req
|
|
|
660
688
|
|
|
661
689
|
The setup is four workflows in `.github/workflows/`. The hosting below is described using Cloudflare (Pages for the static app bundle, Workers for the API) as the example technology — any host that supports named/branch deployments for static sites and named serverless deployments for the API works the same way.
|
|
662
690
|
|
|
663
|
-
| Workflow
|
|
664
|
-
|
|
665
|
-
| `deploy-preview.yml`
|
|
666
|
-
| `deploy-prod.yml`
|
|
667
|
-
| `smoke.yml`
|
|
668
|
-
| `teardown-preview.yml` | PR `closed`
|
|
691
|
+
| Workflow | Trigger | What it does |
|
|
692
|
+
| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
693
|
+
| `deploy-preview.yml` | PR `opened` / `synchronize` / `reopened` | Full test gate, then deploy a per-PR preview environment and post a sticky PR comment with the URLs |
|
|
694
|
+
| `deploy-prod.yml` | Push to `main` | Full test gate, then deploy to production |
|
|
695
|
+
| `smoke.yml` | `deployment_status` success (+ manual dispatch) | Run `@smoke`-tagged e2e tests against the freshly deployed URL |
|
|
696
|
+
| `teardown-preview.yml` | PR `closed` | Delete the per-PR deployments and update the sticky comment |
|
|
669
697
|
|
|
670
698
|
### The preview workflow (`deploy-preview.yml`)
|
|
671
699
|
|
|
@@ -678,8 +706,8 @@ on:
|
|
|
678
706
|
pull_request:
|
|
679
707
|
types: [opened, synchronize, reopened]
|
|
680
708
|
paths-ignore:
|
|
681
|
-
-
|
|
682
|
-
-
|
|
709
|
+
- "**/*.md"
|
|
710
|
+
- "docs/**"
|
|
683
711
|
|
|
684
712
|
permissions:
|
|
685
713
|
contents: read
|
|
@@ -709,7 +737,7 @@ jobs:
|
|
|
709
737
|
- run: bun install --frozen-lockfile
|
|
710
738
|
- if: steps.playwright-cache.outputs.cache-hit != 'true'
|
|
711
739
|
run: bunx playwright install chromium
|
|
712
|
-
- run: bun run test
|
|
740
|
+
- run: bun run test # the FULL gate: lint + type + unit + e2e
|
|
713
741
|
|
|
714
742
|
deploy:
|
|
715
743
|
needs: test
|
|
@@ -757,8 +785,8 @@ jobs:
|
|
|
757
785
|
The load-bearing decisions, each worth copying:
|
|
758
786
|
|
|
759
787
|
1. **Deterministic URLs derived from the PR number.** The slug `pr-<n>` names everything: the Pages branch alias (`pr-<n>.<project>.pages.dev`), the Worker (`pr-<n>-api`), the concurrency group. Anyone — human or LLM — can compute the preview URLs from the PR number alone, without reading the PR comment or querying the host.
|
|
760
|
-
2. **`paths-ignore` for docs.** Both deploy workflows ignore `'**/*.md'` and `'docs/**'`. Deploying because a README changed is pure waste. The trade-off (see gotchas below) is that docs-only PRs get
|
|
761
|
-
3. **Deploy gated on the full test gate.** The `deploy` job has `needs: test`, and `test` runs the
|
|
788
|
+
2. **`paths-ignore` for docs.** Both deploy workflows ignore `'**/*.md'` and `'docs/**'`. Deploying because a README changed is pure waste. The trade-off (see gotchas below) is that docs-only PRs get _no_ preview, which agents must know about.
|
|
789
|
+
3. **Deploy gated on the full test gate.** The `deploy` job has `needs: test`, and `test` runs the _entire_ local gate (`bun run test` = lint + type + unit + e2e), not a subset. Partial gates let e2e regressions reach deployed previews.
|
|
762
790
|
4. **Per-PR concurrency with `cancel-in-progress`.** Group `preview-pr-<n>` means a new push cancels the previous in-flight run — only the latest commit's preview survives, and runs for different PRs never queue behind each other.
|
|
763
791
|
5. **One multi-line env secret per environment.** The whole `.env` file lives in a single repo secret (`ENV_PREVIEW`, `ENV_PROD`) that the workflow writes to disk before building. One place to rotate, and the `[ -s .env ]` guard fails fast if the secret is missing/empty. Because builds use `--env=inline`, env values are frozen into the bundle — changing an env value means rebuilding and redeploying, not editing host config.
|
|
764
792
|
6. **The sticky PR comment.** The comment starts with a fixed marker line (`### Preview Environment`); each deploy finds the existing comment by that marker and updates it rather than posting a new one. The PR thread stays clean and always shows the current state.
|
|
@@ -782,8 +810,8 @@ Runs the `@smoke` subset of the e2e suite against whatever was just deployed:
|
|
|
782
810
|
|
|
783
811
|
```yaml
|
|
784
812
|
on:
|
|
785
|
-
deployment_status:
|
|
786
|
-
workflow_dispatch:
|
|
813
|
+
deployment_status: # fired by any deploy job that declares `environment:`
|
|
814
|
+
workflow_dispatch: # manual runs against the configured APP_URL
|
|
787
815
|
|
|
788
816
|
jobs:
|
|
789
817
|
smoke:
|
|
@@ -793,7 +821,7 @@ jobs:
|
|
|
793
821
|
- name: Use deployment URL as APP_URL
|
|
794
822
|
if: github.event.deployment_status.environment_url
|
|
795
823
|
run: echo "APP_URL=${{ github.event.deployment_status.environment_url }}" >> "$GITHUB_ENV"
|
|
796
|
-
- run: bun run smoke
|
|
824
|
+
- run: bun run smoke # bun test e2e -t @smoke, against $APP_URL
|
|
797
825
|
```
|
|
798
826
|
|
|
799
827
|
Notes:
|
|
@@ -815,7 +843,7 @@ Previews are disposable — tear them down when the PR closes (merged or not):
|
|
|
815
843
|
### Gotchas (read these before touching CI)
|
|
816
844
|
|
|
817
845
|
- **`.md` and `docs/**` changes do not trigger previews or deploys.** This is the `paths-ignore` working as intended, but it has consequences an LLM must anticipate: a docs-only PR gets no preview environment and its deploy-gated checks may show as skipped; a docs-only merge to `main` does **not** redeploy production. If you genuinely need a preview for a docs-only PR, include a code change or run the deploy manually. Conversely: don't wait for a preview URL to appear on a docs-only PR — it never will.
|
|
818
|
-
- **A new push cancels the in-flight deploy.** If you push twice quickly, the first run is cancelled mid-way by `cancel-in-progress` — a cancelled run is not a failure. Judge preview state by the
|
|
846
|
+
- **A new push cancels the in-flight deploy.** If you push twice quickly, the first run is cancelled mid-way by `cancel-in-progress` — a cancelled run is not a failure. Judge preview state by the _latest_ run and the commit SHA in the sticky comment.
|
|
819
847
|
- **Env is frozen at build time.** With `--env=inline` builds, changing `ENV_PREVIEW`/`ENV_PROD` does nothing to already-deployed bundles. Rebuild and redeploy (push a commit, or re-run the deploy workflow).
|
|
820
848
|
- **Preview and production must not share state.** The per-PR worker gets its own bindings; keep preview database/KV namespaces separate from production (e.g. a `preview_id` binding alongside the production id in the worker config).
|
|
821
849
|
- **Smoke failures against previews can be opaque** (process kills with no output). The diagnostic loop: reduce the failing e2e test to its first steps, add `console.debug` checkpoints around suspect boundaries, re-push to re-trigger the preview + smoke run, and read which checkpoints printed in the Actions logs.
|
|
@@ -872,10 +900,10 @@ Adding a feature called `order` touches these files, in this order:
|
|
|
872
900
|
|
|
873
901
|
1. `shared/collection/order.ts` — collection schema, create/pick variants, result schema, derived types. Add to `shared/collection/index.ts`.
|
|
874
902
|
2. `shared/endpoint/order.ts` — `export const ORDER_ENDPOINT = POST("/order", CREATE_ORDER, ORDER_RESULT);`. Add to `shared/endpoint/index.ts`.
|
|
875
|
-
3.
|
|
903
|
+
3. _(If both sides need config/domain classes)_ `shared/config/order/` and/or `shared/order/`, with barrels.
|
|
876
904
|
4. `api/services/order.ts` — `createOrder(create, context)` doing the actual work, plus `order.test.ts` using the mock context.
|
|
877
905
|
5. `api/handlers/order.ts` — `ORDER_HANDLERS` attaching the endpoint to the service. Spread into `api/handlers/index.ts`.
|
|
878
|
-
6.
|
|
906
|
+
6. _(If the server needs its own config)_ `api/config/order/`, keeping the `satisfies` completeness check in its barrel.
|
|
879
907
|
7. `app/order/OrderPage.tsx` (+ feature-local components/styles/tests in `app/order/`).
|
|
880
908
|
8. Register the route in `app/App.tsx`.
|
|
881
909
|
9. Run the full test gate locally, then open a PR — CI runs the same gate and deploys a preview environment at the deterministic per-PR URLs. Verify the feature against the live preview (smoke tests run against it automatically) before merging.
|
|
@@ -7,7 +7,7 @@ The rules here are portable: they describe the style itself, not this repository
|
|
|
7
7
|
## Philosophy
|
|
8
8
|
|
|
9
9
|
- **Reuse before writing.** Before writing a new function, component, or type, scan the codebase for something that already does the job — exactly, or closely enough that a parameter or variant covers the difference. Compose existing primitives rather than reinvent.
|
|
10
|
-
- **Immutability by default.** Data in, new data out. Helpers that "change" a value return an updated copy — and intentionally return the
|
|
10
|
+
- **Immutability by default.** Data in, new data out. Helpers that "change" a value return an updated copy — and intentionally return the _original reference_ when nothing changed, so equality checks stay cheap.
|
|
11
11
|
- **Contracts in names.** A function's prefix (`get*`, `require*`, `assert*`, `create*`, …) is a promise about its behaviour. Callers depend on it, so pick the prefix that matches the contract exactly.
|
|
12
12
|
- **Terse inside, descriptive outside.** Exported names are clear and descriptive; inside a small function body, very short names are preferred.
|
|
13
13
|
|
|
@@ -46,27 +46,27 @@ The rules here are portable: they describe the style itself, not this repository
|
|
|
46
46
|
|
|
47
47
|
Pick the prefix that matches the contract — they are not interchangeable.
|
|
48
48
|
|
|
49
|
-
| Prefix
|
|
50
|
-
|
|
51
|
-
| `is*`
|
|
52
|
-
| `has*`
|
|
53
|
-
| `assert*`
|
|
54
|
-
| `validate*` | Throws on invalid; returns the validated value (also strips/coerces)
|
|
55
|
-
| `get*`
|
|
56
|
-
| `require*`
|
|
57
|
-
| `create*`
|
|
58
|
-
| `with*`
|
|
59
|
-
| `omit*`
|
|
60
|
-
| `add*`
|
|
61
|
-
| `update*`
|
|
62
|
-
| `toggle*`
|
|
63
|
-
| `merge*`
|
|
64
|
-
| `to*`
|
|
65
|
-
| `format*`
|
|
66
|
-
| `parse*`
|
|
67
|
-
| `match*`
|
|
68
|
-
| `await*`
|
|
69
|
-
| `run*`
|
|
49
|
+
| Prefix | Contract | Examples |
|
|
50
|
+
| ----------- | -------------------------------------------------------------------------------------------------------- | --------------------- |
|
|
51
|
+
| `is*` | Boolean type guard returning `value is T` | `isArray`, `isString` |
|
|
52
|
+
| `has*` | Boolean predicate (possession / state, not type) | `hasItems` |
|
|
53
|
+
| `assert*` | Throws if invalid; uses `asserts value is T` | `assertArray` |
|
|
54
|
+
| `validate*` | Throws on invalid; returns the validated value (also strips/coerces) | `validateData` |
|
|
55
|
+
| `get*` | Returns value or `undefined` — never throws for "missing"; may return input unchanged when already valid | `getString` |
|
|
56
|
+
| `require*` | Returns value or throws | `requireFirst` |
|
|
57
|
+
| `create*` | Always returns a freshly constructed instance — never returns the input, never `undefined` | `createDeferred` |
|
|
58
|
+
| `with*` | Immutable updated copy with a value set | `withProp` |
|
|
59
|
+
| `omit*` | Immutable updated copy with keys removed | `omitProp` |
|
|
60
|
+
| `add*` | Immutable updated copy with an item added | `addArrayItem` |
|
|
61
|
+
| `update*` | Immutable updated copy with changes applied | `updateData` |
|
|
62
|
+
| `toggle*` | Immutable updated copy with a value toggled | `toggleArrayItem` |
|
|
63
|
+
| `merge*` | New value combining multiple inputs | `mergeObject` |
|
|
64
|
+
| `to*` | Pure conversion to another shape | `toStringValue` |
|
|
65
|
+
| `format*` | Value → display string | `formatDate` |
|
|
66
|
+
| `parse*` | String → structured value (inverse of `format*`) | `parseRequest` |
|
|
67
|
+
| `match*` | Result of matching / filtering | `matchQuery` |
|
|
68
|
+
| `await*` | Async counterpart of an otherwise-sync helper | `awaitArray` |
|
|
69
|
+
| `run*` | Executes a callback or sequence | `runSequence` |
|
|
70
70
|
|
|
71
71
|
- **Pairing rule:** `get*` / `require*` and `is*` / `assert*` come as pairs over the same target. If you add a new `require*`, consider whether a sibling `get*` belongs alongside it; same for `assert*` / `is*`.
|
|
72
72
|
- **`get*` vs `create*`:** a helper that unconditionally constructs a brand-new instance is `create*`. Reserve `get*` for "look up, coerce, or normalise" — helpers that may return the input unchanged or return `undefined`. Most construction is written inline as `new X(...)`; `create*` is for the few helpers that wrap construction.
|
|
@@ -75,12 +75,12 @@ Pick the prefix that matches the contract — they are not interchangeable.
|
|
|
75
75
|
|
|
76
76
|
Reserved for the UI layer — don't repurpose them for unrelated helpers:
|
|
77
77
|
|
|
78
|
-
| Prefix
|
|
79
|
-
|
|
80
|
-
| `notify*` | Dispatches a notice / custom event
|
|
81
|
-
| `call*`
|
|
82
|
-
| `handle*` | Top-level request / event entry point
|
|
83
|
-
| `on*`
|
|
78
|
+
| Prefix | Contract |
|
|
79
|
+
| --------- | ---------------------------------------------------------------- |
|
|
80
|
+
| `notify*` | Dispatches a notice / custom event |
|
|
81
|
+
| `call*` | Runs a callback, dispatching notices on return / throw |
|
|
82
|
+
| `handle*` | Top-level request / event entry point |
|
|
83
|
+
| `on*` | Event-handler **prop** name on a component (not a function name) |
|
|
84
84
|
|
|
85
85
|
## Imports & exports
|
|
86
86
|
|
|
@@ -179,7 +179,7 @@ if (n.startsWith("44")) return formatUK(n.slice(2));
|
|
|
179
179
|
|
|
180
180
|
- Short single-line `//` comments label sections of a function. Sentence case, ending in a period: `// Stop the page reloading.`
|
|
181
181
|
- Group several file-level constants under a `// Constants.` label.
|
|
182
|
-
- Comment the
|
|
182
|
+
- Comment the _why_ or the section purpose — never restate what the code says.
|
|
183
183
|
- The trailing-empty-comment trick — `Foo, //` — deliberately forces the formatter to keep an argument list multi-line:
|
|
184
184
|
|
|
185
185
|
```ts
|
package/docs/index.md
CHANGED
|
@@ -13,8 +13,8 @@ npm install shelving
|
|
|
13
13
|
Shelving is an ES module. Import from the main package or from individual module subpaths:
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
-
import { STRING, DataSchema } from "shelving"
|
|
17
|
-
import { MemoryDBProvider } from "shelving/db"
|
|
16
|
+
import { STRING, DataSchema } from "shelving";
|
|
17
|
+
import { MemoryDBProvider } from "shelving/db";
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
## For AI agents
|
|
@@ -36,6 +36,7 @@ See [Releases](https://github.com/dhoulb/shelving/releases) on GitHub.
|
|
|
36
36
|
|
|
37
37
|
## Modules
|
|
38
38
|
|
|
39
|
+
|
|
39
40
|
## Pages
|
|
40
41
|
|
|
41
42
|
- [Guides](guides.md): Guides that explain how to use Shelving in a real project, and how to write code in the Shelving style.
|