@hackcove/ui 0.2.3 → 0.2.4

package/README.md

@@ -40,11 +40,13 @@ export const Example = () => (
 ## What is exported
 
 - Primitives: `Card`, `EpicHeader`, `Empty`, `PageTitle` (deprecated: use `PageHeader`), `Pill`, `groupByEpic`, `Markdown`.
-- Layout (see Layout): `AppShell`, `appShellRootClass`, `Container`, `PageHeader`, `Stack`, `Section`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
+- Layout (see Layout): `AppShell`, `appShellRootClass`, `Container`, `PageHeader`, `Stack`, `Section`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
 - Typography roles (each pins size + weight, takes a `color` and an `as`): `Display`, `Lead`,
   `PageHeading`, `SectionHeading`, `SubsectionHeading`, `ModalHeading`, `Subtitle`, `Overline`,
-  `Body`, `BodyStrong`, `Caption`.
-- Controls: `Button`, `buttonClass` (the classes of a `Button`, for a router's own `<Link>`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`), `ColourSchemeToggle` (a light/dark switch on `<html>`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Checkbox` (a native checkbox with its label; `className` goes on the label, other props on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body). `NavTabs` (a row of pill links in a `<nav>`; `items` are `{ label, href, active? }`, `label` names the landmark, the active one is filled and gets `aria-current="page"`). `navTabClass` (the classes of one tab, for a router's own `<Link>`). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, the last is the current page and gets `aria-current="page"`, and each crumb truncates). `crumbLinkClass` (the classes of a crumb that links, for a router's own `<Link>`). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; `size` is `sm`, `md` (default) or `lg`; `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `ToggleChip` (an on/off filter pill; `pressed` sets `aria-pressed` and the filled look, `dot` adds a leading colour dot, and the caller toggles it in `onClick`). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `ToggleChip`s; `className` goes on the fieldset). `DatePicker` and `DateField` (see Dates).
+  `Body`, `BodyStrong`, `Caption`. Three opt-in props, none changing today's look: `SectionHeading rule`
+  (a hairline under it, with its spacing), `SubsectionHeading size` (`sm` default, `base` bold, `lg`),
+  `Body preserveNewlines` (keeps a note's line breaks).
+- Controls: `Button`, `buttonClass` (the classes of a `Button`, for a router's own `<Link>`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`), `ColourSchemeToggle` (a light/dark switch on `<html>`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Checkbox` (a native checkbox with its label; `className` goes on the label, other props on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body). `NavTabs` (a row of pill links in a `<nav>`; `items` are `{ label, href, active? }`, `label` names the landmark, the active one is filled and gets `aria-current="page"`). `navTabClass` (the classes of one tab, for a router's own `<Link>`). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, the last is the current page and gets `aria-current="page"`, and each crumb truncates). `crumbLinkClass` (the classes of a crumb that links, for a router's own `<Link>`). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; with `src` (the app's own local image path, never a remote one) it is a round, cropped `<img alt={name}>` instead; `size` is `sm`, `md` (default), `lg`, `xl` (56px) or `2xl` (96px); `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `TextLink` (an inline text link in the accent colour; `href` is required, `external` adds `target="_blank"` and `rel="noreferrer"`, `className` and every other anchor prop pass through). `linkClass` (the classes of one, for a router's own `<Link>`). `InlineLinks` (a wrapping row of small links joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; `className` goes on the row). `Divider` (a hairline `<hr>` in the theme's line colour; spacing is the caller's, on `className`). `BulletList` (a `<ul>` with discs, an indent and a small gap; children are `<li>`s). `Code` (inline code: mono, on a subtle background). `Video` (a full-width, rounded `<video>` with controls that loads metadata only; `src` is required, `poster` and a WebVTT `captions` track are optional, children are the fallback). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `ToggleChip` (an on/off filter pill; `pressed` sets `aria-pressed` and the filled look, `dot` adds a leading colour dot, and the caller toggles it in `onClick`). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `ToggleChip`s; `className` goes on the fieldset). `DatePicker` and `DateField` (see Dates).
 - Dates: `toISODate`, `fromISODate`, and the `CalendarDate` type.
 
 ## Dates
@@ -95,7 +97,7 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
 // short page and a long one centre their content at the same x. AppShell cannot set it itself.
 <html className={appShellRootClass}>
   <body>
-    <AppShell header={<><Logo /><NavTabs label="Main" items={nav} /></>} footer="…">
+    <AppShell brand={<Logo />} nav={<NavTabs label="Main" items={nav} />} footer="…">
       <PageHeader title="Builds" subtitle="Every build" actions={<Button>New</Button>} />
       <Stack>
         <Section title="Recent">…</Section>
@@ -106,8 +108,13 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
 ```
 
 - **`AppShell`** is the page frame: a sticky header that is always one `h-14` row (a nav that does
-  not fit scrolls sideways, it never wraps), an optional `subnav` second row (same rule), `main`
-  with fixed `py-8`, and an optional `footer`. `bleed` drops main's `Container` for a full-bleed
+  not fit scrolls sideways, it never wraps, and the edge with more to scroll to fades out until it
+  is reached), an optional `subnav` second row (same rule), `main`
+  with fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
+  `brand` (logo and name, at the brand type with the logo gap), `nav` (a `NavTabs`), `header` (a
+  free node, the escape hatch) and `controls` (end-aligned, `gap-2`, centred): no wrapper, no
+  `className`. `hideChromeInPrint` is opt-in: the header and footer are hidden in print and main
+  drops its padding (the page margin is then your `@page`); without it a print is unchanged. `bleed` drops main's `Container` for a full-bleed
   page; the header keeps its own, so put a `Container` back around anything that should line up.
 - **`Container`** is the only place the content width (`max-w-6xl`) and side padding
   (`px-4 sm:px-6`) are defined. **Pages never set their own width or outer padding**: no `max-w-*`,
@@ -115,10 +122,13 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
 - **`PageHeader`** is the top of every page: optional `breadcrumbs`, the `title` (a `PageHeading`),
   `subtitle`, `actions` (right of the title from `sm`, under it on a phone) and `tabs` under it. Its
   fixed bottom margin puts every page's first block at the same y.
-- **`Stack`** spaces blocks in a column: `gap="sm"` (`gap-4`) inside a group, `md` (`gap-6`, the
-  default) between blocks, `lg` (`gap-8`) between groups. Use it instead of `space-y-*`.
-  **`Section`** is a `<section>` Stack (`sm` by default) with an optional `SectionHeading` `title`
-  and `actions` beside it.
+- **`Stack`** spaces blocks in a column: `gap="xs"` (`gap-2`) between lines of one text block (a
+  heading, the line under it), `sm` (`gap-4`) inside a group, `md` (`gap-6`, the default) between
+  blocks, `lg` (`gap-8`) between groups. Use it instead of `space-y-*`. `width` caps the column:
+  `narrow` (`max-w-3xl`, a reading measure), `wide` (`max-w-5xl`), `full` (`w-full`) or `default`
+  (nothing). A capped Stack starts at the Container's left edge and is never re-centred.
+  **`Section`** is a `<section>` Stack (`sm` by default) with an optional `SectionHeading` `title`,
+  `actions` beside it and the same `width`.
 
 ### Page layouts
 
@@ -133,6 +143,11 @@ except the last four.
 - **`FormLayout`**: use this for a create or edit page. A `max-w-3xl` `<form>` that starts at the
   Container's left edge (it is not re-centred, so the title does not jump), with an `actions` row at
   the end. Other props (`onSubmit`, `action`) go on the `<form>`.
+- **`ProseLayout`**: use this for a text page (privacy, terms, a CV, an about page). One `narrow`
+  (`max-w-3xl`) column that starts at the Container's left edge (not re-centred, so the title does
+  not jump): the header, then `children` in a `Stack` (`gap` prop, `md` by default). Unlike
+  `FormLayout` the header sits inside the column, so its `actions` stay beside the text.
+  `className` goes on the column.
 - **`CardGrid`**: use this for stat tiles or a gallery of cards. `columns` is `2`, `3` (default) or
   `4`: one column on a phone, two from `sm`, `columns` from `lg`.
 - **`SidebarLayout`**: use this when a `rail` of navigation sits beside the content. Render it in
@@ -142,6 +157,18 @@ except the last four.
 - **`FullBleedLayout`**: use this for a viewer that needs the whole width. Render it in
   `<AppShell bleed>`; `children` fill the width, and an optional `panel` takes `lg:w-72` on the
   right and stacks below under `lg`.
+
+  **`SidebarLayout` and `FullBleedLayout` deliberately break the shared left edge from `md` and
+  `lg` up.** A full-height rail and an edge-to-edge viewer need the viewport's edges, so they cannot
+  sit inside the Container the header uses. At 1280 px the header logo and every other layout start
+  at x=88, `SidebarLayout`'s rail at x=0 and its canvas at x=264 (rail 240 + the Container's 24
+  padding), `FullBleedLayout`'s `children` at x=0 (they add their own padding). Below `md` (`lg` for
+  `FullBleedLayout`) everything stacks and all layouts agree at the Container's padding. To avoid
+  the shift between pages, give a whole section of an app the same layout (every page under a
+  project on `SidebarLayout`) rather than mixing it with `ListLayout` pages that a user moves
+  between; the header, which stays inside the Container, is the constant. The title's y also
+  differs from `ListLayout` only when one page passes `breadcrumbs` and the other does not:
+  `PageHeader` puts them above the title in every layout.
 - **`CenteredLayout`**: use this for sign-in, landing, not-found and error pages. A `max-w-md` card
   centred at a fixed offset from the top; the one layout that does not share the left edge.
 

package/dist/AppShell.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 /**
  * The class an app puts on its own `<html>`: it always reserves the scrollbar, so centred content
  * does not shift between a short page and a long one. AppShell never touches `<html>` itself.
@@ -9,14 +9,29 @@ export declare const appShellRootClass = "overflow-y-scroll";
  * optional footer. Header, main and footer each sit in a `Container`, so pages never set their own
  * width or padding. `bleed` drops main's Container (the header keeps its own). Main is a flex
  * column, so a full-height child (`SidebarLayout`) is `flex-1 min-h-0` and needs no header height.
+ *
+ * The header row is laid out by its slots, left to right: `brand`, `nav`, then `header` (anything
+ * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
+ * `className` for any of them.
  */
-export declare function AppShell({ header, subnav, footer, bleed, children, }: {
-    /** The header row: logo, nav, controls. Always one `h-14` row. */
-    header: ReactNode;
+export declare function AppShell({ brand, nav, controls, header, subnav, footer, bleed, hideChromeInPrint, children, }: {
+    /** The brand: a logo and a name, in the header's brand type, with the gap between them. */
+    brand?: ReactNode;
+    /** The main navigation, e.g. `NavTabs` (it is already a `<nav>`). */
+    nav?: ReactNode;
+    /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred. */
+    controls?: ReactNode;
+    /** The escape hatch: a free node in the header row, after `brand` and `nav`. */
+    header?: ReactNode;
     /** A second fixed-height row under the header, e.g. `NavTabs`. */
     subnav?: ReactNode;
     footer?: ReactNode;
     /** Main without a Container, for a full-bleed layout. */
     bleed?: boolean;
+    /**
+     * Print only the page: the header and footer are hidden, and main's Container drops its padding
+     * (the page margin is then `@page`'s). Off by default, so a print is unchanged unless an app asks.
+     */
+    hideChromeInPrint?: boolean;
     children: ReactNode;
 }): ReactElement;

package/dist/AppShell.js

@@ -1,4 +1,5 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
 import { Container } from "./Container.js";
 import { cx } from "./cx.js";
 /**
@@ -8,12 +9,53 @@ import { cx } from "./cx.js";
 export const appShellRootClass = "overflow-y-scroll";
 // One fixed-height row that scrolls sideways and never wraps; its children keep their width.
 const ROW = "flex items-center gap-4 overflow-x-auto whitespace-nowrap *:shrink-0";
+// While a row has more to scroll to on a side, that edge fades out (a mask, so it follows any theme).
+// `ScrollRow` sets `data-more-start` / `data-more-end` (and `data-more` for either); a row that fits
+// has none and is untouched.
+const FADE = "data-more-start:[--fade-start:2rem] data-more-end:[--fade-end:2rem] data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
+/** A row in a Container, with the fade on whichever side still has content to scroll to. */
+function ScrollRow({ className, children }) {
+    const row = useRef(null);
+    // Every render: the children may have changed, and each needs observing.
+    useEffect(() => {
+        const el = row.current;
+        if (!el)
+            return undefined;
+        const update = () => {
+            const start = el.scrollLeft > 1;
+            const end = el.scrollWidth - el.clientWidth - el.scrollLeft > 1;
+            el.toggleAttribute("data-more-start", start);
+            el.toggleAttribute("data-more-end", end);
+            el.toggleAttribute("data-more", start || end);
+        };
+        update();
+        el.addEventListener("scroll", update, { passive: true });
+        // jsdom (a consumer's own tests) has no ResizeObserver.
+        const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(update);
+        resize?.observe(el);
+        for (const child of el.children)
+            resize?.observe(child);
+        return () => {
+            el.removeEventListener("scroll", update);
+            resize?.disconnect();
+        };
+    });
+    return (_jsx(Container, { elementRef: (el) => void (row.current = el), className: cx(ROW, FADE, className), children: children }));
+}
+/** The header row's slots in order: brand, nav, the free `children`, then controls at the end. */
+function HeaderSlots({ brand, nav, controls, children, }) {
+    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && _jsx("div", { className: "ml-auto flex items-center gap-2", children: controls })] }));
+}
 /**
  * The page frame: a sticky one-row header, an optional second `subnav` row, the main area and an
  * optional footer. Header, main and footer each sit in a `Container`, so pages never set their own
  * width or padding. `bleed` drops main's Container (the header keeps its own). Main is a flex
  * column, so a full-height child (`SidebarLayout`) is `flex-1 min-h-0` and needs no header height.
+ *
+ * The header row is laid out by its slots, left to right: `brand`, `nav`, then `header` (anything
+ * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
+ * `className` for any of them.
  */
-export function AppShell({ header, subnav, footer, bleed = false, children, }) {
-    return (_jsxs("div", { className: "flex min-h-dvh flex-col", children: [_jsxs("header", { className: "sticky top-0 z-10 border-b border-slate-200 bg-white", children: [_jsx(Container, { className: cx(ROW, "h-14"), children: header }), subnav && _jsx(Container, { className: cx(ROW, "h-12"), children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? children : _jsx(Container, { className: "py-8", children: children }) }), footer && (_jsx("footer", { className: "border-t border-slate-200", children: _jsx(Container, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
+export function AppShell({ brand, nav, controls, header, subnav, footer, bleed = false, hideChromeInPrint = false, children, }) {
+    return (_jsxs("div", { className: "flex min-h-dvh flex-col", children: [_jsxs("header", { className: cx("sticky top-0 z-10 border-b border-slate-200 bg-white", hideChromeInPrint && "print:hidden"), children: [_jsx(ScrollRow, { className: "h-14", children: _jsx(HeaderSlots, { brand: brand, nav: nav, controls: controls, children: header }) }), subnav && _jsx(ScrollRow, { className: "h-12", children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? (children) : (_jsx(Container, { className: cx("py-8", hideChromeInPrint && "print:p-0"), children: children })) }), footer && (_jsx("footer", { className: cx("border-t border-slate-200", hideChromeInPrint && "print:hidden"), children: _jsx(Container, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
 }

package/dist/Avatar.d.ts

@@ -3,6 +3,8 @@ declare const SIZE_CLASSES: {
     readonly sm: "size-6 text-xs";
     readonly md: "size-7 text-xs";
     readonly lg: "size-10 text-base";
+    readonly xl: "size-14 text-xl";
+    readonly "2xl": "size-24 text-3xl";
 };
 export type AvatarSize = keyof typeof SIZE_CLASSES;
 /** The background class for a name: the same name gets the same colour everywhere. */
@@ -10,13 +12,16 @@ export declare function avatarColourClass(name: string): string;
 /** Up to two letters or digits of a name, upper-cased; `?` when it has none. */
 export declare function initialsOf(name: string): string;
 /**
- * A person as a round badge of initials. It never loads a remote image: that is a request to
- * another server for decoration, and it makes a screenshot depend on the network.
+ * A person as a round badge of initials, or as their photo when `src` is given. It never loads a
+ * remote image on its own: that is a request to another server for decoration, and it makes a
+ * screenshot depend on the network. `src` is the app's own local path.
  */
-export declare function Avatar({ name, size, ring, className, ...rest }: {
+export declare function Avatar({ name, src, size, ring, className, ...rest }: {
     name: string;
+    /** The person's photo, a local path. It replaces the initials and is announced as `name`. */
+    src?: string;
     size?: AvatarSize;
     /** A ring in the page colour, for a stack of overlapping avatars. */
     ring?: boolean;
-} & Omit<HTMLAttributes<HTMLSpanElement>, "children">): ReactElement;
+} & Omit<HTMLAttributes<HTMLElement>, "children">): ReactElement;
 export {};

package/dist/Avatar.js

@@ -14,6 +14,8 @@ const SIZE_CLASSES = {
     sm: "size-6 text-xs",
     md: "size-7 text-xs",
     lg: "size-10 text-base",
+    xl: "size-14 text-xl",
+    "2xl": "size-24 text-3xl",
 };
 /** The background class for a name: the same name gets the same colour everywhere. */
 export function avatarColourClass(name) {
@@ -30,9 +32,13 @@ export function initialsOf(name) {
         .toUpperCase() || "?");
 }
 /**
- * A person as a round badge of initials. It never loads a remote image: that is a request to
- * another server for decoration, and it makes a screenshot depend on the network.
+ * A person as a round badge of initials, or as their photo when `src` is given. It never loads a
+ * remote image on its own: that is a request to another server for decoration, and it makes a
+ * screenshot depend on the network. `src` is the app's own local path.
  */
-export function Avatar({ name, size = "md", ring = false, className, ...rest }) {
+export function Avatar({ name, src, size = "md", ring = false, className, ...rest }) {
+    if (src) {
+        return (_jsx("img", { src: src, alt: name, title: name, className: cx("shrink-0 rounded-full object-cover", SIZE_CLASSES[size], ring && "-ml-1.5 border-2 border-slate-50 first:ml-0", className), ...rest }));
+    }
     return (_jsx("span", { "aria-hidden": "true", title: name, className: cx("inline-grid shrink-0 place-items-center rounded-full font-semibold text-violet-50", SIZE_CLASSES[size], avatarColourClass(name), ring && "-ml-1.5 border-2 border-slate-50 first:ml-0", className), ...rest, children: initialsOf(name) }));
 }

package/dist/BulletList.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes, ReactElement } from "react";
+/** A bulleted `<ul>`: discs, indented, a small gap between items. Its children are `<li>`s (e.g. `Body as="li"`). */
+export declare function BulletList({ className, ...rest }: HTMLAttributes<HTMLUListElement>): ReactElement;

package/dist/BulletList.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/** A bulleted `<ul>`: discs, indented, a small gap between items. Its children are `<li>`s (e.g. `Body as="li"`). */
+export function BulletList({ className, ...rest }) {
+    return _jsx("ul", { className: cx("list-disc space-y-1 pl-5", className), ...rest });
+}

package/dist/Code.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes, ReactElement } from "react";
+/** Inline code: mono, on a subtle inset background. It takes the surrounding text colour and size (a touch smaller, for the mono face). */
+export declare function Code({ className, ...rest }: HTMLAttributes<HTMLElement>): ReactElement;

package/dist/Code.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/** Inline code: mono, on a subtle inset background. It takes the surrounding text colour and size (a touch smaller, for the mono face). */
+export function Code({ className, ...rest }) {
+    return (_jsx("code", { className: cx("rounded bg-slate-100 px-1 py-0.5 font-mono text-[0.9em]", className), ...rest }));
+}

package/dist/Container.d.ts

@@ -3,8 +3,10 @@ import type { ReactElement, ReactNode } from "react";
  * The one content edge: every page's width and side padding. This file is the only place they are
  * defined, so a header, a page and a footer inside a Container start at the same x.
  */
-export declare function Container({ as: Tag, className, children, }: {
+export declare function Container({ as: Tag, className, elementRef, children, }: {
     as?: "div" | "main" | "header" | "footer" | "section" | "nav";
     className?: string;
+    /** The rendered element, for a parent that measures or scrolls it. */
+    elementRef?: (element: HTMLElement | null) => void;
     children?: ReactNode;
 }): ReactElement;

package/dist/Container.js

@@ -4,6 +4,6 @@ import { cx } from "./cx.js";
  * The one content edge: every page's width and side padding. This file is the only place they are
  * defined, so a header, a page and a footer inside a Container start at the same x.
  */
-export function Container({ as: Tag = "div", className, children, }) {
-    return _jsx(Tag, { className: cx("mx-auto w-full max-w-6xl px-4 sm:px-6", className), children: children });
+export function Container({ as: Tag = "div", className, elementRef, children, }) {
+    return (_jsx(Tag, { ref: elementRef, className: cx("mx-auto w-full max-w-6xl px-4 sm:px-6", className), children: children }));
 }

package/dist/Divider.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes, ReactElement } from "react";
+/** A hairline rule in the theme's line colour: between a heading and its content, or above a footer. Spacing is the caller's, on `className`. */
+export declare function Divider({ className, ...rest }: Omit<HTMLAttributes<HTMLHRElement>, "children">): ReactElement;

package/dist/Divider.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/** A hairline rule in the theme's line colour: between a heading and its content, or above a footer. Spacing is the caller's, on `className`. */
+export function Divider({ className, ...rest }) {
+    return _jsx("hr", { className: cx("border-t border-slate-200/70", className), ...rest });
+}

package/dist/InlineLinks.d.ts

@@ -0,0 +1,11 @@
+import { type ReactElement, type ReactNode } from "react";
+export type InlineLinksSeparator = "·" | "•" | "none";
+/**
+ * A wrapping row of links, small text, joined by a separator. The separator is `aria-hidden` and
+ * leads each link but the first, held to its link so a wrap never leaves one at a line's end.
+ */
+export declare function InlineLinks({ separator, className, children, }: {
+    separator?: InlineLinksSeparator;
+    className?: string;
+    children: ReactNode;
+}): ReactElement;

package/dist/InlineLinks.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children } from "react";
+import { cx } from "./cx.js";
+import { Caption } from "./typography.js";
+/**
+ * A wrapping row of links, small text, joined by a separator. The separator is `aria-hidden` and
+ * leads each link but the first, held to its link so a wrap never leaves one at a line's end.
+ */
+export function InlineLinks({ separator = "·", className, children, }) {
+    return (_jsx("div", { className: cx("flex flex-wrap items-center gap-x-3 gap-y-1 text-sm", className), children: Children.toArray(children).map((child, index) => (_jsxs("span", { className: "inline-flex items-center gap-x-3 whitespace-nowrap", children: [index > 0 && separator !== "none" && _jsx(Caption, { "aria-hidden": "true", children: separator }), child] }, index))) }));
+}

package/dist/Markdown.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// A minimal, SAFE markdown renderer for the standup (headings / bullets / bold). No
+// A minimal, SAFE markdown renderer (headings / bullets / bold). No
 // dangerouslySetInnerHTML — text is rendered as React nodes, so it can't inject HTML.
 function inline(text) {
     return text.split(/(\*\*[^*]+\*\*)/g).map((p, i) => p.startsWith("**") && p.endsWith("**") ? (_jsx("strong", { className: "font-semibold text-slate-900", children: p.slice(2, -2) }, i)) : (_jsx("span", { children: p }, i)));

package/dist/PageLayouts.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 import { type PageHeaderProps } from "./PageHeader.js";
+import { type StackGap } from "./Stack.js";
 /** A list page: header, an optional `filters` slot, then the list, or `empty` when `isEmpty`. */
 export declare function ListLayout({ filters, empty, isEmpty, children, ...header }: PageHeaderProps & {
     filters?: ReactNode;
@@ -18,6 +19,17 @@ export declare function FormLayout({ actions, children, breadcrumbs, title, subt
     actions?: ReactNode;
     children: ReactNode;
 } & Omit<ComponentPropsWithoutRef<"form">, "title">): ReactElement;
+/**
+ * A text page: header, then `children` stacked `gap` apart (`md` by default), all in one `narrow`
+ * (`max-w-3xl`) reading column that starts at the Container's left edge (it is not re-centred, so
+ * the title does not jump). Unlike `FormLayout` the header sits inside the column, so its `actions`
+ * stay beside the text instead of at the Container's far edge. `className` goes on the column.
+ */
+export declare function ProseLayout({ gap, className, children, ...header }: PageHeaderProps & {
+    gap?: StackGap | undefined;
+    className?: string;
+    children?: ReactNode;
+}): ReactElement;
 declare const COLUMNS: {
     readonly 2: "lg:grid-cols-2";
     readonly 3: "lg:grid-cols-3";
@@ -33,12 +45,21 @@ export declare function CardGrid({ columns, className, children, }: {
  * A full-height `rail` beside the `children` canvas. Render it in `<AppShell bleed>`: it fills what
  * the shell's flex column leaves under the header, so no header height is written down. The rail is
  * `md:w-60` and stacks above the canvas below `md`; the canvas keeps the Container's padding.
+ *
+ * It deliberately breaks the shared left edge from `md` up: a full-height rail needs the viewport's
+ * left edge, so the rail starts at x=0 and the canvas at the rail's width plus the Container's
+ * padding (264 at 1280), not at the header logo's x. Below `md` every layout agrees.
  */
 export declare function SidebarLayout({ rail, children, }: {
     rail: ReactNode;
     children: ReactNode;
 }): ReactElement;
-/** Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller screen. Render it in `<AppShell bleed>`. */
+/**
+ * Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller
+ * screen. Render it in `<AppShell bleed>`. It deliberately breaks the shared left edge: a viewer
+ * that needs the whole width has no Container of its own, so `children` start at the viewport's
+ * left edge and add their own padding.
+ */
 export declare function FullBleedLayout({ panel, children, }: {
     panel?: ReactNode;
     children: ReactNode;

package/dist/PageLayouts.js

@@ -3,7 +3,7 @@ import { Card } from "./ui.js";
 import { Container } from "./Container.js";
 import { cx } from "./cx.js";
 import { PageHeader, PageHeaderContent } from "./PageHeader.js";
-import { Stack } from "./Stack.js";
+import { STACK_WIDTH, Stack } from "./Stack.js";
 // Compositions of the layout foundation. None sets a page width or outer padding of its own; the
 // ones that narrow their content do it inside the Container they are rendered in.
 /** A list page: header, an optional `filters` slot, then the list, or `empty` when `isEmpty`. */
@@ -18,6 +18,15 @@ export function DetailLayout({ aside, children, ...header }) {
 export function FormLayout({ actions, children, breadcrumbs, title, subtitle, tabs, className, ...form }) {
     return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, tabs: tabs }), _jsx("form", { className: cx("max-w-3xl", className), ...form, children: _jsxs(Stack, { children: [children, actions && _jsx("div", { className: "flex flex-wrap items-center gap-2", children: actions })] }) })] }));
 }
+/**
+ * A text page: header, then `children` stacked `gap` apart (`md` by default), all in one `narrow`
+ * (`max-w-3xl`) reading column that starts at the Container's left edge (it is not re-centred, so
+ * the title does not jump). Unlike `FormLayout` the header sits inside the column, so its `actions`
+ * stay beside the text instead of at the Container's far edge. `className` goes on the column.
+ */
+export function ProseLayout({ gap, className, children, ...header }) {
+    return (_jsxs("div", { className: cx(STACK_WIDTH.narrow, className), children: [_jsx(PageHeader, { ...header }), _jsx(Stack, { gap: gap, children: children })] }));
+}
 const COLUMNS = {
     2: "lg:grid-cols-2",
     3: "lg:grid-cols-3",
@@ -31,11 +40,20 @@ export function CardGrid({ columns = 3, className, children, }) {
  * A full-height `rail` beside the `children` canvas. Render it in `<AppShell bleed>`: it fills what
  * the shell's flex column leaves under the header, so no header height is written down. The rail is
  * `md:w-60` and stacks above the canvas below `md`; the canvas keeps the Container's padding.
+ *
+ * It deliberately breaks the shared left edge from `md` up: a full-height rail needs the viewport's
+ * left edge, so the rail starts at x=0 and the canvas at the rail's width plus the Container's
+ * padding (264 at 1280), not at the header logo's x. Below `md` every layout agrees.
  */
 export function SidebarLayout({ rail, children, }) {
     return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col md:flex-row", children: [_jsx("aside", { className: "w-full shrink-0 border-b border-slate-200 bg-slate-50 p-4 md:w-60 md:border-r md:border-b-0", children: rail }), _jsx("div", { className: "min-w-0 flex-1", children: _jsx(Container, { className: "py-8", children: children }) })] }));
 }
-/** Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller screen. Render it in `<AppShell bleed>`. */
+/**
+ * Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller
+ * screen. Render it in `<AppShell bleed>`. It deliberately breaks the shared left edge: a viewer
+ * that needs the whole width has no Container of its own, so `children` start at the viewport's
+ * left edge and add their own padding.
+ */
 export function FullBleedLayout({ panel, children, }) {
     return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col lg:flex-row", children: [_jsx("div", { className: "min-w-0 flex-1", children: children }), panel && (_jsx("aside", { className: "w-full shrink-0 border-t border-slate-200 bg-slate-50 p-4 lg:w-72 lg:border-t-0 lg:border-l", children: panel }))] }));
 }

package/dist/Stack.d.ts

@@ -1,18 +1,30 @@
 import { type ReactElement, type ReactNode } from "react";
-export type StackGap = "sm" | "md" | "lg";
-/** A vertical column of blocks a fixed `gap` apart: `sm` inside a group, `md` (default) between blocks, `lg` between groups. */
-export declare function Stack({ gap, as: Tag, className, children, ...rest }: {
-    gap?: StackGap;
+export type StackGap = "xs" | "sm" | "md" | "lg";
+export type StackWidth = "narrow" | "default" | "wide" | "full";
+/** `default` adds nothing: the Stack is as wide as its parent. */
+export declare const STACK_WIDTH: Record<StackWidth, string | undefined>;
+/**
+ * A vertical column of blocks a fixed `gap` apart: `xs` between lines of text (a heading and the
+ * line under it), `sm` inside a group, `md` (default) between blocks, `lg` between groups.
+ *
+ * `width` caps the column: `narrow` is a reading measure (`max-w-3xl`), `wide` is `max-w-5xl`, `full`
+ * is the parent's whole width and `default` sets nothing. A capped Stack starts at its parent's left
+ * edge (it is never re-centred), so its first line lines up with every other block on the page.
+ */
+export declare function Stack({ gap, width, as: Tag, className, children, ...rest }: {
+    gap?: StackGap | undefined;
+    width?: StackWidth | undefined;
     as?: "div" | "section";
     className?: string | undefined;
     children?: ReactNode;
     "aria-labelledby"?: string | undefined;
 }): ReactElement;
 /** A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside it. */
-export declare function Section({ title, actions, gap, className, children, }: {
+export declare function Section({ title, actions, gap, width, className, children, }: {
     title?: ReactNode;
     actions?: ReactNode;
-    gap?: StackGap;
+    gap?: StackGap | undefined;
+    width?: StackWidth | undefined;
     className?: string;
     children?: ReactNode;
 }): ReactElement;

package/dist/Stack.js

@@ -2,13 +2,27 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 import { cx } from "./cx.js";
 import { SectionHeading } from "./typography.js";
-const GAP = { sm: "gap-4", md: "gap-6", lg: "gap-8" };
-/** A vertical column of blocks a fixed `gap` apart: `sm` inside a group, `md` (default) between blocks, `lg` between groups. */
-export function Stack({ gap = "md", as: Tag = "div", className, children, ...rest }) {
-    return (_jsx(Tag, { className: cx("flex flex-col", GAP[gap], className), ...rest, children: children }));
+const GAP = { xs: "gap-2", sm: "gap-4", md: "gap-6", lg: "gap-8" };
+/** `default` adds nothing: the Stack is as wide as its parent. */
+export const STACK_WIDTH = {
+    narrow: "max-w-3xl",
+    default: undefined,
+    wide: "max-w-5xl",
+    full: "w-full",
+};
+/**
+ * A vertical column of blocks a fixed `gap` apart: `xs` between lines of text (a heading and the
+ * line under it), `sm` inside a group, `md` (default) between blocks, `lg` between groups.
+ *
+ * `width` caps the column: `narrow` is a reading measure (`max-w-3xl`), `wide` is `max-w-5xl`, `full`
+ * is the parent's whole width and `default` sets nothing. A capped Stack starts at its parent's left
+ * edge (it is never re-centred), so its first line lines up with every other block on the page.
+ */
+export function Stack({ gap = "md", width = "default", as: Tag = "div", className, children, ...rest }) {
+    return (_jsx(Tag, { className: cx("flex flex-col", GAP[gap], STACK_WIDTH[width], className), ...rest, children: children }));
 }
 /** A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside it. */
-export function Section({ title, actions, gap = "sm", className, children, }) {
+export function Section({ title, actions, gap = "sm", width, className, children, }) {
     const titleId = useId();
-    return (_jsxs(Stack, { as: "section", gap: gap, className: className, "aria-labelledby": title ? titleId : undefined, children: [(title || actions) && (_jsxs("div", { className: "flex items-center justify-between gap-4", children: [title && _jsx(SectionHeading, { id: titleId, children: title }), actions && _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] })), children] }));
+    return (_jsxs(Stack, { as: "section", gap: gap, width: width, className: className, "aria-labelledby": title ? titleId : undefined, children: [(title || actions) && (_jsxs("div", { className: "flex items-center justify-between gap-4", children: [title && _jsx(SectionHeading, { id: titleId, children: title }), actions && _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] })), children] }));
 }

package/dist/TextLink.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentPropsWithoutRef, ReactElement } from "react";
+/** The classes of an inline text link, for a router's own <Link> that should look like one. */
+export declare const linkClass: string;
+type TextLinkProps = {
+    /** Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`. */
+    external?: boolean | undefined;
+} & ComponentPropsWithoutRef<"a"> & {
+    href: string;
+};
+/** An inline text link in the accent colour. Every anchor prop goes on the `<a>`. */
+export declare function TextLink({ external, className, children, ...rest }: TextLinkProps): ReactElement;
+export {};

package/dist/TextLink.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx, focusRing } from "./cx.js";
+/** The classes of an inline text link, for a router's own <Link> that should look like one. */
+export const linkClass = cx("rounded font-medium text-violet-600 underline-offset-2 transition-colors hover:text-violet-700", focusRing);
+/** An inline text link in the accent colour. Every anchor prop goes on the `<a>`. */
+export function TextLink({ external = false, className, children, ...rest }) {
+    return (_jsx("a", { className: cx(linkClass, className), ...(external ? { target: "_blank", rel: "noreferrer" } : {}), ...rest, children: children }));
+}

package/dist/Video.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement, VideoHTMLAttributes } from "react";
+/**
+ * A `<video>` with controls, full width and rounded; it loads metadata only, so the page does not
+ * pull the file until it is played. `src` is the app's own video; `captions` is a WebVTT file,
+ * offered as the default track. `children` is the fallback for a browser that cannot play it.
+ */
+export declare function Video({ src, captions, className, children, ...rest }: {
+    src: string;
+    captions?: string | undefined;
+} & Omit<VideoHTMLAttributes<HTMLVideoElement>, "src" | "controls">): ReactElement;

package/dist/Video.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/**
+ * A `<video>` with controls, full width and rounded; it loads metadata only, so the page does not
+ * pull the file until it is played. `src` is the app's own video; `captions` is a WebVTT file,
+ * offered as the default track. `children` is the fallback for a browser that cannot play it.
+ */
+export function Video({ src, captions, className, children, ...rest }) {
+    return (_jsxs("video", { controls: true, preload: "metadata", src: src, className: cx("w-full rounded-lg", className), ...rest, children: [captions && _jsx("track", { kind: "captions", src: captions, default: true }), children] }));
+}

package/dist/index.d.ts

@@ -3,12 +3,15 @@ export { Markdown } from "./Markdown.js";
 export { AppShell, appShellRootClass } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader, type PageHeaderProps } from "./PageHeader.js";
-export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, SidebarLayout, } from "./PageLayouts.js";
-export { Section, Stack, type StackGap } from "./Stack.js";
+export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";
+export { Section, Stack, type StackGap, type StackWidth } from "./Stack.js";
 export { Button, buttonClass, type ButtonVariant } from "./Button.js";
 export { Avatar, avatarColourClass, initialsOf, type AvatarSize } from "./Avatar.js";
 export { Breadcrumbs, crumbLinkClass } from "./Breadcrumbs.js";
+export { BulletList } from "./BulletList.js";
 export { Callout, type CalloutTone } from "./Callout.js";
+export { Code } from "./Code.js";
+export { Divider } from "./Divider.js";
 export { Dialog, type DialogProps } from "./Dialog.js";
 export { IconButton } from "./IconButton.js";
 export { ColourSchemeToggle } from "./ColourSchemeToggle.js";
@@ -22,11 +25,14 @@ export { CopyLine } from "./CopyLine.js";
 export { Field } from "./Field.js";
 export { FieldDialog, type FieldDialogProps } from "./FieldDialog.js";
 export { Input } from "./Input.js";
+export { InlineLinks, type InlineLinksSeparator } from "./InlineLinks.js";
 export { Kbd } from "./Kbd.js";
 export { KeyValue, KeyValueList } from "./KeyValueList.js";
 export { Select } from "./Select.js";
 export { Textarea } from "./Textarea.js";
-export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, Subtitle, type TypographyColor, type TypographyProps, } from "./typography.js";
+export { Video } from "./Video.js";
+export { linkClass, TextLink } from "./TextLink.js";
+export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, type SubsectionHeadingSize, Subtitle, type TypographyColor, type TypographyProps, } from "./typography.js";
 export { DateField, type DateFieldProps } from "./DateField.js";
 export { DatePicker, type DatePickerProps } from "./DatePicker.js";
 export { fromISODate, toISODate } from "./isoDate.js";

package/dist/index.js

@@ -3,12 +3,15 @@ export { Markdown } from "./Markdown.js";
 export { AppShell, appShellRootClass } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader } from "./PageHeader.js";
-export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, SidebarLayout, } from "./PageLayouts.js";
+export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";
 export { Section, Stack } from "./Stack.js";
 export { Button, buttonClass } from "./Button.js";
 export { Avatar, avatarColourClass, initialsOf } from "./Avatar.js";
 export { Breadcrumbs, crumbLinkClass } from "./Breadcrumbs.js";
+export { BulletList } from "./BulletList.js";
 export { Callout } from "./Callout.js";
+export { Code } from "./Code.js";
+export { Divider } from "./Divider.js";
 export { Dialog } from "./Dialog.js";
 export { IconButton } from "./IconButton.js";
 export { ColourSchemeToggle } from "./ColourSchemeToggle.js";
@@ -22,10 +25,13 @@ export { CopyLine } from "./CopyLine.js";
 export { Field } from "./Field.js";
 export { FieldDialog } from "./FieldDialog.js";
 export { Input } from "./Input.js";
+export { InlineLinks } from "./InlineLinks.js";
 export { Kbd } from "./Kbd.js";
 export { KeyValue, KeyValueList } from "./KeyValueList.js";
 export { Select } from "./Select.js";
 export { Textarea } from "./Textarea.js";
+export { Video } from "./Video.js";
+export { linkClass, TextLink } from "./TextLink.js";
 export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, Subtitle, } from "./typography.js";
 export { DateField } from "./DateField.js";
 export { DatePicker } from "./DatePicker.js";

package/dist/typography.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ElementType, ReactElement, ReactNode } from "react";
 export type TypographyColor = "default" | "secondary" | "tertiary" | "muted" | "brand";
 /** Own props shared by every typography component; the rest follow the rendered element. */
 type OwnProps = {
@@ -19,57 +19,65 @@ export type TypographyProps<E extends ElementType> = OwnProps & {
  * overriding PageHeading's size.
  */
 export declare const Display: {
-    <E extends ElementType = "h1">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** The supporting sentence under a `Display`. `p`, text-lg/7 normal, secondary. */
 export declare const Lead: {
-    <E extends ElementType = "p">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "p">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Page title. `h1`, text-2xl/8 semibold, primary text. */
 export declare const PageHeading: {
-    <E extends ElementType = "h1">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
-    displayName: string;
-};
-/** Top-level section header. `h2`, text-base/6 semibold, primary text. */
-export declare const SectionHeading: {
-    <E extends ElementType = "h2">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
-    displayName: string;
-};
-/** Nested header. `h3`, text-sm/5 semibold, primary text. */
-export declare const SubsectionHeading: {
-    <E extends ElementType = "h3">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * a hairline under it (the `Divider` line colour) with the space either side of
+ * the line built in.
+ */
+export declare function SectionHeading<E extends ElementType = "h2">({ rule, ...props }: TypographyProps<E> & {
+    rule?: boolean;
+}): ReactElement;
+export type SubsectionHeadingSize = "sm" | "base" | "lg";
+/**
+ * Nested header. `h3`, text-sm/5 semibold, primary text. `size` steps it up for
+ * a card, drawer or form-group title: `sm` (default), `base` (bold) or `lg`.
+ */
+export declare function SubsectionHeading<E extends ElementType = "h3">({ size, ...props }: TypographyProps<E> & {
+    size?: SubsectionHeadingSize;
+}): ReactElement;
 /** Dialog/modal title. `h2`, text-base/6 semibold, primary text. */
 export declare const ModalHeading: {
-    <E extends ElementType = "h2">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "h2">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Supporting line under a heading. `p`, text-sm/5 normal, secondary. */
 export declare const Subtitle: {
-    <E extends ElementType = "p">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "p">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. */
 export declare const Overline: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
-    displayName: string;
-};
-/** Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. */
-export declare const Body: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "span">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/**
+ * Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary.
+ * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
+ */
+export declare function Body<E extends ElementType = "span">({ preserveNewlines, ...props }: TypographyProps<E> & {
+    preserveNewlines?: boolean;
+}): ReactElement;
 /** Emphasised run of body text. `span`, text-sm/5 medium, primary text. */
 export declare const BodyStrong: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "span">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. */
 export declare const Caption: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "span">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 export {};

package/dist/typography.js

@@ -15,13 +15,20 @@ const COLOR = {
  * layout classes — never the pinned size/weight.
  */
 function typography(displayName, defaultAs, variantClass, defaultColor) {
-    function Typography({ as, color, className, children, ...rest }) {
-        const Tag = as ?? defaultAs;
-        return (_jsx(Tag, { className: cx(variantClass, COLOR[color ?? defaultColor], className), ...rest, children: children }));
+    function Typography(props) {
+        return pinned(defaultAs, variantClass, defaultColor, props);
     }
     Typography.displayName = displayName;
     return Typography;
 }
+/**
+ * The one place a pinned role renders. The few roles with an opt-in prop of their own are
+ * written by hand, not by `typography`, and call this too.
+ */
+function pinned(defaultAs, variantClass, defaultColor, { as, color, className, children, ...rest }) {
+    const Tag = as ?? defaultAs;
+    return (_jsx(Tag, { className: cx(variantClass, COLOR[color ?? defaultColor], className), ...rest, children: children }));
+}
 // --- Structural roles (block by default) -----------------------------------
 /**
  * Marketing-scale headline — the one line at the top of a public page. `h1`,
@@ -35,10 +42,27 @@ export const Display = typography("Display", "h1", "text-4xl/[1.1] font-semibold
 export const Lead = typography("Lead", "p", "text-lg/7 font-normal sm:text-xl/8", "secondary");
 /** Page title. `h1`, text-2xl/8 semibold, primary text. */
 export const PageHeading = typography("PageHeading", "h1", "text-2xl/8 font-semibold tracking-tight", "default");
-/** Top-level section header. `h2`, text-base/6 semibold, primary text. */
-export const SectionHeading = typography("SectionHeading", "h2", "text-base/6 font-semibold", "default");
-/** Nested header. `h3`, text-sm/5 semibold, primary text. */
-export const SubsectionHeading = typography("SubsectionHeading", "h3", "text-sm/5 font-semibold", "default");
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * a hairline under it (the `Divider` line colour) with the space either side of
+ * the line built in.
+ */
+export function SectionHeading({ rule, ...props }) {
+    const variant = cx(rule && "mb-4 border-b border-slate-200/70 pb-2", "text-base/6 font-semibold");
+    return pinned("h2", variant, "default", props);
+}
+const SUBSECTION_SIZE = {
+    sm: "text-sm/5 font-semibold",
+    base: "text-base/6 font-bold",
+    lg: "text-lg/7 font-semibold",
+};
+/**
+ * Nested header. `h3`, text-sm/5 semibold, primary text. `size` steps it up for
+ * a card, drawer or form-group title: `sm` (default), `base` (bold) or `lg`.
+ */
+export function SubsectionHeading({ size = "sm", ...props }) {
+    return pinned("h3", SUBSECTION_SIZE[size], "default", props);
+}
 /** Dialog/modal title. `h2`, text-base/6 semibold, primary text. */
 export const ModalHeading = typography("ModalHeading", "h2", "text-base/6 font-semibold", "default");
 /** Supporting line under a heading. `p`, text-sm/5 normal, secondary. */
@@ -46,8 +70,14 @@ export const Subtitle = typography("Subtitle", "p", "text-sm/5 font-normal", "se
 // --- Inline roles (inline by default) --------------------------------------
 /** Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. */
 export const Overline = typography("Overline", "span", "text-xs font-semibold uppercase tracking-wide", "tertiary");
-/** Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. */
-export const Body = typography("Body", "span", "text-sm/5 font-normal", "secondary");
+/**
+ * Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary.
+ * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
+ */
+export function Body({ preserveNewlines, ...props }) {
+    const variant = cx(preserveNewlines && "whitespace-pre-line", "text-sm/5 font-normal");
+    return pinned("span", variant, "secondary", props);
+}
 /** Emphasised run of body text. `span`, text-sm/5 medium, primary text. */
 export const BodyStrong = typography("BodyStrong", "span", "text-sm/5 font-medium", "default");
 /** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. */

package/package.json

@@ -1,8 +1,26 @@
 {
   "name": "@hackcove/ui",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
+  "keywords": [
+    "components",
+    "design-system",
+    "hackcove",
+    "markdown",
+    "react",
+    "tailwind",
+    "tailwindcss",
+    "ui"
+  ],
+  "homepage": "https://github.com/madangryscientist/hackcove/tree/main/packages/ui#readme",
+  "bugs": {
+    "url": "https://github.com/madangryscientist/hackcove/issues"
+  },
   "license": "MIT",
+  "author": {
+    "name": "Jacobus Langner",
+    "url": "https://github.com/madangryscientist"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/madangryscientist/hackcove.git",