shelving 1.268.1 → 1.269.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.268.1",
+	"version": "1.269.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/react/createAPIContext.d.ts

@@ -1,5 +1,6 @@
 import { type ReactElement } from "react";
 import type { Endpoint } from "../api/endpoint/Endpoint.js";
+import { APICache } from "../api/index.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
 import type { EndpointStore } from "../api/store/EndpointStore.js";
 import type { ChildProps } from "../ui/index.js";
@@ -13,8 +14,10 @@ export interface APIContext<P, R> {
     /** React hook to return an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Endpoint<PP, RR>, payload: PP): EndpointStore<PP, RR>;
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Nullish<Endpoint<PP, RR>>, payload: PP): EndpointStore<PP, RR> | undefined;
-    /** The `<APIContext>` wrapper to give your React components access to this API provider. */
+    /** Create a new `APICache` and provide it as context to child nodes, to allow them to use `useAPI()` */
     readonly APIContext: (props: ChildProps) => ReactElement;
+    /** Return the underlying `APICache` for `<APIContext>` */
+    requireAPICache(): APICache<P, R>;
 }
 /**
  * Create an API context.

package/react/createAPIContext.js

@@ -15,15 +15,18 @@ import { useStore } from "./useStore.js";
  */
 export function createAPIContext(provider) {
     const CacheContext = createContext(undefined);
-    function useAPI(endpoint, payload) {
+    function requireAPICache(caller = requireAPICache) {
         const cache = use(CacheContext);
         if (!cache)
-            throw new RequiredError(`useAPI() can only be used inside <APIContext>`, { caller: useAPI });
-        return useStore(endpoint ? cache.get(endpoint).get(payload) : undefined);
+            throw new RequiredError(`Must be used inside <APIContext>`, { caller });
+        return cache;
+    }
+    function useAPI(endpoint, payload) {
+        return useStore(endpoint ? requireAPICache(useAPI).get(endpoint).get(payload) : undefined);
     }
     function APIContext({ children }) {
         const cache = useInstance(APICache, provider);
         return _jsx(CacheContext, { value: cache, children: children });
     }
-    return { useAPI, APIContext };
+    return { requireAPICache, useAPI, APIContext };
 }

package/react/createDBContext.d.ts

@@ -1,4 +1,5 @@
 import { type ReactElement, type ReactNode } from "react";
+import { DBCache } from "../db/cache/DBCache.js";
 import type { Collection } from "../db/collection/Collection.js";
 import type { DBProvider } from "../db/provider/DBProvider.js";
 import type { ItemStore } from "../db/store/ItemStore.js";
@@ -23,10 +24,12 @@ export interface DBContext<I extends Identifier, T extends Data> {
     query: Nullish<Query<Item<II, TT>>>): QueryStore<II, TT> | undefined;
     useQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, //
     query: Query<Item<II, TT>>): QueryStore<II, TT>;
-    /** The `<DataContext>` wrapper to give your React components access to this data. */
+    /** Create a new `DBCache` and provide it as context to child nodes, to allow them to use `useItem()` and `useQuery()` */
     readonly DBContext: ({ children }: {
         children: ReactNode;
     }) => ReactElement;
+    /** Return the underlying `DBCache` for `<DBContext>` */
+    requireDBCache(): DBCache<I, T>;
 }
 /**
  * Create a data context

package/react/createDBContext.js

@@ -15,23 +15,23 @@ import { useStore } from "./useStore.js";
  */
 export function createDBContext(provider) {
     const CacheContext = createContext(undefined);
-    function useItem(collection, //
-    id) {
+    function requireDBCache(caller = requireDBCache) {
         const cache = use(CacheContext);
         if (!cache)
-            throw new RequiredError("useItem() can only be used inside <DBContext>", { caller: useItem });
-        return useStore(collection && id ? cache.getItem(collection, id) : undefined);
+            throw new RequiredError(`Must be used inside <DBContext>`, { caller });
+        return cache;
+    }
+    function useItem(collection, //
+    id) {
+        return useStore(collection && id ? requireDBCache(useItem).getItem(collection, id) : undefined);
     }
     function useQuery(collection, //
     query) {
-        const cache = use(CacheContext);
-        if (!cache)
-            throw new RequiredError("useQuery() can only be used inside <DBContext>", { caller: useQuery });
-        return useStore(collection && query ? cache.getQuery(collection, query) : undefined);
+        return useStore(collection && query ? requireDBCache(useQuery).getQuery(collection, query) : undefined);
     }
     function DBContext({ children }) {
         const cache = useInstance(DBCache, provider);
         return _jsx(CacheContext, { value: cache, children: children });
     }
-    return { useItem, useQuery, DBContext };
+    return { requireDBCache, useItem, useQuery, DBContext };
 }

package/ui/block/Card.d.ts

@@ -1,14 +1,15 @@
 import type { ReactElement } from "react";
 import { type ClickableProps } from "../button/Clickable.js";
 import { type BlockVariants } from "../style/Block.js";
+import { type ShadowVariants } from "../style/Shadow.js";
 import { type StatusVariants } from "../style/Status.js";
 import type { BlockElement } from "./Block.js";
 /**
- * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, and width variants.
+ * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, width, and shadow variants.
  *
  * @see https://shelving.cc/ui/CardProps
  */
-export interface CardProps extends ClickableProps, StatusVariants, BlockVariants {
+export interface CardProps extends ClickableProps, StatusVariants, BlockVariants, ShadowVariants {
     /**
      * Element this `<Card>` renders as, e.g. "header" to output a "<header>"
      * @default "article"
@@ -21,6 +22,7 @@ export interface CardProps extends ClickableProps, StatusVariants, BlockVariants
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
+ * - Carries a `normal` drop shadow by default — set `shadow="none"` to flatten a card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
  *
  * @kind component
  * @see https://shelving.cc/ui/Card

package/ui/block/Card.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Clickable } from "../button/Clickable.js";
 import { getBlockClass } from "../style/Block.js";
+import { getShadowClass } from "../style/Shadow.js";
 import { getStatusClass } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import CARD_CSS from "./Card.module.css";
@@ -10,6 +11,7 @@ import CARD_CSS from "./Card.module.css";
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
+ * - Carries a `normal` drop shadow by default — set `shadow="none"` to flatten a card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
  *
  * @kind component
  * @see https://shelving.cc/ui/Card
@@ -17,5 +19,5 @@ import CARD_CSS from "./Card.module.css";
 export function Card({ as: Element = "article", children, href, onClick, title = "Open", ...props }) {
     const overlay = (href || onClick) && (_jsx(Clickable, { title: title, href: href, onClick: onClick, ...props, className: getModuleClass(CARD_CSS, "overlay") }));
     return (_jsxs(Element, { className: getClass(getModuleClass(CARD_CSS, "card"), //
-        getStatusClass(props), getBlockClass(props)), children: [overlay, overlay ? _jsx("div", { children: children }) : children] }));
+        getStatusClass(props), getBlockClass(props), getShadowClass(props)), children: [overlay, overlay ? _jsx("div", { children: children }) : children] }));
 }

package/ui/block/Card.md

@@ -7,7 +7,8 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
 - 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.
 - `color=` and `status=` move the tint anchor for the card's scope, so the surface, border, text, and hover shade all re-derive together — and nested components (`<Tag>`, `<Preformatted>`, `<Button>`) inherit the same tint.
 - A card styles only the box. Lay out its contents with the usual block components (`<Subheading>`, `<Paragraph>`, `<Row>`, …).
-- Composes the standard styling variants: `color`, `status`, `padding`, `space`, `width`, plus typography.
+- Cards carry a `normal` drop shadow by default — set `shadow="none"` to flatten a given card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
+- Composes the standard styling variants: `color`, `status`, `padding`, `space`, `width`, `shadow`, plus typography.
 
 ## Usage
 
@@ -43,6 +44,16 @@ import { Card, Subheading } from "shelving/ui";
 <Card color="purple" padding="large" space="none"><Subheading>Featured</Subheading></Card>
 ```
 
+### Shadow
+
+```tsx
+import { Card, Subheading } from "shelving/ui";
+
+// Flatten one card; raise another.
+<Card shadow="none"><Subheading>Flat</Subheading></Card>
+<Card shadow="large"><Subheading>Raised</Subheading></Card>
+```
+
 ## Styling
 
 `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, border, text, and hover shade re-derive together; reach for a per-property hook for a single surgical change.
@@ -57,19 +68,20 @@ import { Card, Subheading } from "shelving/ui";
 | `--card-radius` | Corner radius | `var(--radius-normal)` (16px) |
 | `--card-padding` | Inner padding | `var(--space-normal)` (16px) |
 | `--card-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
-| `--card-shadow` | Drop shadow | `none` |
+| `--card-shadow` | Drop shadow | `var(--shadow-normal)` |
 | `--card-transition` | Transition | `all var(--duration-fast)` (150ms) |
 | `--card-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
 
-**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-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
+**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`, `--shadow-normal`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
 
 ```css
-/* Theme: borderless cards with a soft shadow and tighter corners. */
+/* Theme: flat cards with tighter corners. */
 :root {
-  --card-border: none;
-  --card-shadow: var(--shadow-small);
+  --card-shadow: none;
   --card-radius: var(--radius-small);
 }
 ```
 
+The `--card-shadow` hook sets the app-wide default; the `shadow=` variant prop wins over it on a per-card basis.
+
 To recolour cards, apply `color=` / `status=` to the card (or a tinted ancestor scope) — e.g. `<Card color="purple">` — rather than a per-component tint hook.

package/ui/block/Card.module.css

@@ -2,6 +2,7 @@
 @import url("../style/Color.module.css");
 @import url("../style/Duration.module.css");
 @import url("../style/Radius.module.css");
+@import url("../style/Shadow.module.css");
 @import url("../style/Space.module.css");
 @import url("../style/Stroke.module.css");
 @import url("../style/Tint.module.css");
@@ -30,7 +31,7 @@
 		/* Style */
 		background: var(--card-background, var(--tint-90));
 		color: var(--card-color, var(--tint-00));
-		box-shadow: var(--card-shadow, none);
+		box-shadow: var(--card-shadow, var(--shadow-normal));
 		transition: var(--card-transition, all var(--duration-fast));
 		outline: var(--card-focus-border, var(--stroke-focus) solid var(--color-focus));
 		outline-offset: calc(0px - var(--card-stroke, var(--stroke-normal)));

package/ui/block/Card.tsx

@@ -1,17 +1,18 @@
 import type { ReactElement } from "react";
 import { Clickable, type ClickableProps } from "../button/Clickable.js";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
+import { getShadowClass, type ShadowVariants } from "../style/Shadow.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { BlockElement } from "./Block.js";
 import CARD_CSS from "./Card.module.css";
 
 /**
- * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, and width variants.
+ * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, width, and shadow variants.
  *
  * @see https://shelving.cc/ui/CardProps
  */
-export interface CardProps extends ClickableProps, StatusVariants, BlockVariants {
+export interface CardProps extends ClickableProps, StatusVariants, BlockVariants, ShadowVariants {
 	/**
 	 * Element this `<Card>` renders as, e.g. "header" to output a "<header>"
 	 * @default "article"
@@ -25,6 +26,7 @@ export interface CardProps extends ClickableProps, StatusVariants, BlockVariants
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
+ * - Carries a `normal` drop shadow by default — set `shadow="none"` to flatten a card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
  *
  * @kind component
  * @see https://shelving.cc/ui/Card
@@ -39,6 +41,7 @@ export function Card({ as: Element = "article", children, href, onClick, title =
 				getModuleClass(CARD_CSS, "card"), //
 				getStatusClass(props),
 				getBlockClass(props),
+				getShadowClass(props),
 			)}
 		>
 			{overlay}

package/ui/style/Shadow.d.ts

@@ -3,7 +3,7 @@
  *
  * @see https://shelving.cc/ui/ShadowVariant
  */
-export type ShadowVariant = "none" | "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge";
+export type ShadowVariant = "none" | "small" | "normal" | "large";
 /**
  * Variant props for the drop shadow of an element, e.g. `shadow="large"`.
  *

package/ui/style/Shadow.module.css

@@ -6,13 +6,9 @@
 		--shadow-color: #0006;
 
 		/* Shadows — elevation drop-shadows. */
-		--shadow-xxsmall: 0 0.125rem 0.5rem -0.25rem var(--shadow-color);
-		--shadow-xsmall: 0 0.25rem 1rem -0.5rem var(--shadow-color);
 		--shadow-small: 0 0.375rem 1.5rem -0.75rem var(--shadow-color);
 		--shadow-normal: 0 0.5rem 2rem -1rem var(--shadow-color);
 		--shadow-large: 0 0.75rem 3rem -1.5rem var(--shadow-color);
-		--shadow-xlarge: 0 1rem 4rem -2rem var(--shadow-color);
-		--shadow-xxlarge: 0 1.5rem 6rem -3rem var(--shadow-color);
 	}
 }
 
@@ -22,14 +18,6 @@
 		box-shadow: none;
 	}
 
-	.shadow-xxsmall {
-		box-shadow: var(--shadow-xxsmall);
-	}
-
-	.shadow-xsmall {
-		box-shadow: var(--shadow-xsmall);
-	}
-
 	.shadow-small {
 		box-shadow: var(--shadow-small);
 	}
@@ -41,12 +29,4 @@
 	.shadow-large {
 		box-shadow: var(--shadow-large);
 	}
-
-	.shadow-xlarge {
-		box-shadow: var(--shadow-xlarge);
-	}
-
-	.shadow-xxlarge {
-		box-shadow: var(--shadow-xxlarge);
-	}
 }

package/ui/style/Shadow.tsx

@@ -6,7 +6,7 @@ import SHADOW_CSS from "./Shadow.module.css";
  *
  * @see https://shelving.cc/ui/ShadowVariant
  */
-export type ShadowVariant = "none" | "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge";
+export type ShadowVariant = "none" | "small" | "normal" | "large";
 
 /**
  * Variant props for the drop shadow of an element, e.g. `shadow="large"`.

package/ui/style/getShadowClass.md

@@ -8,10 +8,8 @@ The following `:root` variables are defined by this module and can be overridden
 
 | Variable | Default |
 |---|---|
-| `--shadow-xxsmall` | `0 0.125rem 0.5rem -0.25rem #0006` |
-| `--shadow-xsmall` | `0 0.25rem 1rem -0.5rem #0006` |
 | `--shadow-small` | `0 0.375rem 1.5rem -0.75rem #0006` |
 | `--shadow-normal` | `0 0.5rem 2rem -1rem #0006` |
 | `--shadow-large` | `0 0.75rem 3rem -1.5rem #0006` |
-| `--shadow-xlarge` | `0 1rem 4rem -2rem #0006` |
-| `--shadow-xxlarge` | `0 1.5rem 6rem -3rem #0006` |
+
+The `shadow=` variant prop accepts `"none"`, `"small"`, `"normal"`, or `"large"` — `"none"` removes a component's default shadow rather than mapping to a token.