@hackcove/ui-react 0.9.0 → 0.9.1

package/dist/Table.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 import type { CalloutTone } from "./Callout.js";
 import { type TextTone } from "./typography.js";
-type Align = "start" | "end";
+type Align = "start" | "center" | "end";
 /**
  * The text of a cell: its weight and colour. `default`, `strong` and `muted` are the plain ones; the
  * rest are the Callout's tones, for an amount that carries a meaning (a gain, an overspend). Colour
@@ -15,17 +15,28 @@ type TableVariant = "card" | "plain";
  * stripe takes the tone's text colour, which every theme already remaps, so no new palette entry.
  */
 export type RowTone = "neutral" | "info" | "positive" | "warn" | "danger" | "muted";
-/** The row's status mark: a `tone` (stripe and fill, or faded) or a `stripe` alone, never both. */
+/** The row's mark: a `tone` (stripe and fill, or faded), a `stripe` alone or `emphasis`, only one of them. */
 type RowMark = {
-    /** The row's status: a stripe on the leading edge plus the tone's soft fill, or `muted` to fade the row. Give `tone` or `stripe`, not both. */
+    /** The row's status: a stripe on the leading edge plus the tone's soft fill, or `muted` to fade the row. Give only one of `tone`, `stripe` and `emphasis`. */
     tone?: RowTone | undefined;
-    /** A stripe on the leading edge in this tone, with no fill. Give `stripe` or `tone`, not both. */
+    /** A stripe on the leading edge in this tone, with no fill. Give only one of `tone`, `stripe` and `emphasis`. */
     stripe?: undefined;
+    /** A subtotal in the body: the look of a `TableFoot` row, with strong cells, a firmer line above and no hover. Give only one of `tone`, `stripe` and `emphasis`. */
+    emphasis?: false | undefined;
 } | {
-    /** A stripe on the leading edge in this tone, with no fill. Give `stripe` or `tone`, not both. */
+    /** A stripe on the leading edge in this tone, with no fill. Give only one of `tone`, `stripe` and `emphasis`. */
     stripe?: TextTone | undefined;
-    /** The row's status: a stripe on the leading edge plus the tone's soft fill, or `muted` to fade the row. Give `tone` or `stripe`, not both. */
+    /** The row's status: a stripe on the leading edge plus the tone's soft fill, or `muted` to fade the row. Give only one of `tone`, `stripe` and `emphasis`. */
     tone?: undefined;
+    /** A subtotal in the body: the look of a `TableFoot` row, with strong cells, a firmer line above and no hover. Give only one of `tone`, `stripe` and `emphasis`. */
+    emphasis?: false | undefined;
+} | {
+    /** A subtotal in the body: the look of a `TableFoot` row, with strong cells, a firmer line above and no hover. Give only one of `tone`, `stripe` and `emphasis`. */
+    emphasis: boolean;
+    /** The row's status: a stripe on the leading edge plus the tone's soft fill, or `muted` to fade the row. Give only one of `tone`, `stripe` and `emphasis`. */
+    tone?: undefined;
+    /** A stripe on the leading edge in this tone, with no fill. Give only one of `tone`, `stripe` and `emphasis`. */
+    stripe?: undefined;
 };
 /** What an element passes through (`data-*`, `aria-*`, `id`, …): the layout and the children stay the component's. */
 type Rest<Tag extends "table" | "thead" | "tbody" | "tfoot" | "tr" | "th" | "td", Own extends string = never> = Omit<ComponentPropsWithoutRef<Tag>, "className" | "style" | "children" | Own>;
@@ -73,9 +84,10 @@ export declare function TableFoot({ children, ...rest }: {
  * linked row's link, not a hover fill, says it is clickable. `stripe` is the stripe alone, in the
  * `TextTone` colours (the first five names of a `StackedBar` segment's `VizTone`), with no fill: the row keeps its hover
  * and its own look. Give `tone` or `stripe`, not both. Body rows only; colour alone does not say it,
- * so name the status in a cell too (a `Pill`). A bold subtotal is not a tone: it is a `TableFoot` row.
+ * so name the status in a cell too (a `Pill`). A bold subtotal is not a tone: a total of the whole
+ * table is a `TableFoot` row, and a subtotal among the body's rows is `emphasis`, the same look.
  */
-export declare function TableRow({ tone, stripe, children, ...rest }: RowMark & {
+export declare function TableRow({ tone, stripe, emphasis, children, ...rest }: RowMark & {
     children: ReactNode;
 } & Rest<"tr">): ReactElement;
 /**
@@ -99,7 +111,7 @@ export declare function TableGroupRow({ label, trailing, colSpan, ...rest }: {
  */
 export declare function TableHeaderCell({ align, children, srLabel, ...rest }: {
     /**
-     * The cell's horizontal alignment; `end` for figures.
+     * The cell's horizontal alignment; `end` for figures, `center` over a centred column.
      * @default start
      */
     align?: Align | undefined;
@@ -111,6 +123,8 @@ export declare function TableHeaderCell({ align, children, srLabel, ...rest }: {
     /** The column's name for a screen reader, visually hidden, for a column with no visible title (a row's actions). */
     srLabel: string;
 }) & Rest<"th", "align" | "scope">): ReactElement;
+/** A step of a hierarchy under a row: the cell's own `pl-4` plus 1rem a level. */
+type Indent = 1 | 2 | 3;
 /**
  * A `<td>`. `tone` is the text weight and colour (see `CellTone`; in a `TableFoot` it defaults to
  * `strong`); `numeric` sets tabular figures, `mono` a small mono face. `secondary` is a second,
@@ -119,14 +133,17 @@ export declare function TableHeaderCell({ align, children, srLabel, ...rest }: {
  * cell (a figure, a code, a type) never breaks. `truncate` caps a long value's width, cuts it with
  * an ellipsis on one line and puts the full text in a `title`; the content is then plain text (strings and
  * numbers), since that is what the title shows. `colSpan` passes through: a cell that
- * spans the row is a full-width panel (an empty state, a note under a group).
+ * spans the row is a full-width panel (an empty state, a note under a group), and `align="center"`
+ * centres it. `indent` sets a start-aligned cell in by 1 to 3 levels, for a line under a parent row.
  */
-export declare function TableCell({ align, tone, numeric, mono, truncate, secondary, children, ...rest }: {
+export declare function TableCell({ align, tone, numeric, mono, truncate, indent, secondary, children, ...rest }: {
     /**
-     * The cell's horizontal alignment; `end` for figures.
+     * The cell's horizontal alignment; `end` for figures, `center` for a full-width note or empty state.
      * @default start
      */
     align?: Align | undefined;
+    /** Sets the cell in by this many levels (1 to 3), for a line under a parent row. Start-aligned cells only. */
+    indent?: Indent | undefined;
     /** The text weight and colour (see `CellTone`). In a `TableFoot` it defaults to `strong`. */
     tone?: CellTone | undefined;
     /** Tabular figures, and the cell never wraps. */

package/dist/Table.js

@@ -2,7 +2,11 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { Children, createContext, useContext } from "react";
 import { cx, liftInteractive } from "./cx.js";
 import { TEXT_TONE } from "./typography.js";
-const ALIGN = { start: "text-left", end: "text-right" };
+const ALIGN = {
+    start: "text-left",
+    center: "text-center",
+    end: "text-right",
+};
 const TONE = {
     default: "text-slate-700",
     strong: "font-medium text-slate-900",
@@ -62,12 +66,14 @@ export function TableFoot({ children, ...rest }) {
  * linked row's link, not a hover fill, says it is clickable. `stripe` is the stripe alone, in the
  * `TextTone` colours (the first five names of a `StackedBar` segment's `VizTone`), with no fill: the row keeps its hover
  * and its own look. Give `tone` or `stripe`, not both. Body rows only; colour alone does not say it,
- * so name the status in a cell too (a `Pill`). A bold subtotal is not a tone: it is a `TableFoot` row.
+ * so name the status in a cell too (a `Pill`). A bold subtotal is not a tone: a total of the whole
+ * table is a `TableFoot` row, and a subtotal among the body's rows is `emphasis`, the same look.
  */
-export function TableRow({ tone, stripe, children, ...rest }) {
-    const section = useContext(SectionContext);
+export function TableRow({ tone, stripe, emphasis = false, children, ...rest }) {
+    const outer = useContext(SectionContext);
     const plain = useContext(VariantContext) === "plain";
-    return (_jsx("tr", { ...rest, className: rowClass(section, plain, tone, stripe), children: children }));
+    const section = emphasis && outer === "body" ? "foot" : outer;
+    return (_jsx(SectionContext.Provider, { value: section, children: _jsx("tr", { ...rest, className: rowClass(section, plain, tone, stripe), children: children }) }));
 }
 /** The classes of a row: a line above in the body and the foot, the hover fill and the tone's or stripe's look in the body only. */
 function rowClass(section, plain, tone, stripe) {
@@ -110,6 +116,13 @@ function figureClass(numeric, mono) {
 }
 /** The widest a `truncate` cell grows. */
 const TRUNCATE_WIDTH = "max-w-xs";
+/** Where a `truncate` cell's capped box sits, so it follows the cell's alignment. */
+const TRUNCATE_ALIGN = {
+    start: undefined,
+    center: "mx-auto",
+    end: "ml-auto",
+};
+const INDENT = { 1: "pl-8", 2: "pl-12", 3: "pl-16" };
 /**
  * A `<td>`. `tone` is the text weight and colour (see `CellTone`; in a `TableFoot` it defaults to
  * `strong`); `numeric` sets tabular figures, `mono` a small mono face. `secondary` is a second,
@@ -118,21 +131,22 @@ const TRUNCATE_WIDTH = "max-w-xs";
  * cell (a figure, a code, a type) never breaks. `truncate` caps a long value's width, cuts it with
  * an ellipsis on one line and puts the full text in a `title`; the content is then plain text (strings and
  * numbers), since that is what the title shows. `colSpan` passes through: a cell that
- * spans the row is a full-width panel (an empty state, a note under a group).
+ * spans the row is a full-width panel (an empty state, a note under a group), and `align="center"`
+ * centres it. `indent` sets a start-aligned cell in by 1 to 3 levels, for a line under a parent row.
  */
-export function TableCell({ align = "start", tone, numeric = false, mono = false, truncate = false, secondary, children, ...rest }) {
+export function TableCell({ align = "start", tone, numeric = false, mono = false, truncate = false, indent, secondary, children, ...rest }) {
     const foot = useContext(SectionContext) === "foot";
-    return (_jsx("td", { ...rest, className: cellClass({ align, tone, foot, numeric, mono }), children: _jsx(CellBody, { align: align, truncate: truncate, secondary: secondary, children: children }) }));
+    return (_jsx("td", { ...rest, className: cellClass({ align, indent, tone, foot, numeric, mono }), children: _jsx(CellBody, { align: align, truncate: truncate, secondary: secondary, children: children }) }));
 }
 /** The classes of a cell: the tone (`strong` by default in a foot, and a foot's cells are medium whatever the tone), then the wrapping rule. */
-function cellClass({ align, tone, foot, numeric, mono, }) {
+function cellClass({ align, indent, tone, foot, numeric, mono, }) {
     const resolved = tone ?? (foot ? "strong" : "default");
-    return cx("px-4 py-3", ALIGN[align], TONE[resolved], foot && resolved !== "strong" && "font-medium", figureClass(numeric, mono));
+    return cx("px-4 py-3", align === "start" && indent !== undefined && INDENT[indent], ALIGN[align], TONE[resolved], foot && resolved !== "strong" && "font-medium", figureClass(numeric, mono));
 }
 const isText = (node) => typeof node === "string" || typeof node === "number";
 /** What a cell holds: the content, cut to one line with its full text in a `title` when `truncate`, then the `secondary` line. */
 function CellBody({ align, truncate, secondary, children, }) {
     const parts = Children.toArray(children);
     const text = parts.every(isText) ? parts.join("") : undefined;
-    return (_jsxs(_Fragment, { children: [truncate ? (_jsx("div", { className: cx(TRUNCATE_WIDTH, "truncate", align === "end" && "ml-auto"), title: text, children: children })) : (children), secondary != null && secondary !== false && (_jsx("div", { className: "text-xs font-normal text-slate-500", children: secondary }))] }));
+    return (_jsxs(_Fragment, { children: [truncate ? (_jsx("div", { className: cx(TRUNCATE_WIDTH, "truncate", TRUNCATE_ALIGN[align]), title: text, children: children })) : (children), secondary != null && secondary !== false && (_jsx("div", { className: "text-xs font-normal text-slate-500", children: secondary }))] }));
 }

package/dist/TableEditCell.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { TableCell } from "./Table.js";
+/**
+ * A `TableCell` whose value opens an editor in place. It shows `children` as a button with a dotted
+ * underline; a click, Enter or Space swaps it for `renderEditor(close)` and moves the focus into the
+ * editor. The cell keeps its own open state. The editor calls `close` when it has saved, and Esc
+ * closes it: both put the focus back on the value. A press outside it or Tab out of it closes it too and leaves the
+ * focus where it went, so the editor saves its value on its own change or submit, never on a close.
+ * Put the control in the cell itself, not in a popover of its own, which counts as outside. Takes
+ * `TableCell`'s `align`, `tone`, `numeric`, `mono`, `indent` and `secondary`.
+ */
+export declare function TableEditCell({ label, renderEditor, children, ...cell }: {
+    /** What the button does, for a screen reader, heard after the value: "Edit category". It also names the editor. */
+    label: string;
+    /** The control that edits the value, drawn while open. `close` shuts it and returns the focus to the value. */
+    renderEditor: (close: () => void) => ReactNode;
+    /** The value, shown while closed. */
+    children: ReactNode;
+} & Omit<ComponentProps<typeof TableCell>, "children" | "truncate">): ReactElement;

package/dist/TableEditCell.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { cx, focusRing } from "./cx.js";
+import { TableCell } from "./Table.js";
+/** What takes the focus when the editor opens, unless the editor already took it (`autoFocus`). */
+const FOCUSABLE = "input, select, textarea, button, a[href]";
+/** Whether `target` is a node outside `box`. */
+function isOutside(box, target) {
+    return target instanceof Node && box !== null && !box.contains(target);
+}
+/** Closes the editor when a press lands outside `box`, for as long as `open`. */
+function useDismissOnOutsidePress(box, open, dismiss) {
+    useEffect(() => {
+        if (!open)
+            return undefined;
+        const onPress = (event) => {
+            if (isOutside(box.current, event.target))
+                dismiss();
+        };
+        document.addEventListener("pointerdown", onPress);
+        return () => document.removeEventListener("pointerdown", onPress);
+    }, [box, open, dismiss]);
+}
+/**
+ * A `TableCell` whose value opens an editor in place. It shows `children` as a button with a dotted
+ * underline; a click, Enter or Space swaps it for `renderEditor(close)` and moves the focus into the
+ * editor. The cell keeps its own open state. The editor calls `close` when it has saved, and Esc
+ * closes it: both put the focus back on the value. A press outside it or Tab out of it closes it too and leaves the
+ * focus where it went, so the editor saves its value on its own change or submit, never on a close.
+ * Put the control in the cell itself, not in a popover of its own, which counts as outside. Takes
+ * `TableCell`'s `align`, `tone`, `numeric`, `mono`, `indent` and `secondary`.
+ */
+export function TableEditCell({ label, renderEditor, children, ...cell }) {
+    const [phase, setPhase] = useState("closed");
+    const open = phase === "open";
+    const box = useRef(null);
+    const trigger = useRef(null);
+    const dismiss = useCallback(() => setPhase("closed"), []);
+    const close = () => setPhase("returning");
+    useDismissOnOutsidePress(box, open, dismiss);
+    useEffect(() => {
+        if (phase === "returning")
+            trigger.current?.focus();
+        if (phase === "open" && !box.current?.contains(document.activeElement))
+            box.current?.querySelector(FOCUSABLE)?.focus();
+    }, [phase]);
+    const onKeyDown = (event) => {
+        if (event.key !== "Escape")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        close();
+    };
+    return (_jsx(TableCell, { ...cell, children: open ? (_jsx("div", { ref: box, role: "group", "aria-label": label, className: "-mx-2 -my-1", onKeyDown: onKeyDown, onBlur: (event) => {
+                if (isOutside(event.currentTarget, event.relatedTarget))
+                    dismiss();
+            }, children: renderEditor(close) })) : (_jsxs("button", { ref: trigger, type: "button", onClick: () => setPhase("open"), className: cx("-mx-2 -my-1 block w-[calc(100%+1rem)] cursor-pointer rounded-md px-2 py-1 [text-align:inherit] underline decoration-dotted underline-offset-4 transition hover:bg-slate-100", focusRing), children: [children, _jsxs("span", { className: "sr-only", children: [" ", label] })] })) }));
+}

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { Callout, type CalloutTone } from "./Callout.js";
 export { ListRow, type ListRowProps } from "./ListRow.js";
 export { OutlineRegion, RegionFrame, type RegionRect } from "./OutlineRegion.js";
 export { type CellTone, type RowTone, Table, TableBody, TableCell, TableFoot, TableGroupRow, TableHead, TableHeaderCell, TableRow, } from "./Table.js";
+export { TableEditCell } from "./TableEditCell.js";
 export { EmptyState } from "./EmptyState.js";
 export { Step, Steps } from "./Steps.js";
 export { Timeline, TimelineItem } from "./Timeline.js";
@@ -64,6 +65,9 @@ export { KeyValue, KeyValueList } from "./KeyValueList.js";
 export { Select } from "./Select.js";
 export { Textarea } from "./Textarea.js";
 export { Video } from "./Video.js";
+export { Image, type ImageAspect, type ImageProps, type ImageWidth } from "./Image.js";
+export { MediaTile, type MediaTileProps } from "./MediaTile.js";
+export { ScrollStrip, type ScrollStripProps } from "./ScrollStrip.js";
 export { TextLink, type TextLinkSize } from "./TextLink.js";
 export { Caption, Display, Lead, Overline, PageHeading, SectionHeading, SubsectionHeading, type SubsectionHeadingSize, Text, type TextTone, type TypographyColor, type TypographyProps, } from "./typography.js";
 export { DateField, type DateFieldProps } from "./DateField.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export { Callout } from "./Callout.js";
 export { ListRow } from "./ListRow.js";
 export { OutlineRegion, RegionFrame } from "./OutlineRegion.js";
 export { Table, TableBody, TableCell, TableFoot, TableGroupRow, TableHead, TableHeaderCell, TableRow, } from "./Table.js";
+export { TableEditCell } from "./TableEditCell.js";
 export { EmptyState } from "./EmptyState.js";
 export { Step, Steps } from "./Steps.js";
 export { Timeline, TimelineItem } from "./Timeline.js";
@@ -60,6 +61,9 @@ export { KeyValue, KeyValueList } from "./KeyValueList.js";
 export { Select } from "./Select.js";
 export { Textarea } from "./Textarea.js";
 export { Video } from "./Video.js";
+export { Image } from "./Image.js";
+export { MediaTile } from "./MediaTile.js";
+export { ScrollStrip } from "./ScrollStrip.js";
 export { TextLink } from "./TextLink.js";
 export { Caption, Display, Lead, Overline, PageHeading, SectionHeading, SubsectionHeading, Text, } from "./typography.js";
 export { DateField } from "./DateField.js";

package/dist/size.d.ts

@@ -1,6 +1,6 @@
 /**
  * The one size scale of the library: `sm`, `md` (the default everywhere) and `lg`. A component
- * extends it outward only where it has a real use (Avatar's `xl` and `2xl`, the gap scale's `xs`
+ * extends it outward only where it has a real use (Avatar's `xs`, `xl` and `2xl`, the gap scale's `xs`
  * and `xl`), and no scale skips `md`.
  */
 export type Size = "sm" | "md" | "lg";

package/dist/typography.d.ts

@@ -15,6 +15,8 @@ type OwnProps = {
     color?: TypographyColor;
     children?: ReactNode;
 };
+/** Where a run of text sits across its block. */
+export type TextAlign = "start" | "center" | "end";
 /** The opt-in props of the inline roles (`Text`, `Caption`, `Overline`). */
 type InlineOwnProps = {
     /** A meaning's colour (see `TextTone`). Wins over `color`. */
@@ -25,6 +27,18 @@ type InlineOwnProps = {
     mono?: boolean | undefined;
     /** One line, cut with an ellipsis where the container ends; the full text is the `title`. */
     truncate?: boolean | undefined;
+    /**
+     * Set the text at `start`, `center` or `end` of its block. The run becomes block-level, so the
+     * alignment has a box to act on (a table header cell, a right-hand column).
+     */
+    align?: TextAlign | undefined;
+};
+/** The opt-in props of `Text` and `Caption` only: the face of the run, not a label's. */
+type RunOwnProps = {
+    /** Italic: a muted hint or a caption. */
+    italic?: boolean | undefined;
+    /** Break a long unbroken string (a URL, a token) where the container ends, instead of overflowing. */
+    breakWords?: boolean | undefined;
 };
 type Own = OwnProps & InlineOwnProps;
 /** Polymorphic props: own props + `as` + the intrinsic props of whichever element `as` selects. */
@@ -66,11 +80,14 @@ export declare const PageHeading: {
 /**
  * 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.
+ * the line built in. `description` is a muted line under the heading, outside the `<h2>`, so the
+ * heading's name stays the title; the rule then sits under the description.
  */
-export declare function SectionHeading<E extends ElementType = "h2">({ rule, ...props }: TypographyProps<E> & {
+export declare function SectionHeading<E extends ElementType = "h2">({ rule, description, ...props }: TypographyProps<E> & {
     /** A hairline under the heading, with the space either side of it built in. */
     rule?: boolean;
+    /** A muted line under the heading that says more. It is a paragraph beside the heading, not part of its name. */
+    description?: ReactNode;
 }): ReactElement;
 export type SubsectionHeadingSize = Size;
 /**
@@ -89,12 +106,14 @@ export declare function SubsectionHeading<E extends ElementType = "h3">({ size,
 }): ReactElement;
 /**
  * Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. `tone`,
- * `numeric`, `mono` and `truncate` are opt-in, as on `Text`.
+ * `numeric`, `mono`, `truncate` and `align` are opt-in, as on `Text`.
  */
 export declare const Overline: {
     <E extends ElementType = "span">(props: InlineTypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/** A fixed width for a run of text: `amount` is a money figure, right-aligned, at a width that lines a column up. */
+export type TextMinWidth = "amount";
 /**
  * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. A block of it
  * stops at a readable line length (`max-w-[72ch]`), wherever it sits. `strong` emphasises it:
@@ -102,13 +121,17 @@ export declare const Overline: {
  * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
  * `tone` colours it by meaning (`positive` for "Saved.", `danger` for an error; it wins over `color`),
  * `numeric` sets tabular figures, `mono` the monospace face, and `truncate` cuts it to one line with an
- * ellipsis (the full text becomes its `title`).
+ * ellipsis (the full text becomes its `title`). `align` sets it at `start`, `center` or `end`.
+ * `italic` slants it, `breakWords` breaks a long unbroken string at the edge of its box, and `minWidth="amount"`
+ * fixes a width and right-aligns the figure in it (a column of amounts lines up); it does not take `align`.
  */
-export declare function Text<E extends ElementType = "span">({ strong, preserveNewlines, ...props }: InlineTypographyProps<E> & {
+export declare function Text<E extends ElementType = "span">({ strong, preserveNewlines, minWidth, italic, breakWords, ...props }: InlineTypographyProps<E> & RunOwnProps & {
     /** Emphasis: font-medium in the primary ink (`color` and `tone` still win). */
     strong?: boolean | undefined;
     /** Keep the line breaks in the text (a user-typed note); runs of spaces still collapse. */
     preserveNewlines?: boolean;
+    /** A fixed width: `amount` is a right-aligned money figure, min-w-24, in tabular figures. */
+    minWidth?: TextMinWidth | undefined;
 }): ReactElement;
 /**
  * The supporting line under a `Dialog` title: `Text as="p"` without the measure, so
@@ -117,9 +140,10 @@ export declare function Text<E extends ElementType = "span">({ strong, preserveN
 export declare function HeaderText({ children }: {
     children: ReactNode;
 }): ReactElement;
-/** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. Takes `tone`, `numeric`, `mono` and `truncate` like `Text`. */
-export declare const Caption: {
-    <E extends ElementType = "span">(props: InlineTypographyProps<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. Takes `tone`,
+ * `numeric`, `mono`, `truncate` and `align` like `Text`, and `italic` for a muted hint and `breakWords`
+ * for a long unbroken string such as a URL.
+ */
+export declare function Caption<E extends ElementType = "span">({ italic, breakWords, ...props }: InlineTypographyProps<E> & RunOwnProps): ReactElement;
 export {};

package/dist/typography.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, } from "react";
 import { cx } from "./cx.js";
 /** Colour token → slate/violet utility, which a theme remaps. */
@@ -17,6 +17,11 @@ export const TEXT_TONE = {
     warn: "text-amber-700",
     danger: "text-red-700",
 };
+const ALIGN = {
+    start: "text-start",
+    center: "text-center",
+    end: "text-end",
+};
 /**
  * Build a semantic component that pins `variantClass` (size + weight + tracking)
  * and a default colour. The scale/weight for each role therefore lives in exactly
@@ -42,9 +47,19 @@ function inlineRole(displayName, defaultAs, variantClass, defaultColor) {
  * 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, tone, numeric, mono, truncate, children, ...rest }) {
+function pinned(defaultAs, variantClass, defaultColor, { as, color, tone, numeric, mono, truncate, align, children, ...rest }) {
     const Tag = as ?? defaultAs;
-    return (_jsx(Tag, { ...rest, ...(truncate ? { title: rest.title ?? plainText(children) } : {}), className: cx(variantClass, tone ? TEXT_TONE[tone] : COLOR[color ?? defaultColor], numeric && "tabular-nums", mono && "font-mono", truncate && "inline-block min-w-0 truncate align-bottom"), children: children }));
+    return (_jsx(Tag, { ...rest, ...(truncate ? { title: rest.title ?? plainText(children) } : {}), className: cx(variantClass, tone ? TEXT_TONE[tone] : COLOR[color ?? defaultColor], numeric && "tabular-nums", mono && "font-mono", layoutClass(align, truncate)), children: children }));
+}
+/**
+ * The alignment, and the box it needs. An aligned run is block-level, so text-align has a box to set
+ * the text in. A truncated run clips: inline-block by default, a block when it is aligned too.
+ */
+function layoutClass(align, truncate) {
+    const box = truncate
+        ? cx("min-w-0 truncate align-bottom", align ? "block" : "inline-block")
+        : align && "block";
+    return cx(align && ALIGN[align], box);
 }
 /** The text of `children` when it is all strings and numbers: what a truncated run shows on hover. */
 function plainText(children) {
@@ -71,11 +86,16 @@ export const PageHeading = typography("PageHeading", "h1", "text-3xl/9 font-bold
 /**
  * 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.
+ * the line built in. `description` is a muted line under the heading, outside the `<h2>`, so the
+ * heading's name stays the title; the rule then sits under the description.
  */
-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);
+export function SectionHeading({ rule, description, ...props }) {
+    const hairline = "mb-4 border-b border-slate-200/70 pb-2";
+    const hasDescription = description != null && description !== false;
+    if (!hasDescription) {
+        return pinned("h2", cx(rule && hairline, "text-base/6 font-semibold"), "default", props);
+    }
+    return (_jsxs("div", { className: cx("flex flex-col gap-1", rule && hairline), children: [pinned("h2", "text-base/6 font-semibold", "default", props), _jsx(Text, { as: "p", color: "tertiary", children: description })] }));
 }
 const SUBSECTION_SIZE = {
     sm: "text-sm/5 font-semibold",
@@ -93,7 +113,7 @@ export function SubsectionHeading({ size = "md", ...props }) {
 // --- Inline roles (inline by default) --------------------------------------
 /**
  * Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. `tone`,
- * `numeric`, `mono` and `truncate` are opt-in, as on `Text`.
+ * `numeric`, `mono`, `truncate` and `align` are opt-in, as on `Text`.
  */
 export const Overline = inlineRole("Overline", "span", "text-xs font-semibold uppercase tracking-wide", "tertiary");
 /**
@@ -103,10 +123,14 @@ export const Overline = inlineRole("Overline", "span", "text-xs font-semibold up
  * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
  * `tone` colours it by meaning (`positive` for "Saved.", `danger` for an error; it wins over `color`),
  * `numeric` sets tabular figures, `mono` the monospace face, and `truncate` cuts it to one line with an
- * ellipsis (the full text becomes its `title`).
+ * ellipsis (the full text becomes its `title`). `align` sets it at `start`, `center` or `end`.
+ * `italic` slants it, `breakWords` breaks a long unbroken string at the edge of its box, and `minWidth="amount"`
+ * fixes a width and right-aligns the figure in it (a column of amounts lines up); it does not take `align`.
  */
-export function Text({ strong, preserveNewlines, ...props }) {
-    return pinned("span", textVariant(strong, preserveNewlines, true), strong ? "default" : "secondary", props);
+export function Text({ strong, preserveNewlines, minWidth, italic, breakWords, ...props }) {
+    return pinned("span", cx(textVariant(strong, preserveNewlines, true), italic && "italic", breakWords && "break-words", minWidth === "amount" && "inline-block min-w-24 text-end"), strong ? "default" : "secondary", 
+    // An amount is always in tabular figures, so it lines up; `numeric` already emits them.
+    { ...props, numeric: props.numeric || minWidth === "amount" });
 }
 /**
  * The supporting line under a `Dialog` title: `Text as="p"` without the measure, so
@@ -118,5 +142,11 @@ export function HeaderText({ children }) {
 function textVariant(strong, preserveNewlines, measure) {
     return cx(preserveNewlines && "whitespace-pre-line", measure && "max-w-[72ch]", "text-sm/5", strong ? "font-medium" : "font-normal");
 }
-/** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. Takes `tone`, `numeric`, `mono` and `truncate` like `Text`. */
-export const Caption = inlineRole("Caption", "span", "text-xs/4 font-normal", "tertiary");
+/**
+ * Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. Takes `tone`,
+ * `numeric`, `mono`, `truncate` and `align` like `Text`, and `italic` for a muted hint and `breakWords`
+ * for a long unbroken string such as a URL.
+ */
+export function Caption({ italic, breakWords, ...props }) {
+    return pinned("span", cx("text-xs/4 font-normal", italic && "italic", breakWords && "break-words"), "tertiary", props);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui-react",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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",