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.
Files changed (316) hide show
  1. package/docs/api/APIProvider.md +2 -2
  2. package/docs/api/CachedAPIProvider.md +6 -8
  3. package/docs/api/ClientAPIProvider.md +5 -5
  4. package/docs/api/DebugAPIProvider.md +3 -5
  5. package/docs/api/HydratingAPIProvider.md +2 -2
  6. package/docs/api/JSONAPIProvider.md +3 -5
  7. package/docs/api/LoggingAPIProvider.md +7 -9
  8. package/docs/api/MockAPIProvider.md +4 -4
  9. package/docs/api/MockEndpointAPIProvider.md +5 -7
  10. package/docs/api/ThroughAPIProvider.md +15 -10
  11. package/docs/api/ValidationAPIProvider.md +3 -5
  12. package/docs/api/XMLAPIProvider.md +3 -3
  13. package/docs/api.md +48 -44
  14. package/docs/bun.md +9 -9
  15. package/docs/db/DBProvider.md +6 -6
  16. package/docs/db/MemoryDBProvider.md +3 -3
  17. package/docs/db/PostgresProvider.md +6 -4
  18. package/docs/db/SQLProvider.md +6 -3
  19. package/docs/db/SQLiteProvider.md +9 -4
  20. package/docs/db/StorageDBProvider.md +2 -2
  21. package/docs/db/ThroughDBProvider.md +6 -6
  22. package/docs/db/UndoDBProvider.md +2 -2
  23. package/docs/db.md +32 -32
  24. package/docs/error/NetworkError.md +5 -5
  25. package/docs/error/RequestError.md +4 -4
  26. package/docs/error/RequiredError.md +2 -2
  27. package/docs/error/ResponseError.md +1 -1
  28. package/docs/error/UnexpectedError.md +1 -1
  29. package/docs/error/UnsupportedError.md +3 -3
  30. package/docs/error/ValueError.md +2 -2
  31. package/docs/error.md +20 -19
  32. package/docs/extract.md +14 -14
  33. package/docs/firebase.md +6 -6
  34. package/docs/guides/building-with-shelving.md +113 -85
  35. package/docs/guides/styleguide.md +29 -29
  36. package/docs/index.md +3 -2
  37. package/docs/llms-full.txt +2541 -2295
  38. package/docs/markup.md +15 -17
  39. package/docs/react/createAPIContext.md +12 -12
  40. package/docs/react/createDBContext.md +21 -15
  41. package/docs/react/useInstance.md +2 -2
  42. package/docs/react/useLazy.md +1 -1
  43. package/docs/react/useMap.md +10 -6
  44. package/docs/react/useReduce.md +2 -2
  45. package/docs/react/useSequence.md +2 -2
  46. package/docs/react/useStore.md +10 -10
  47. package/docs/react.md +22 -16
  48. package/docs/schema/ArraySchema.md +6 -6
  49. package/docs/schema/BooleanSchema.md +5 -5
  50. package/docs/schema/ChoiceSchema.md +1 -1
  51. package/docs/schema/CurrencyAmountSchema.md +2 -2
  52. package/docs/schema/DataSchema.md +5 -5
  53. package/docs/schema/NullableSchema.md +4 -4
  54. package/docs/schema/NumberSchema.md +4 -4
  55. package/docs/schema/OptionalSchema.md +1 -1
  56. package/docs/schema/StringSchema.md +7 -7
  57. package/docs/schema.md +21 -21
  58. package/docs/sequence/DeferredSequence.md +1 -1
  59. package/docs/sequence/InspectSequence.md +8 -6
  60. package/docs/sequence/LazySequence.md +3 -3
  61. package/docs/sequence/Sequence.md +6 -6
  62. package/docs/sequence/ThroughSequence.md +4 -2
  63. package/docs/sequence.md +3 -3
  64. package/docs/store/ArrayStore.md +6 -6
  65. package/docs/store/BooleanStore.md +2 -2
  66. package/docs/store/BusyStore.md +1 -1
  67. package/docs/store/DataStore.md +5 -5
  68. package/docs/store/DictionaryStore.md +4 -4
  69. package/docs/store/FetchStore.md +6 -6
  70. package/docs/store/PathStore.md +4 -4
  71. package/docs/store/PayloadFetchStore.md +1 -5
  72. package/docs/store/Store.md +8 -6
  73. package/docs/store/URLStore.md +5 -5
  74. package/docs/store.md +15 -15
  75. package/docs/test.md +6 -6
  76. package/docs/ui/App.md +99 -69
  77. package/docs/ui/AppLayout.md +35 -26
  78. package/docs/ui/BackButton.md +13 -11
  79. package/docs/ui/Button.md +73 -64
  80. package/docs/ui/Card.md +23 -22
  81. package/docs/ui/Catcher.md +3 -3
  82. package/docs/ui/ClassProps.md +1 -1
  83. package/docs/ui/Code.md +11 -11
  84. package/docs/ui/CollapseTransition.md +5 -5
  85. package/docs/ui/Deleted.md +6 -6
  86. package/docs/ui/Details.md +13 -13
  87. package/docs/ui/Dialog.md +42 -28
  88. package/docs/ui/Dialogs.md +4 -0
  89. package/docs/ui/DocumentationButtons.md +2 -2
  90. package/docs/ui/DocumentationCard.md +2 -2
  91. package/docs/ui/DocumentationFrame.md +4 -4
  92. package/docs/ui/DocumentationLive.md +11 -11
  93. package/docs/ui/DocumentationPage.md +3 -3
  94. package/docs/ui/Emphasis.md +4 -4
  95. package/docs/ui/Empty.md +2 -2
  96. package/docs/ui/FadeTransition.md +9 -9
  97. package/docs/ui/Field.md +14 -14
  98. package/docs/ui/FixedLayout.md +27 -25
  99. package/docs/ui/Form.md +41 -39
  100. package/docs/ui/FormStore.md +6 -2
  101. package/docs/ui/Grid.md +21 -9
  102. package/docs/ui/HTML.md +10 -8
  103. package/docs/ui/Head.md +2 -3
  104. package/docs/ui/Heading.md +12 -12
  105. package/docs/ui/HorizontalTransition.md +10 -10
  106. package/docs/ui/Icon.md +4 -4
  107. package/docs/ui/ImageInput.md +12 -12
  108. package/docs/ui/Inserted.md +6 -6
  109. package/docs/ui/Link.md +11 -11
  110. package/docs/ui/List.md +7 -7
  111. package/docs/ui/Loading.md +6 -6
  112. package/docs/ui/Mark.md +11 -9
  113. package/docs/ui/Markup.md +4 -4
  114. package/docs/ui/Menu.md +24 -24
  115. package/docs/ui/MenuItem.md +29 -29
  116. package/docs/ui/Modal.md +57 -45
  117. package/docs/ui/Navigation.md +28 -26
  118. package/docs/ui/NavigationStore.md +18 -18
  119. package/docs/ui/Notice.md +15 -15
  120. package/docs/ui/Notices.md +17 -17
  121. package/docs/ui/Page.md +13 -13
  122. package/docs/ui/Panel.md +8 -8
  123. package/docs/ui/Paragraph.md +5 -5
  124. package/docs/ui/Progress.md +11 -11
  125. package/docs/ui/Prose.md +6 -6
  126. package/docs/ui/QueryRadiosInput.md +2 -2
  127. package/docs/ui/RouteCache.md +27 -27
  128. package/docs/ui/Router.md +70 -61
  129. package/docs/ui/SchemaInput.md +20 -20
  130. package/docs/ui/Scroll.md +16 -16
  131. package/docs/ui/Section.md +13 -10
  132. package/docs/ui/SidebarLayout.md +27 -27
  133. package/docs/ui/Small.md +4 -4
  134. package/docs/ui/Span.md +3 -1
  135. package/docs/ui/StackButton.md +13 -7
  136. package/docs/ui/Strong.md +4 -4
  137. package/docs/ui/Subheading.md +12 -12
  138. package/docs/ui/TINT_CLASS.md +11 -11
  139. package/docs/ui/Table.md +40 -29
  140. package/docs/ui/Tag.md +15 -15
  141. package/docs/ui/Title.md +13 -13
  142. package/docs/ui/Transition.md +22 -22
  143. package/docs/ui/TreeApp.md +8 -8
  144. package/docs/ui/TreeMarkup.md +2 -2
  145. package/docs/ui/TreeMenu.md +3 -3
  146. package/docs/ui/TreeSidebar.md +1 -1
  147. package/docs/ui/VerticalTransition.md +8 -8
  148. package/docs/ui/getClass.md +10 -10
  149. package/docs/ui/getColorClass.md +23 -23
  150. package/docs/ui/getDurationClass.md +5 -5
  151. package/docs/ui/getGridClass.md +2 -2
  152. package/docs/ui/getHeightClass.md +4 -4
  153. package/docs/ui/getRadiusClass.md +9 -9
  154. package/docs/ui/getShadowClass.md +6 -6
  155. package/docs/ui/getSpaceClass.md +13 -13
  156. package/docs/ui/getStrokeClass.md +6 -6
  157. package/docs/ui/getTypographyClass.md +38 -38
  158. package/docs/ui/getWidthClass.md +4 -4
  159. package/docs/ui/notify.md +11 -11
  160. package/docs/ui/requireContext.md +1 -1
  161. package/docs/ui.md +4 -4
  162. package/docs/util/array.md +35 -29
  163. package/docs/util/async.md +2 -2
  164. package/docs/util/base64.md +7 -7
  165. package/docs/util/boolean.md +10 -10
  166. package/docs/util/buffer.md +5 -5
  167. package/docs/util/bytes.md +9 -9
  168. package/docs/util/class.md +10 -6
  169. package/docs/util/color.md +13 -13
  170. package/docs/util/constants.md +2 -2
  171. package/docs/util/crypto.md +1 -1
  172. package/docs/util/currency.md +2 -2
  173. package/docs/util/data.md +18 -18
  174. package/docs/util/date.md +22 -22
  175. package/docs/util/debug/debug.md +12 -12
  176. package/docs/util/dictionary.md +21 -18
  177. package/docs/util/diff.md +6 -6
  178. package/docs/util/dispose/dispose.md +5 -5
  179. package/docs/util/duration.md +9 -9
  180. package/docs/util/element.md +1 -1
  181. package/docs/util/entity.md +6 -6
  182. package/docs/util/entry.md +21 -8
  183. package/docs/util/env.md +2 -2
  184. package/docs/util/equal.md +16 -16
  185. package/docs/util/error.md +4 -4
  186. package/docs/util/file.md +8 -8
  187. package/docs/util/filter.md +9 -5
  188. package/docs/util/format.md +18 -18
  189. package/docs/util/function.md +4 -4
  190. package/docs/util/geo.md +13 -13
  191. package/docs/util/hash.md +3 -3
  192. package/docs/util/http.md +1 -1
  193. package/docs/util/hydrate/hydrate.md +7 -4
  194. package/docs/util/item.md +4 -4
  195. package/docs/util/iterate.md +11 -11
  196. package/docs/util/jwt.md +1 -6
  197. package/docs/util/link.md +5 -5
  198. package/docs/util/map.md +17 -11
  199. package/docs/util/merge.md +2 -5
  200. package/docs/util/null.md +20 -10
  201. package/docs/util/number.md +16 -16
  202. package/docs/util/object.md +25 -22
  203. package/docs/util/path.md +17 -17
  204. package/docs/util/query.md +23 -25
  205. package/docs/util/random.md +7 -7
  206. package/docs/util/regexp.md +16 -16
  207. package/docs/util/sequence.md +16 -10
  208. package/docs/util/serialise/serialise.md +6 -6
  209. package/docs/util/set.md +10 -10
  210. package/docs/util/sort.md +10 -11
  211. package/docs/util/source.md +11 -7
  212. package/docs/util/start.md +8 -8
  213. package/docs/util/string.md +14 -14
  214. package/docs/util/template.md +3 -3
  215. package/docs/util/timeout.md +5 -5
  216. package/docs/util/transform.md +6 -6
  217. package/docs/util/tree.md +13 -13
  218. package/docs/util/undefined.md +3 -3
  219. package/docs/util/units.md +15 -15
  220. package/docs/util/update.md +16 -16
  221. package/docs/util/uri.md +12 -12
  222. package/docs/util/url.md +11 -11
  223. package/docs/util/uuid.md +3 -3
  224. package/docs/util/validate.md +14 -9
  225. package/package.json +3 -3
  226. package/skills/shelving/SKILL.md +1 -0
  227. package/ui/README.md +4 -4
  228. package/ui/app/App.md +99 -69
  229. package/ui/block/Card.md +23 -22
  230. package/ui/block/Details.md +13 -13
  231. package/ui/block/Grid.md +21 -9
  232. package/ui/block/Heading.md +12 -12
  233. package/ui/block/List.md +7 -7
  234. package/ui/block/Panel.md +8 -8
  235. package/ui/block/Paragraph.md +5 -5
  236. package/ui/block/Prose.md +6 -6
  237. package/ui/block/Section.md +13 -10
  238. package/ui/block/Subheading.md +12 -12
  239. package/ui/block/Title.md +13 -13
  240. package/ui/button/Button.md +73 -64
  241. package/ui/dialog/Dialog.md +42 -28
  242. package/ui/dialog/Dialogs.d.ts +4 -0
  243. package/ui/dialog/Dialogs.js +4 -0
  244. package/ui/dialog/Dialogs.tsx +4 -0
  245. package/ui/dialog/Modal.md +57 -45
  246. package/ui/docs/DocumentationButtons.md +2 -2
  247. package/ui/docs/DocumentationCard.md +2 -2
  248. package/ui/docs/DocumentationFrame.md +4 -4
  249. package/ui/docs/DocumentationLive.md +11 -11
  250. package/ui/docs/DocumentationPage.md +3 -3
  251. package/ui/form/Field.md +14 -14
  252. package/ui/form/Form.md +41 -39
  253. package/ui/form/FormStore.md +6 -2
  254. package/ui/form/Progress.md +11 -11
  255. package/ui/inline/Code.md +11 -11
  256. package/ui/inline/Deleted.md +6 -6
  257. package/ui/inline/Emphasis.md +4 -4
  258. package/ui/inline/Inserted.md +6 -6
  259. package/ui/inline/Link.md +11 -11
  260. package/ui/inline/Mark.md +11 -9
  261. package/ui/inline/Small.md +4 -4
  262. package/ui/inline/Span.md +3 -1
  263. package/ui/inline/Strong.md +4 -4
  264. package/ui/input/ImageInput.md +12 -12
  265. package/ui/input/QueryRadiosInput.md +2 -2
  266. package/ui/input/SchemaInput.md +20 -20
  267. package/ui/layout/AppLayout.md +35 -26
  268. package/ui/layout/AppLayout.module.css +3 -16
  269. package/ui/layout/FixedLayout.md +27 -25
  270. package/ui/layout/SidebarLayout.md +27 -27
  271. package/ui/layout/SidebarLayout.module.css +1 -0
  272. package/ui/menu/Menu.md +24 -24
  273. package/ui/menu/MenuItem.md +29 -29
  274. package/ui/misc/Catcher.md +3 -3
  275. package/ui/misc/Icon.md +4 -4
  276. package/ui/misc/Loading.md +6 -6
  277. package/ui/misc/Markup.md +4 -4
  278. package/ui/misc/Tag.md +15 -15
  279. package/ui/notice/Empty.md +2 -2
  280. package/ui/notice/Notice.md +15 -15
  281. package/ui/notice/Notices.md +17 -17
  282. package/ui/page/HTML.md +10 -8
  283. package/ui/page/Head.md +2 -3
  284. package/ui/page/Page.md +13 -13
  285. package/ui/router/BackButton.md +13 -11
  286. package/ui/router/Navigation.md +28 -26
  287. package/ui/router/NavigationStore.md +18 -18
  288. package/ui/router/RouteCache.md +27 -27
  289. package/ui/router/Router.md +70 -61
  290. package/ui/router/StackButton.md +13 -7
  291. package/ui/style/Scroll.md +16 -16
  292. package/ui/style/TINT_CLASS.md +11 -11
  293. package/ui/style/getColorClass.md +23 -23
  294. package/ui/style/getDurationClass.md +5 -5
  295. package/ui/style/getGridClass.md +2 -2
  296. package/ui/style/getHeightClass.md +4 -4
  297. package/ui/style/getRadiusClass.md +9 -9
  298. package/ui/style/getShadowClass.md +6 -6
  299. package/ui/style/getSpaceClass.md +13 -13
  300. package/ui/style/getStrokeClass.md +6 -6
  301. package/ui/style/getTypographyClass.md +38 -38
  302. package/ui/style/getWidthClass.md +4 -4
  303. package/ui/table/Table.md +40 -30
  304. package/ui/transition/CollapseTransition.md +5 -5
  305. package/ui/transition/FadeTransition.md +9 -9
  306. package/ui/transition/HorizontalTransition.md +10 -10
  307. package/ui/transition/Transition.md +22 -22
  308. package/ui/transition/VerticalTransition.md +8 -8
  309. package/ui/tree/TreeApp.md +8 -8
  310. package/ui/tree/TreeMarkup.md +2 -2
  311. package/ui/tree/TreeMenu.md +3 -3
  312. package/ui/tree/TreeSidebar.md +1 -1
  313. package/ui/util/ClassProps.md +1 -1
  314. package/ui/util/getClass.md +10 -10
  315. package/ui/util/notify.md +11 -11
  316. 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 *derived* from them with `ValidatorType`. You never write a type by hand and a validator separately.
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 *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.
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/` *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.
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 *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.
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 *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."
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
- <Navigation>
403
- <PageLoader>
404
- <Router routes={ROUTES} />
405
- </PageLoader>
406
- </Navigation>
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
- <Scroll vertical cover>
417
- <PageLoader>
418
- <Router routes={ROUTES} />
419
- </PageLoader>
420
- </Scroll>
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
- <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
431
- <LoginForm />
432
- </Block>
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
- <Scroll vertical cover>
443
- <Router routes={ROUTES} />
444
- </Scroll>
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. The bar has its own view-transition group, so it stays still while pages slide. Set `nav={false}` to hide the bar.
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
- <Scroll vertical cover>
455
- <Router routes={ROUTES} />
456
- </Scroll>
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
- return (
473
- <div className={LAYOUT_CLASS}>
474
- <header className={BAR_CLASS}>{bar}</header>
475
- <main className={CONTENT_CLASS}>{children}</main>
476
- </div>
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
- html:has(.layout) { height: 100dvh; overflow: hidden; }
484
- body:has(.layout) { position: fixed; inset: 0; margin: 0; }
485
- .layout { position: absolute; inset: 0; display: flex; flex-direction: column; }
486
- .content { position: relative; flex: 1; min-height: 0; overflow: hidden; }
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
- <Scroll vertical cover>
503
- <PageLoader>
504
- <Router routes={ROUTES} />
505
- </PageLoader>
506
- </Scroll>
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
- <HorizontalTransition>
519
- <RouteCache>
520
- <Scroll vertical cover>…</Scroll>
521
- </RouteCache>
522
- </HorizontalTransition>
523
- </AppLayout>
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
- const { path } = requireMetaURL();
544
- return (
545
- <AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
546
- <Content />
547
- </AppLayout>
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
- if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
559
- return <AppLayout nav={<StackBar />}><Content routes={ROUTES} /></AppLayout>;
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
- return (
572
- <FixedLayout>
573
- <Scroll vertical cover>
574
- <ErrorPage reason={reason} />
575
- </Scroll>
576
- </FixedLayout>
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 *as* the barrel:
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 | Trigger | What it does |
664
- |---|---|---|
665
- | `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 |
666
- | `deploy-prod.yml` | Push to `main` | Full test gate, then deploy to production |
667
- | `smoke.yml` | `deployment_status` success (+ manual dispatch) | Run `@smoke`-tagged e2e tests against the freshly deployed URL |
668
- | `teardown-preview.yml` | PR `closed` | Delete the per-PR deployments and update the sticky comment |
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
- - '**/*.md'
682
- - 'docs/**'
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 # the FULL gate: lint + type + unit + e2e
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 *no* preview, which agents must know about.
761
- 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.
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: # fired by any deploy job that declares `environment:`
786
- workflow_dispatch: # manual runs against the configured APP_URL
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 # bun test e2e -t @smoke, against $APP_URL
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 *latest* run and the commit SHA in the sticky comment.
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. *(If both sides need config/domain classes)* `shared/config/order/` and/or `shared/order/`, with barrels.
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. *(If the server needs its own config)* `api/config/order/`, keeping the `satisfies` completeness check in its barrel.
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 *original reference* when nothing changed, so equality checks stay cheap.
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 | 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` |
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 | 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) |
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 *why* or the section purpose — never restate what the code says.
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.