@hackcove/ui-react 0.10.0 → 0.10.2

package/dist/typography.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentPropsWithoutRef, type ElementType, type ReactElement, type ReactNode } from "react";
+import type { Passthrough } from "./props.js";
 import type { Size } from "./size.js";
 export type TypographyColor = "default" | "secondary" | "tertiary" | "muted" | "brand";
 /**
@@ -77,8 +78,31 @@ export declare const PageHeading: {
     <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/** True inside a `Prose`, where the text roles take the long-form scale. Internal. */
+export declare function useProse(): boolean;
 /**
- * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * Sets the text roles back to the app scale around what a component renders itself (a `Dialog`, a
+ * `Drawer`, an `EmptyState`), so one opened from a docs page looks as it does anywhere else.
+ * Renders no element. Internal: not exported from the package.
+ */
+export declare function AppScale({ children }: {
+    children?: ReactNode;
+}): ReactElement;
+/**
+ * Long-form content, for a docs page or an article. A block (`div`) that sets text-base/7 on itself,
+ * so a bare `<li>` or text node inside reads at 16px, and puts the text roles inside it on the
+ * prose scale: `Text` text-base/7, `SectionHeading` text-2xl/8, `SubsectionHeading` `lg` text-2xl/8,
+ * `md` text-xl/7 and `sm` text-base/7 (a semibold line at body size), and the box of a `Callout`
+ * text-base/7. Every other role keeps its size. Nothing outside a `Prose` changes, and a `Dialog`,
+ * `Drawer` or `EmptyState` inside one is back on the app scale. An app screen never uses it: wrap the
+ * body of a docs page or an article, inside a `ProseLayout`, a `SidebarLayout` or anywhere else.
+ */
+export declare function Prose({ children, ...rest }: {
+    children?: ReactNode;
+} & Passthrough): ReactElement;
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text (text-2xl/8 semibold tight
+ * inside a `Prose`). `rule` sets
  * a hairline under it (the `Divider` line colour) with the space either side of
  * 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.
@@ -92,7 +116,9 @@ export declare function SectionHeading<E extends ElementType = "h2">({ rule, des
 export type SubsectionHeadingSize = Size;
 /**
  * Nested header. `h3`, text-base/6 semibold, primary text. `size` steps it down for a dense card
- * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. `truncate` keeps it on
+ * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. Inside a `Prose`
+ * `md` is text-xl/7 (the h3 of a doc), `sm` text-base/7 (the h4: body size, set apart by its weight)
+ * and `lg` text-2xl/8, the size of a `SectionHeading` there. `truncate` keeps it on
  * one line and cuts it with an ellipsis where its container ends, the full text as the `title`.
  */
 export declare function SubsectionHeading<E extends ElementType = "h3">({ size, ...props }: TypographyProps<E> & {
@@ -115,7 +141,8 @@ export declare const Overline: {
 /** 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
+ * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary (text-base/7
+ * inside a `Prose`). A block of it
  * stops at a readable line length (`max-w-[72ch]`), wherever it sits. `strong` emphasises it:
  * font-medium in the primary ink, unless `color` or `tone` says otherwise.
  * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.

package/dist/typography.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, } from "react";
+import { Children, createContext, useContext, } from "react";
 import { cx } from "./cx.js";
 /** Colour token → slate/violet utility, which a theme remaps. */
 const COLOR = {
@@ -83,32 +83,72 @@ export const Lead = typography("Lead", "p", "text-lg/7 font-normal sm:text-xl/8"
  * `Lead` under it and the body text after it, so the page's title reads first.
  */
 export const PageHeading = typography("PageHeading", "h1", "text-3xl/9 font-bold tracking-tight sm:text-4xl/10", "default");
+// --- Prose: the long-form scale ---------------------------------------------
 /**
- * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * Whether the text roles below are in a `Prose`. `Text`, `SectionHeading`, `SubsectionHeading` and
+ * `Callout` read it and pick their prose size; outside a `Prose` it is false and nothing changes.
+ * Internal: not exported from the package.
+ */
+const ProseContext = createContext(false);
+/** True inside a `Prose`, where the text roles take the long-form scale. Internal. */
+export function useProse() {
+    return useContext(ProseContext);
+}
+/**
+ * Sets the text roles back to the app scale around what a component renders itself (a `Dialog`, a
+ * `Drawer`, an `EmptyState`), so one opened from a docs page looks as it does anywhere else.
+ * Renders no element. Internal: not exported from the package.
+ */
+export function AppScale({ children }) {
+    return _jsx(ProseContext.Provider, { value: false, children: children });
+}
+/**
+ * Long-form content, for a docs page or an article. A block (`div`) that sets text-base/7 on itself,
+ * so a bare `<li>` or text node inside reads at 16px, and puts the text roles inside it on the
+ * prose scale: `Text` text-base/7, `SectionHeading` text-2xl/8, `SubsectionHeading` `lg` text-2xl/8,
+ * `md` text-xl/7 and `sm` text-base/7 (a semibold line at body size), and the box of a `Callout`
+ * text-base/7. Every other role keeps its size. Nothing outside a `Prose` changes, and a `Dialog`,
+ * `Drawer` or `EmptyState` inside one is back on the app scale. An app screen never uses it: wrap the
+ * body of a docs page or an article, inside a `ProseLayout`, a `SidebarLayout` or anywhere else.
+ */
+export function Prose({ children, ...rest }) {
+    return (_jsx(ProseContext.Provider, { value: true, children: _jsx("div", { ...rest, className: "text-base/7", children: children }) }));
+}
+const SECTION = {
+    app: "text-base/6 font-semibold",
+    prose: "text-2xl/8 font-semibold tracking-tight",
+};
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text (text-2xl/8 semibold tight
+ * inside a `Prose`). `rule` sets
  * a hairline under it (the `Divider` line colour) with the space either side of
  * 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, description, ...props }) {
     const hairline = "mb-4 border-b border-slate-200/70 pb-2";
+    const size = useProse() ? SECTION.prose : SECTION.app;
     const hasDescription = description != null && description !== false;
     if (!hasDescription) {
-        return pinned("h2", cx(rule && hairline, "text-base/6 font-semibold"), "default", props);
+        return pinned("h2", cx(rule && hairline, size), "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 })] }));
+    return (_jsxs("div", { className: cx("flex flex-col gap-1", rule && hairline), children: [pinned("h2", size, "default", props), _jsx(Text, { as: "p", color: "tertiary", children: description })] }));
 }
 const SUBSECTION_SIZE = {
-    sm: "text-sm/5 font-semibold",
-    md: "text-base/6 font-semibold",
-    lg: "text-lg/7 font-semibold",
+    sm: { app: "text-sm/5 font-semibold", prose: "text-base/7 font-semibold" },
+    md: { app: "text-base/6 font-semibold", prose: "text-xl/7 font-semibold" },
+    lg: { app: "text-lg/7 font-semibold", prose: "text-2xl/8 font-semibold tracking-tight" },
 };
 /**
  * Nested header. `h3`, text-base/6 semibold, primary text. `size` steps it down for a dense card
- * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. `truncate` keeps it on
+ * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. Inside a `Prose`
+ * `md` is text-xl/7 (the h3 of a doc), `sm` text-base/7 (the h4: body size, set apart by its weight)
+ * and `lg` text-2xl/8, the size of a `SectionHeading` there. `truncate` keeps it on
  * one line and cuts it with an ellipsis where its container ends, the full text as the `title`.
  */
 export function SubsectionHeading({ size = "md", ...props }) {
-    return pinned("h3", SUBSECTION_SIZE[size], "default", props);
+    const scale = SUBSECTION_SIZE[size];
+    return pinned("h3", useProse() ? scale.prose : scale.app, "default", props);
 }
 // --- Inline roles (inline by default) --------------------------------------
 /**
@@ -117,7 +157,8 @@ export function SubsectionHeading({ size = "md", ...props }) {
  */
 export const Overline = inlineRole("Overline", "span", "text-xs font-semibold uppercase tracking-wide", "tertiary");
 /**
- * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. A block of it
+ * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary (text-base/7
+ * inside a `Prose`). A block of it
  * stops at a readable line length (`max-w-[72ch]`), wherever it sits. `strong` emphasises it:
  * font-medium in the primary ink, unless `color` or `tone` says otherwise.
  * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
@@ -128,7 +169,8 @@ export const Overline = inlineRole("Overline", "span", "text-xs font-semibold up
  * 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, 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", 
+    const prose = useProse();
+    return pinned("span", cx(textVariant(strong, preserveNewlines, true, prose), 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" });
 }
@@ -137,10 +179,10 @@ export function Text({ strong, preserveNewlines, minWidth, italic, breakWords, .
  * it runs the width of its dialog. Internal; not exported from the package.
  */
 export function HeaderText({ children }) {
-    return pinned("p", textVariant(false, false, false), "secondary", { children });
+    return pinned("p", textVariant(false, false, false, useProse()), "secondary", { children });
 }
-function textVariant(strong, preserveNewlines, measure) {
-    return cx(preserveNewlines && "whitespace-pre-line", measure && "max-w-[72ch]", "text-sm/5", strong ? "font-medium" : "font-normal");
+function textVariant(strong, preserveNewlines, measure, prose) {
+    return cx(preserveNewlines && "whitespace-pre-line", measure && "max-w-[72ch]", prose ? "text-base/7" : "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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui-react",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a theme from @hackcove/themes.",
   "keywords": [
     "components",