shelving 1.268.2 → 1.269.0

package/package.json

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

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.