shelving 1.238.0 → 1.239.0

package/package.json

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

package/ui/block/Panel.d.ts

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants } from "../style/Color.js";
+import { type PaddingVariants } from "../style/Padding.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
@@ -14,20 +15,20 @@ export type PanelElement = "section" | "header" | "footer" | "nav" | "aside" | "
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelProps
  */
-export interface PanelProps extends ColorVariants, StatusVariants, TypographyVariants, OptionalChildProps {
+export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
 }
 /**
  * Full-width vertical region that paints the current surface colour. Use to break a page into stacked
- * sections. Has zero block-space (Panels butt against each other) but big vertical padding by
- * default — adjust with the `padding` prop (`<Panel padding="large">` etc.).
+ * sections. Has zero block-space (Panels butt against each other); set its vertical breathing room
+ * with the `padding` variant (`<Panel padding="large">`, `<Panel padding="xxlarge">` etc.).
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
  * @kind component
- * @param props Colour, status, and typography variants plus `children`.
+ * @param props Colour, padding, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
- * @example <Panel as="header" color="primary"><Title>Welcome</Title></Panel>
+ * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
 export declare function Panel({ children, ...props }: PanelProps): ReactElement;

package/ui/block/Panel.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getColorClass } from "../style/Color.js";
+import { getPaddingClass } from "../style/Padding.js";
 import { getStatusClass } from "../style/Status.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
@@ -7,19 +8,19 @@ import PANEL_CSS from "./Panel.module.css";
 const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
 /**
  * Full-width vertical region that paints the current surface colour. Use to break a page into stacked
- * sections. Has zero block-space (Panels butt against each other) but big vertical padding by
- * default — adjust with the `padding` prop (`<Panel padding="large">` etc.).
+ * sections. Has zero block-space (Panels butt against each other); set its vertical breathing room
+ * with the `padding` variant (`<Panel padding="large">`, `<Panel padding="xxlarge">` etc.).
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
  * @kind component
- * @param props Colour, status, and typography variants plus `children`.
+ * @param props Colour, padding, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
- * @example <Panel as="header" color="primary"><Title>Welcome</Title></Panel>
+ * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
 export function Panel({ children, ...props }) {
     return (_jsx("div", { className: getClass(PANEL_CLASS, //
-        getStatusClass(props), getColorClass(props), getTypographyClass(props)), children: children }));
+        getStatusClass(props), getColorClass(props), getPaddingClass(props), getTypographyClass(props)), children: children }));
 }

package/ui/block/Panel.module.css

@@ -4,10 +4,10 @@
 
 /*
  * Full-width vertical region that paints the current surface. Panels always have zero block-space
- * (they butt up against each other vertically to create stacked page sections) but they do have
- * vertical `padding-block` — `xxlarge` by default, overridable via PaddingVariants (`.padding-large`,
- * `.padding-none`, etc.). Inline padding is fixed at `--space-normal`; if you want narrower content
- * inside a wide panel, compose a `<Block narrow>` (or `<Block wide>`) inside it.
+ * (they butt up against each other vertically to create stacked page sections). Vertical breathing
+ * room comes from the shared `padding` variant (`.large`, `.xxlarge`, etc. from `style/Padding`);
+ * with no `padding` the block padding is zero and the inner `<Section>` margins provide the spacing.
+ * For narrower content inside a wide panel, compose a `<Block narrow>` (or `<Block wide>`) inside it.
  */
 @layer components {
 	.panel {

package/ui/block/Panel.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
+import { getPaddingClass, type PaddingVariants } from "../style/Padding.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
@@ -20,20 +21,20 @@ export type PanelElement = "section" | "header" | "footer" | "nav" | "aside" | "
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelProps
  */
-export interface PanelProps extends ColorVariants, StatusVariants, TypographyVariants, OptionalChildProps {}
+export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {}
 
 /**
  * Full-width vertical region that paints the current surface colour. Use to break a page into stacked
- * sections. Has zero block-space (Panels butt against each other) but big vertical padding by
- * default — adjust with the `padding` prop (`<Panel padding="large">` etc.).
+ * sections. Has zero block-space (Panels butt against each other); set its vertical breathing room
+ * with the `padding` variant (`<Panel padding="large">`, `<Panel padding="xxlarge">` etc.).
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
  * @kind component
- * @param props Colour, status, and typography variants plus `children`.
+ * @param props Colour, padding, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
- * @example <Panel as="header" color="primary"><Title>Welcome</Title></Panel>
+ * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
 export function Panel({ children, ...props }: PanelProps): ReactElement {
@@ -43,6 +44,7 @@ export function Panel({ children, ...props }: PanelProps): ReactElement {
 				PANEL_CLASS, //
 				getStatusClass(props),
 				getColorClass(props),
+				getPaddingClass(props),
 				getTypographyClass(props),
 			)}
 		>

package/ui/docs/DocumentationHomePage.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+import type { TreeElementProps } from "../../util/tree.js";
+/**
+ * Page renderer for the documentation site's home page — a bold coloured hero panel over the module listing.
+ * - The whole page sits in a single `color="red"` `<Block>`, so the hero panel, prose, and child cards all pick up the red tint.
+ * - The hero is a full-padding `<Panel>` with the package name centred as a large `<Title>`.
+ * - Below the hero it renders any absorbed prose content, then the root's children (the modules) as a stack of cards.
+ *
+ * @kind component
+ * @param props The root tree element props (`title`, `name`, `description`, `content`, `children`).
+ * @returns A `<Page>` with a coloured hero panel followed by the module listing.
+ * @example <DocumentationHomePage {...root.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationHomePage/DocumentationHomePage
+ */
+export declare function DocumentationHomePage({ title, name, description, content, children }: TreeElementProps): ReactNode;

package/ui/docs/DocumentationHomePage.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Block } from "../block/Block.js";
+import { Panel } from "../block/Panel.js";
+import { Prose } from "../block/Prose.js";
+import { Section } from "../block/Section.js";
+import { Title } from "../block/Title.js";
+import { Markup } from "../misc/Markup.js";
+import { Page } from "../page/Page.js";
+import { TreeCards } from "../tree/TreeCards.js";
+/**
+ * Page renderer for the documentation site's home page — a bold coloured hero panel over the module listing.
+ * - The whole page sits in a single `color="red"` `<Block>`, so the hero panel, prose, and child cards all pick up the red tint.
+ * - The hero is a full-padding `<Panel>` with the package name centred as a large `<Title>`.
+ * - Below the hero it renders any absorbed prose content, then the root's children (the modules) as a stack of cards.
+ *
+ * @kind component
+ * @param props The root tree element props (`title`, `name`, `description`, `content`, `children`).
+ * @returns A `<Page>` with a coloured hero panel followed by the module listing.
+ * @example <DocumentationHomePage {...root.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationHomePage/DocumentationHomePage
+ */
+export function DocumentationHomePage({ title, name, description, content, children }) {
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: "red", children: [_jsx(Panel, { padding: "xxlarge", children: _jsx(Title, { center: true, size: "xxlarge", children: title ?? name }) }), content && (_jsx(Section, { wide: true, children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), _jsx(Section, { wide: true, children: _jsx(TreeCards, { children: children }) })] }) }));
+}

package/ui/docs/DocumentationHomePage.md

@@ -0,0 +1,42 @@
+# DocumentationHomePage
+
+The landing page for a documentation site — a bold coloured hero panel with the package name, sitting above the listing of every module. Swap it in for the root element via [`TreeRouterMapping`](/ui/TreeRouter) so the home route (`/`) renders this instead of the generic [`TreePage`](/ui/TreePage).
+
+**Things to know:**
+
+- The whole page sits inside one `color="red"` [`Block`](/ui/Block), so the hero [`Panel`](/ui/Panel), prose, and child [`DocumentationCard`](/ui/DocumentationCard)s all inherit the red tint and re-derive together.
+- The hero is a `padding="xxlarge"` [`Panel`](/ui/Panel) with the package name centred as a large [`Title`](/ui/Title) (`center`, `size="xxlarge"`).
+- Below the hero it renders any absorbed README prose, then the root's children (the modules) as a stack of cards via [`TreeCards`](/ui/TreeCards).
+- It consumes the same [`TreeElementProps`](/util/tree) as [`TreePage`](/ui/TreePage), so it's a drop-in replacement for the `tree-element` renderer.
+
+## Usage
+
+Wire it in as the renderer for the root `tree-element` so the home route uses it:
+
+```tsx
+import { DocumentationHomePage, TreeApp, TreeRouterMapping } from "shelving/ui";
+
+<TreeRouterMapping mapping={{ "tree-element": DocumentationHomePage }}>
+  <TreeApp tree={tree} />
+</TreeRouterMapping>
+```
+
+Or render a single page manually by spreading the root element's props:
+
+```tsx
+import { DocumentationHomePage } from "shelving/ui";
+
+<DocumentationHomePage {...root.props} />
+```
+
+## Styling
+
+`DocumentationHomePage` has no own CSS hooks — it composes [`Page`](/ui/Page), [`Block`](/ui/Block), [`Panel`](/ui/Panel), [`Title`](/ui/Title), [`Section`](/ui/Section), and [`TreeCards`](/ui/TreeCards), which carry their own themeable surfaces. Retheme through those, or change the hero colour via the `color=` on the wrapping `Block`.
+
+## See also
+
+- [`TreePage`](/ui/TreePage) — the generic `tree-element` renderer this replaces for the home route.
+- [`DocumentationPage`](/ui/DocumentationPage) — the per-symbol detail page that uses the same coloured-panel hero pattern.
+- [`Panel`](/ui/Panel) — the full-width hero band, here with `padding="xxlarge"`.
+- [`TreeCards`](/ui/TreeCards) — the module card listing rendered below the hero.
+- [`TreeApp`](/ui/TreeApp) — wires renderers into a complete site.

package/ui/docs/DocumentationHomePage.test.tsx

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { DocumentationElement } from "../../util/tree.js";
+import { MetaContext } from "../misc/MetaContext.js";
+import { createMeta } from "../util/meta.js";
+import { DocumentationHomePage } from "./DocumentationHomePage.js";
+
+/** Make a minimal `kind: "module"` child element. */
+function mod(name: string): DocumentationElement {
+	return { type: "tree-documentation", key: name, props: { name, kind: "module" } };
+}
+
+/** Render inside a `MetaContext` — the child cards read the current URL from it. */
+function render(node: ReactNode, url = "./"): string {
+	return renderToStaticMarkup(<MetaContext value={createMeta({ root: "http://x.com/", url })}>{node}</MetaContext>);
+}
+
+describe("DocumentationHomePage", () => {
+	test("renders the title as a hero and lists the modules", () => {
+		const html = render(
+			<DocumentationHomePage name="shelving" title="shelving">
+				{[mod("util"), mod("schema")]}
+			</DocumentationHomePage>,
+		);
+		expect(html).toContain("shelving");
+		expect(html).toContain("util");
+		expect(html).toContain("schema");
+	});
+
+	test("falls back to `name` when no `title` is set", () => {
+		const html = render(<DocumentationHomePage name="shelving">{[mod("util")]}</DocumentationHomePage>);
+		expect(html).toContain("shelving");
+	});
+});

package/ui/docs/DocumentationHomePage.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+import type { TreeElementProps } from "../../util/tree.js";
+import { Block } from "../block/Block.js";
+import { Panel } from "../block/Panel.js";
+import { Prose } from "../block/Prose.js";
+import { Section } from "../block/Section.js";
+import { Title } from "../block/Title.js";
+import { Markup } from "../misc/Markup.js";
+import { Page } from "../page/Page.js";
+import { TreeCards } from "../tree/TreeCards.js";
+
+/**
+ * Page renderer for the documentation site's home page — a bold coloured hero panel over the module listing.
+ * - The whole page sits in a single `color="red"` `<Block>`, so the hero panel, prose, and child cards all pick up the red tint.
+ * - The hero is a full-padding `<Panel>` with the package name centred as a large `<Title>`.
+ * - Below the hero it renders any absorbed prose content, then the root's children (the modules) as a stack of cards.
+ *
+ * @kind component
+ * @param props The root tree element props (`title`, `name`, `description`, `content`, `children`).
+ * @returns A `<Page>` with a coloured hero panel followed by the module listing.
+ * @example <DocumentationHomePage {...root.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationHomePage/DocumentationHomePage
+ */
+export function DocumentationHomePage({ title, name, description, content, children }: TreeElementProps): ReactNode {
+	return (
+		<Page title={title ?? name} description={description}>
+			<Block color="red">
+				<Panel padding="xxlarge">
+					<Title center size="xxlarge">
+						{title ?? name}
+					</Title>
+				</Panel>
+				{content && (
+					<Section wide>
+						<Prose>
+							<Markup>{content}</Markup>
+						</Prose>
+					</Section>
+				)}
+				<Section wide>
+					<TreeCards>{children}</TreeCards>
+				</Section>
+			</Block>
+		</Page>
+	);
+}

package/ui/docs/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./DocumentationButtons.js";
 export * from "./DocumentationCard.js";
+export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationSignatures.js";

package/ui/docs/index.js

@@ -1,5 +1,6 @@
 export * from "./DocumentationButtons.js";
 export * from "./DocumentationCard.js";
+export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationSignatures.js";

package/ui/docs/index.ts

@@ -1,5 +1,6 @@
 export * from "./DocumentationButtons.js";
 export * from "./DocumentationCard.js";
+export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationSignatures.js";