@supertype.ai/foundations 0.1.24

package/dist/eslint.js

@@ -0,0 +1,138 @@
+/**
+ * The design rules, as ESLint selectors, shared so the two apps cannot drift.
+ * Plain data — esquery matches these against className strings, so no plugin.
+ * They see values, never the shape of a class list; a primitive fixes that.
+ */
+/** A className written as a plain string, or as a chunk of a template literal. */
+const classString = (pattern) => [
+    `Literal[value=${pattern}]`,
+    `TemplateElement[value.raw=${pattern}]`,
+];
+const rule = (pattern, message) => classString(pattern).map((selector) => ({ selector, message }));
+const VARIANTS = "(dark:|hover:|focus:|group-hover:|active:|disabled:|sm:|md:|lg:|xl:)*";
+const PALETTE = "(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)";
+/** Applies everywhere, marketing included — the tints exist for those pages. */
+export function colourRules({ accents = "a brand accent", } = {}) {
+    return [
+        ...rule(`/(^| )${VARIANTS}(text|bg|border|ring|from|to|via|fill|stroke|divide|outline|placeholder|shadow|decoration|accent|caret)-${PALETTE}-\\d+/`, `Raw Tailwind palette. Use a token — text-foreground / text-muted-foreground / text-subtle-foreground, bg-background / bg-card / bg-muted, border-border — a status token (success, warn, destructive), or ${accents}.`),
+        // Split by prefix: alpha on a fill is a scrim (the effect), on ink or a
+        // hairline it is just an undeclared colour.
+        ...rule(`/(^| )${VARIANTS}(bg|from|to|via|shadow)-(white|black)($| )/`, "Solid white/black is a hand-rolled surface. Use bg-card / bg-background, or bg-tint for a tinted panel. Alpha scrims (bg-black/50) stay legal — there the point is the transparency, not the hue."),
+        ...rule(`/(^| )${VARIANTS}(text|border|ring|divide|fill|stroke|decoration|outline|placeholder)-(white|black)($| |\\x2f)/`, "White/black ink and hairlines are hand-rolled colour, alpha or not. Use text-foreground / text-background for ink, text-tint-foreground for ink on a tinted surface, and border-border for a hairline — the token already carries the alpha the theme wants."),
+        ...rule("/(^| )(text|bg|border|fill|stroke|ring)-\\[#/", "Hex colours bypass the token system entirely. Add a token if the colour is real; use an existing one if it is not."),
+    ];
+}
+/**
+ * The semantic tokens, for the rules that care which token it is rather than
+ * whether one was used at all.
+ */
+const TOKEN = "foreground|muted-foreground|subtle-foreground|muted|card-foreground|card|popover-foreground|popover|" +
+    "secondary-foreground|secondary|accent-foreground|accent|primary-foreground|primary|border|input|ring|" +
+    "background|destructive-foreground|destructive|success|warn|info|brand|tint-foreground";
+const COLOUR_PREFIX = "text|bg|border|ring|from|to|via|fill|stroke|divide|placeholder|decoration|shadow|outline";
+/**
+ * A token already knows what it does in the dark; `dark:` on one says the token
+ * is wrong. Only the solid form is restricted — `dark:bg-destructive/20` against
+ * a `/10` is the same token at the density a darker ground needs.
+ */
+export function themeOverrideRules() {
+    return rule(`/(^| )dark:(${COLOUR_PREFIX})-(${TOKEN})($| )/`, "A `dark:` override on a token means the token is wrong — fix it in theme.css, where one change covers every call site, rather than here. Alpha variants (dark:bg-destructive/20) stay legal: those tune a wash's density, not the token.");
+}
+/**
+ * `--muted` is a fill at L92%, so `text-muted` is ~1.1:1 — invisible, and it
+ * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
+ */
+export function surfaceAsInkRules() {
+    return rule("/(^| )(dark:|hover:|focus:|group-hover:)*text-(muted|card|popover|input)($| )/", "That is a surface token, not an ink — as text it has no defined contrast (text-muted measures ~1.1:1 on a light page). Use text-muted-foreground for secondary ink, text-subtle-foreground for tertiary, or text-card-foreground on a card.");
+}
+/**
+ * `-foreground` means the label printed on a fill; `-ink` means the hue as
+ * words. `warn-foreground` was always the ink, under the other name.
+ */
+export function renamedTokenRules() {
+    return rule("/(^| )(dark:|hover:|focus:|group-hover:)*(text|bg|border|ring|fill|stroke)-warn-foreground($| )/", "`warn-foreground` is the deprecated name for `warn-ink`. In this package `-foreground` is the label printed on a fill and `-ink` is the hue used as text; warn has no printed-on label, because orange carries white text at no lightness. Use warn-ink.");
+}
+export function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2xs 11 / text-xs 12 / text-sm 14 / text-base 16 and up", pairing = false, axis = false, } = {}) {
+    return [
+        // Alpha ink composites against whatever surface it lands on, so its
+        // contrast is unmeasurable. The ink tokens are measured.
+        // `\x2f`, never a literal slash: ESLint 8's esquery ends the regex at the
+        // first `/` it sees, however escaped, and hands RegExp the truncated half.
+        ...rule("/text-(foreground|muted-foreground|subtle-foreground)\\x2f\\d+/", "Alpha on a text token has unmeasurable contrast (it composites against whatever surface it lands on). Use text-foreground (primary), text-muted-foreground (secondary), or text-subtle-foreground (tertiary)."),
+        // px only: a rem value at display scale is an ornament, not a rung.
+        ...rule("/(^| )text-\\[\\d+px\\]/", `Arbitrary font sizes bypass the type ramp. Use a rung (${ramp}).`),
+        // A primitive that owns a size axis, reached past for a class that does the
+        // same thing. The class wins on the page, so nothing looks wrong — what is
+        // lost is everything else the axis carries: `TypographyCaption` pins leading
+        // per rung because a wrapped caption sets cramped at the ramp's own setting,
+        // and `TypographyStat` pairs its rungs with the heading ladder so a figure
+        // and the heading beside it retune together on an editorial surface. A
+        // literal gets the size and silently drops the rest.
+        //
+        // Matching the class node INSIDE the attribute, rather than the className
+        // string on its own, lets this name the component. It reaches into `cn()`
+        // for free, since the argument sits in the same subtree.
+        ...(axis
+            ? [
+                // Both node kinds, for the same reason `classString` above covers both: a
+                // class list assembled in a template literal is the shape a call site
+                // reaches for precisely when it is doing something conditional, which
+                // is where a stray rung is most likely to be hiding.
+                ...["Literal[value", "TemplateElement[value.raw"].map((node) => ({
+                    selector: `JSXOpeningElement[name.name=/^Typography(Small|Caption|Stat|Eyebrow)$/] JSXAttribute[name.name="className"] ${node}=/(^| )text-(3xs|2xs|xs|sm|base|lg|xl|[2-9]xl|h[1-4])( |$)/]`,
+                    message: "This primitive owns its size: pass the axis (TypographySmall/Caption size=, TypographyStat size=, TypographyEyebrow tone=) rather than a text-* class, which takes the size and drops the leading and ladder that come with the rung.",
+                })),
+            ]
+            : []),
+        // Two valid primitives forming an invalid pair, which the value rules above
+        // cannot see: `<TypographyP>` is the 14px interface rung, and the list under
+        // it reads at the prose rung, so one passage lands two rungs apart.
+        //
+        // `~` and never `+`: JSX puts a whitespace text node between sibling
+        // elements, and an adjacent-sibling selector will not cross it — measured,
+        // `+` matches nothing at all here. The cost of `~` is that it means "any
+        // later sibling", so it can reach past an intervening paragraph; on a corpus
+        // of 168 files it fired four times and was right four times.
+        ...(pairing
+            ? [
+                {
+                    selector: 'JSXElement:has(>JSXOpeningElement[name.name="TypographyP"]) ~ JSXElement > JSXOpeningElement[name.name="TypographyProseList"]',
+                    message: "A ui paragraph over a prose list splits one passage across two rungs. Promote the paragraph with TypographyProse, or drop the list to the paragraph's rung with TypographyList variant=\"ui\".",
+                },
+            ]
+            : []),
+        ...(weights
+            ? rule("/(^| )font-(bold|extrabold|black)( |$)/", "The product weight ramp is 400 body / 500 label / 600 heading. Use font-semibold for headings, or a label primitive for a label.")
+            : []),
+    ];
+}
+/**
+ * Every rule in one flat-config entry, ready to spread into eslint.config.js:
+ *
+ *   import { designConfig } from "@supertype.ai/foundations/eslint";
+ *   export default [ ...designConfig({ accents: "the brand tints" }) ];
+ *
+ * One entry is not a detail. Flat config replaces a rule's options rather than
+ * merging them, so two blocks covering overlapping files leave only the last
+ * one's rules in effect. Combining them here is what stops a consumer losing
+ * half the set by accident. If you need a second scope, call this again with a
+ * different `files` and no overlap.
+ */
+export function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], accents, weights, ramp, pairing, axis, } = {}) {
+    return [
+        {
+            name: "@supertype.ai/foundations/design",
+            files,
+            rules: {
+                "no-restricted-syntax": [
+                    "error",
+                    ...colourRules({ accents }),
+                    ...typographyRules({ weights, ramp, pairing, axis }),
+                    ...themeOverrideRules(),
+                    ...surfaceAsInkRules(),
+                    ...renamedTokenRules(),
+                ],
+            },
+        },
+    ];
+}

package/dist/essay/contents.d.ts

@@ -0,0 +1,10 @@
+import type { EssayIndexEntry } from "./essay.js";
+/**
+ * The margin index, with the section you are in marked. Separate from
+ * `EssayLayout` so only this nav crosses the client boundary.
+ */
+export declare function TableOfContents({ sections, label, }: {
+    sections: readonly EssayIndexEntry[];
+    /** The rail's own heading. Set it to `null` to render the links alone. */
+    label?: React.ReactNode;
+}): import("react").JSX.Element | null;

package/dist/essay/contents.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Rail, RailLink } from "./rail.js";
+import { useScrollSpy } from "./scroll.js";
+/**
+ * The margin index, with the section you are in marked. Separate from
+ * `EssayLayout` so only this nav crosses the client boundary.
+ */
+export function TableOfContents({ sections, label = "On this page", }) {
+    const active = useScrollSpy(sections.map((s) => s.id));
+    // Nothing to index is nothing to render: an empty list would still draw the
+    // label and the rail's hairline in the margin. `ReadingRail` bails the same
+    // way. Placed after the hook so the call order never changes.
+    if (sections.length === 0)
+        return null;
+    return (_jsxs("nav", { "aria-label": "Page sections", children: [label ? (_jsx("p", { className: "mb-4 text-xs font-medium uppercase tracking-widest text-muted-foreground", children: label })) : null, _jsx(Rail, { children: sections.map(({ id, label: text }) => (_jsx(RailLink, { href: `#${id}`, active: active === id, children: text }, id))) })] }));
+}

package/dist/essay/essay.d.ts

@@ -0,0 +1,125 @@
+import type { ComponentProps, ComponentType, ReactNode } from "react";
+/**
+ * The long-form reading surface: a page read from the top, not scanned.
+ * `EssayColumns` sets the measure, `EssayHeader` the opening, `EssayDocument`
+ * the whole of a page whose sections are just heading and prose.
+ */
+/** One entry in the margin index, matching the `id` of the section it points at. */
+export type EssayIndexEntry = {
+    id: string;
+    label: string;
+};
+/**
+ * Motion and gradient belong to an app, not the package. Both default to
+ * nothing, so a consumer supplying neither gets the same markup, statically.
+ */
+export interface EssayDecorations {
+    /** `"scale"` is the only variant named, so a narrower union still satisfies it. */
+    Reveal?: ComponentType<{
+        children: ReactNode;
+        className?: string;
+        eager?: boolean;
+        variant?: "scale";
+    }>;
+    /** A backdrop behind the header. Rendered before the content, positioned by class. */
+    Glow?: ComponentType<{
+        className?: string;
+        intensity?: number;
+    }>;
+}
+/** One section of a reference document: a heading, and the prose under it. */
+export type EssayDocSection = {
+    heading: string;
+    /** A string is set as one paragraph. Pass a node for anything longer. */
+    body: string | ReactNode;
+    /** Only when the anchor has to outlive a retitling, since it is a public URL. */
+    id?: string;
+};
+/** One step of a sequence: an ordinal, a title, and the prose under it. */
+export type EssayMovement = {
+    title: string;
+    body: ReactNode;
+};
+export declare function createEssay({ Reveal, Glow, }?: EssayDecorations): {
+    EssayHeader: ({ eyebrow, title, lede, byline, }: {
+        eyebrow: ReactNode;
+        title: ReactNode;
+        /** The standfirst. Optional: a short piece can open on its title alone. */
+        lede?: ReactNode;
+        /** The signature line under the lede: who wrote it, and who it is written for. */
+        byline?: ReactNode;
+    }) => import("react").JSX.Element;
+    EssayLayout: ({ index, children, }: {
+        index: readonly EssayIndexEntry[];
+        children: ReactNode;
+    }) => import("react").JSX.Element;
+    EssaySection: ({ id, heading, children, }: {
+        id: string;
+        heading: ReactNode;
+        children: ReactNode;
+    }) => import("react").JSX.Element;
+    EssayPullQuote: ({ children }: {
+        children: ReactNode;
+    }) => import("react").JSX.Element;
+    EssayFigure: ({ children, caption, }: {
+        children: ReactNode;
+        caption: ReactNode;
+    }) => import("react").JSX.Element;
+    EssayMovements: ({ items }: {
+        items: readonly EssayMovement[];
+    }) => import("react").JSX.Element;
+    EssayDocument: ({ sections, ...header }: ComponentProps<({ eyebrow, title, lede, byline, }: {
+        eyebrow: ReactNode;
+        title: ReactNode;
+        /** The standfirst. Optional: a short piece can open on its title alone. */
+        lede?: ReactNode;
+        /** The signature line under the lede: who wrote it, and who it is written for. */
+        byline?: ReactNode;
+    }) => import("react").JSX.Element> & {
+        sections: readonly EssayDocSection[];
+    }) => import("react").JSX.Element;
+};
+/**
+ * The undecorated shell, bound once.
+ *
+ * The factory takes an app's motion and gradient, and an app that has neither
+ * still had to call it — at module scope, passing nothing — because there was
+ * no other way to reach the components. These are that call, made here, so a
+ * consumer without decorations imports them by name like the rest of the
+ * package. `createEssay` stays for the consumers that do decorate.
+ *
+ * Module scope is not incidental. The factory defines its components per call,
+ * so one made during a render hands React a new type on every pass and remounts
+ * everything under it.
+ */
+export declare const EssayHeader: ({ eyebrow, title, lede, byline, }: {
+    eyebrow: ReactNode;
+    title: ReactNode;
+    /** The standfirst. Optional: a short piece can open on its title alone. */
+    lede?: ReactNode;
+    /** The signature line under the lede: who wrote it, and who it is written for. */
+    byline?: ReactNode;
+}) => import("react").JSX.Element, EssayLayout: ({ index, children, }: {
+    index: readonly EssayIndexEntry[];
+    children: ReactNode;
+}) => import("react").JSX.Element, EssaySection: ({ id, heading, children, }: {
+    id: string;
+    heading: ReactNode;
+    children: ReactNode;
+}) => import("react").JSX.Element, EssayPullQuote: ({ children }: {
+    children: ReactNode;
+}) => import("react").JSX.Element, EssayFigure: ({ children, caption, }: {
+    children: ReactNode;
+    caption: ReactNode;
+}) => import("react").JSX.Element, EssayMovements: ({ items }: {
+    items: readonly EssayMovement[];
+}) => import("react").JSX.Element, EssayDocument: ({ sections, ...header }: ComponentProps<({ eyebrow, title, lede, byline, }: {
+    eyebrow: ReactNode;
+    title: ReactNode;
+    /** The standfirst. Optional: a short piece can open on its title alone. */
+    lede?: ReactNode;
+    /** The signature line under the lede: who wrote it, and who it is written for. */
+    byline?: ReactNode;
+}) => import("react").JSX.Element> & {
+    sections: readonly EssayDocSection[];
+}) => import("react").JSX.Element;

package/dist/essay/essay.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../cn.js";
+import { headingClass, TypographyEyebrow, TypographyH1, TypographyH2, TypographyH3, } from "../typography/header.js";
+import { TypographyCaption, TypographyMuted, TypographyProse, } from "../typography/paragraph.js";
+import { EssayColumns } from "./layout.js";
+import { TableOfContents } from "./contents.js";
+/** Pass-through: keeps the className the shell relies on for layout. */
+const PlainReveal = ({ children, className, }) => _jsx("div", { className: className, children: children });
+const NoGlow = () => null;
+// Apostrophes are dropped rather than treated as a separator, so "What we don't
+// collect" anchors at `what-we-dont-collect` the way a reader would type it.
+const slugify = (heading) => heading
+    .toLowerCase()
+    .replace(/['’]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/**
+ * Resolved for the whole document, since only the full list settles two cases:
+ * a heading with no ASCII slugs to "" (which `useScrollSpy` discards), and two
+ * differing only in case collide. An explicit `id` is always honoured.
+ */
+const anchorIds = (sections) => {
+    const seen = new Map();
+    return sections.map((section, i) => {
+        const base = section.id ?? (slugify(section.heading) || `section-${i + 1}`);
+        const taken = seen.get(base) ?? 0;
+        seen.set(base, taken + 1);
+        return taken ? `${base}-${taken + 1}` : base;
+    });
+};
+export function createEssay({ Reveal = PlainReveal, Glow = NoGlow, } = {}) {
+    /** Left aligned: the eye has to reach the first line of prose either way. */
+    function EssayHeader({ eyebrow, title, lede, byline, }) {
+        return (_jsxs("header", { className: "relative overflow-hidden pb-12 pt-16 sm:pt-24", children: [_jsx(Glow, { className: "-top-40 left-1/2 -translate-x-1/2", intensity: 0.16 }), _jsx(EssayColumns, { children: _jsxs(Reveal, { eager: true, className: "flex flex-col gap-6", children: [_jsx(TypographyEyebrow, { children: eyebrow }), _jsx(TypographyH1, { variant: "display", className: "text-balance", children: title }), lede && (_jsx(TypographyMuted, { className: "text-pretty text-xl leading-relaxed", children: lede })), byline && (_jsx(TypographyMuted, { className: "border-t border-border/60 pt-5 text-base", children: byline }))] }) })] }));
+    }
+    /** The reading column, with the sticky index sitting in its left margin. */
+    function EssayLayout({ index, children, }) {
+        return (_jsx(EssayColumns, { className: "pb-16 sm:pb-24", aside: _jsx("div", { className: "sticky top-24", children: _jsx(TableOfContents, { sections: index }) }), children: _jsx("div", { className: "flex flex-col gap-16 border-t border-border pt-12 @6xl:border-t-0 @6xl:pt-0", children: children }) }));
+    }
+    /** The heading carries the anchor, offset so it lands under the sticky nav. */
+    function EssaySection({ id, heading, children, }) {
+        return (_jsx("section", { id: id, className: "scroll-mt-24", children: _jsxs(Reveal, { className: "flex flex-col gap-5", children: [_jsx(TypographyH2, { className: "text-balance", children: heading }), children] }) }));
+    }
+    /** One per essay: a page with three of them has decided nothing. */
+    function EssayPullQuote({ children }) {
+        return (_jsx(Reveal, { children: _jsx("blockquote", { className: cn(headingClass(), "text-balance border-l-2 border-primary/40 py-1 pl-6 leading-snug"), children: children }) }));
+    }
+    /** Generic on purpose: a page hands it anything; this decides only the fit. */
+    function EssayFigure({ children, caption, }) {
+        return (_jsx(Reveal, { variant: "scale", children: _jsxs("figure", { className: "flex flex-col gap-3", children: [children, _jsx(TypographyCaption, { className: "text-pretty", children: caption })] }) }));
+    }
+    /**
+       * A grid says the items are interchangeable; these hand output to each other.
+       * An ordered list says that without an arrow — the ordinal is the ornament.
+       */
+    function EssayMovements({ items }) {
+        return (_jsx("ol", { className: "flex flex-col", children: items.map(({ title, body }, i) => (_jsxs("li", { className: "border-t border-border/60 py-8 first:border-t-0 first:pt-0 last:pb-0 sm:grid sm:grid-cols-[3.5rem_minmax(0,1fr)] sm:gap-6", children: [_jsx(TypographyCaption, { className: "block pt-2 font-mono tabular-nums text-primary max-sm:mb-2", children: String(i + 1).padStart(2, "0") }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(TypographyH3, { children: title }), body] })] }, title))) }));
+    }
+    /**
+     * A reference document as data: the index derives from the sections, so a
+     * retitling cannot leave the rail scrolling to nothing.
+     */
+    function EssayDocument({ sections, ...header }) {
+        // Resolved once and shared, so the index and the sections cannot disagree
+        // about what a section is called.
+        const ids = anchorIds(sections);
+        return (_jsxs("article", { children: [_jsx(EssayHeader, { ...header }), _jsx(EssayLayout, { index: sections.map((s, i) => ({ id: ids[i], label: s.heading })), children: sections.map((s, i) => (_jsx(EssaySection, { id: ids[i], heading: s.heading, children: typeof s.body === "string" ? (_jsx(TypographyProse, { children: s.body })) : (s.body) }, ids[i]))) })] }));
+    }
+    return {
+        EssayHeader,
+        EssayLayout,
+        EssaySection,
+        EssayPullQuote,
+        EssayFigure,
+        EssayMovements,
+        EssayDocument,
+    };
+}
+/**
+ * The undecorated shell, bound once.
+ *
+ * The factory takes an app's motion and gradient, and an app that has neither
+ * still had to call it — at module scope, passing nothing — because there was
+ * no other way to reach the components. These are that call, made here, so a
+ * consumer without decorations imports them by name like the rest of the
+ * package. `createEssay` stays for the consumers that do decorate.
+ *
+ * Module scope is not incidental. The factory defines its components per call,
+ * so one made during a render hands React a new type on every pass and remounts
+ * everything under it.
+ */
+export const { EssayHeader, EssayLayout, EssaySection, EssayPullQuote, EssayFigure, EssayMovements, EssayDocument, } = createEssay();

package/dist/essay/index.d.ts

@@ -0,0 +1,7 @@
+export { extractHeadings, createSlugger, readingTime, type TocHeading, } from "./toc.js";
+export { Rail, RailLink } from "./rail.js";
+export { TableOfContents } from "./contents.js";
+export { createEssay, EssayHeader, EssayLayout, EssaySection, EssayPullQuote, EssayFigure, EssayMovements, EssayDocument, type EssayDecorations, type EssayIndexEntry, type EssayDocSection, type EssayMovement, } from "./essay.js";
+export { useReadingProgress, useScrollSpy } from "./scroll.js";
+export { ReadingProgressBar, ReadingRail } from "./reading.js";
+export { EssayColumns, MetaDot, PostMetaRow, PostDate, formatPostDate, type PostDateFormat, ReadTime, TagPills, } from "./layout.js";

package/dist/essay/index.js

@@ -0,0 +1,9 @@
+export { extractHeadings, createSlugger, readingTime, } from "./toc.js";
+export { Rail, RailLink } from "./rail.js";
+export { TableOfContents } from "./contents.js";
+export { createEssay, 
+// The undecorated binding, for a consumer that supplies neither Reveal nor Glow.
+EssayHeader, EssayLayout, EssaySection, EssayPullQuote, EssayFigure, EssayMovements, EssayDocument, } from "./essay.js";
+export { useReadingProgress, useScrollSpy } from "./scroll.js";
+export { ReadingProgressBar, ReadingRail } from "./reading.js";
+export { EssayColumns, MetaDot, PostMetaRow, PostDate, formatPostDate, ReadTime, TagPills, } from "./layout.js";

package/dist/essay/layout.d.ts

@@ -0,0 +1,72 @@
+import type { ComponentProps, ComponentType, ReactNode } from "react";
+/**
+ * Three tracks with the third empty: two would push the prose off-centre the
+ * moment an aside appeared, setting body copy on a different axis per page.
+ * The measure grows per step — a comfortable line length is a range.
+ *
+ * The margin track is what the third one buys, and it only exists if the
+ * container can pay for it:
+ *
+ *   aside = (container − 3rem padding − measure) ÷ 2 − 2.5rem gutter
+ *
+ * At 72rem, the grid's own first cap, that is 11rem — enough for a rail. At
+ * `lg` (64rem), where this used to switch on, it is 7rem, and a `text-sm` label
+ * past about thirteen characters wraps. So the reveal is pinned to the width
+ * the three tracks were drawn for rather than to a viewport step that happens
+ * to be near it.
+ *
+ * A container query, not a media query, because the answer depends on the room
+ * this shell was given and not on the size of the window. Mounted in something
+ * narrower — a docs page with its own 64rem column — it now drops the rail and
+ * sets the prose centred, which is a layout, where before it drew a 5.5rem
+ * margin and called it one.
+ */
+export declare function EssayColumns({ aside, children, className, ...props }: ComponentProps<"div"> & {
+    aside?: ReactNode;
+}): import("react").JSX.Element;
+/** A separator between meta items. Decorative, so it is hidden from assistive tech. */
+export declare function MetaDot({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** The row of meta beneath a title: byline, date, reading time, tags. */
+export declare function PostMetaRow({ className, children, size, ...props }: ComponentProps<"div"> & {
+    size?: "sm" | "base";
+}): import("react").JSX.Element;
+declare const DATE_FMT: {
+    readonly short: Intl.DateTimeFormat;
+    readonly long: Intl.DateTimeFormat;
+};
+export type PostDateFormat = keyof typeof DATE_FMT;
+/**
+ * The date string, outside React. An OG image builds one in a plain function and
+ * the index builds one in a component; two formatters is how the two drift.
+ *
+ * Fixed to `en-US`, not the visitor's locale: server and client must agree or
+ * React reports a hydration mismatch, and the server cannot see their locale.
+ * The index abbreviates because its dates sit inside a card's metadata line; an
+ * article spells the month out under a display title.
+ */
+export declare const formatPostDate: (date: string | Date, format?: PostDateFormat) => string;
+/** `<time datetime>` carries the machine value beside the human one. */
+export declare function PostDate({ date, format, className, }: {
+    date: string | Date;
+    format?: PostDateFormat;
+    className?: string;
+}): import("react").JSX.Element | null;
+/**
+ * Estimated reading time. Pair with `readingTime()` from the toc module.
+ * `icon` is injected, so the package needs no icon set of its own.
+ */
+export declare function ReadTime({ minutes, icon: Icon, className, }: {
+    minutes: number;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    className?: string;
+}): import("react").JSX.Element;
+/** Topic tags, as quiet pills. */
+export declare function TagPills({ tags, className, }: {
+    tags: readonly string[];
+    className?: string;
+}): import("react").JSX.Element | null;
+export {};

package/dist/essay/layout.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../cn.js";
+/**
+ * Three tracks with the third empty: two would push the prose off-centre the
+ * moment an aside appeared, setting body copy on a different axis per page.
+ * The measure grows per step — a comfortable line length is a range.
+ *
+ * The margin track is what the third one buys, and it only exists if the
+ * container can pay for it:
+ *
+ *   aside = (container − 3rem padding − measure) ÷ 2 − 2.5rem gutter
+ *
+ * At 72rem, the grid's own first cap, that is 11rem — enough for a rail. At
+ * `lg` (64rem), where this used to switch on, it is 7rem, and a `text-sm` label
+ * past about thirteen characters wraps. So the reveal is pinned to the width
+ * the three tracks were drawn for rather than to a viewport step that happens
+ * to be near it.
+ *
+ * A container query, not a media query, because the answer depends on the room
+ * this shell was given and not on the size of the window. Mounted in something
+ * narrower — a docs page with its own 64rem column — it now drops the rail and
+ * sets the prose centred, which is a layout, where before it drew a 5.5rem
+ * margin and called it one.
+ */
+export function EssayColumns({ aside, children, className, ...props }) {
+    return (_jsx("div", { className: "@container w-full", children: _jsxs("div", { className: cn("mx-auto grid w-full max-w-6xl gap-10 px-6", "@6xl:grid-cols-[1fr_minmax(0,42rem)_1fr] @6xl:gap-0", "@7xl:max-w-7xl @7xl:grid-cols-[1fr_minmax(0,44rem)_1fr]", "@min-[84rem]:max-w-[84rem] @min-[84rem]:grid-cols-[1fr_minmax(0,46rem)_1fr]", className), ...props, children: [_jsx("div", { className: "hidden @6xl:block @6xl:pr-10", children: aside }), _jsx("div", { className: "mx-auto w-full min-w-0 max-w-2xl @6xl:max-w-none", children: children }), _jsx("div", { className: "hidden @6xl:block" })] }) }));
+}
+/** A separator between meta items. Decorative, so it is hidden from assistive tech. */
+export function MetaDot({ className }) {
+    return (_jsx("span", { "aria-hidden": true, className: cn("text-muted-foreground/50", className), children: "\u00B7" }));
+}
+/** The row of meta beneath a title: byline, date, reading time, tags. */
+export function PostMetaRow({ className, children, size = "base", ...props }) {
+    return (_jsx("div", { className: cn("flex flex-wrap items-center gap-x-2 text-muted-foreground", size === "sm" ? "text-xs" : "text-sm", className), ...props, children: children }));
+}
+const DATE_FMT = {
+    short: new Intl.DateTimeFormat("en-US", {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    }),
+    long: new Intl.DateTimeFormat("en-US", {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+    }),
+};
+/**
+ * The date string, outside React. An OG image builds one in a plain function and
+ * the index builds one in a component; two formatters is how the two drift.
+ *
+ * Fixed to `en-US`, not the visitor's locale: server and client must agree or
+ * React reports a hydration mismatch, and the server cannot see their locale.
+ * The index abbreviates because its dates sit inside a card's metadata line; an
+ * article spells the month out under a display title.
+ */
+export const formatPostDate = (date, format = "short") => DATE_FMT[format].format(typeof date === "string" ? new Date(date) : date);
+/** `<time datetime>` carries the machine value beside the human one. */
+export function PostDate({ date, format, className, }) {
+    const value = typeof date === "string" ? new Date(date) : date;
+    if (Number.isNaN(value.getTime()))
+        return null;
+    return (_jsx("time", { dateTime: value.toISOString(), className: className, children: formatPostDate(value, format) }));
+}
+/**
+ * Estimated reading time. Pair with `readingTime()` from the toc module.
+ * `icon` is injected, so the package needs no icon set of its own.
+ */
+export function ReadTime({ minutes, icon: Icon, className, }) {
+    return (_jsxs("span", { className: cn("inline-flex items-center gap-1", className), children: [Icon && _jsx(Icon, { className: "size-3.5" }), minutes, " min read"] }));
+}
+/** Topic tags, as quiet pills. */
+export function TagPills({ tags, className, }) {
+    if (tags.length === 0)
+        return null;
+    return (_jsx("span", { className: cn("flex flex-wrap gap-1.5", className), children: tags.map((tag) => (_jsx("span", { className: "rounded-full bg-primary/15 px-2.5 py-0.5 text-xs font-medium text-primary", children: tag }, tag))) }));
+}

package/dist/essay/rail.d.ts

@@ -0,0 +1,15 @@
+import { type ComponentProps, type ReactElement, type ReactNode } from "react";
+/**
+ * The line is drawn once on the list, with the active item marking itself with a
+ * thumb on top — a border per link breaks the rail into segments that jump on
+ * hover. No client hooks, so a server-rendered listing can use it.
+ */
+export declare function Rail({ className, ...props }: ComponentProps<"ul">): import("react").JSX.Element;
+export declare function RailLink({ active, nested, className, children, render, ...props }: Omit<ComponentProps<"a">, "children"> & {
+    active?: boolean;
+    /** A sub-heading under the item above it, indented a step further in. */
+    nested?: boolean;
+    children: ReactNode;
+    /** Swap the anchor for another link element, e.g. `<Link href={…} />`. */
+    render?: ReactElement<ComponentProps<"a">>;
+}): import("react").JSX.Element;

package/dist/essay/rail.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cloneElement } from "react";
+import { cn } from "../cn.js";
+/**
+ * The line is drawn once on the list, with the active item marking itself with a
+ * thumb on top — a border per link breaks the rail into segments that jump on
+ * hover. No client hooks, so a server-rendered listing can use it.
+ */
+export function Rail({ className, ...props }) {
+    return (_jsx("ul", { className: cn("flex flex-col border-l border-border", className), ...props }));
+}
+export function RailLink({ active = false, nested = false, className, children, render, ...props }) {
+    const anchor = {
+        ...props,
+        "aria-current": active ? "page" : undefined,
+        className: cn("relative block py-1 text-sm leading-snug transition-colors", nested ? "pl-6" : "pl-3", 
+        // The thumb overlaps the list's hairline rather than replacing it, so an
+        // inactive neighbour keeps its line and nothing shifts when the active
+        // item changes.
+        "before:absolute before:inset-y-1 before:-left-px before:w-0.5 before:rounded-full before:bg-primary before:opacity-0 before:transition-opacity", active
+            ? "font-medium text-primary before:opacity-100"
+            : "text-muted-foreground hover:text-foreground", className),
+        children,
+    };
+    return _jsx("li", { children: render ? cloneElement(render, anchor) : _jsx("a", { ...anchor }) });
+}

package/dist/essay/reading.d.ts

@@ -0,0 +1,17 @@
+import type { TocHeading } from "./toc.js";
+/**
+ * Hairline progress bar, rendered even where the rail is hidden. A CSS
+ * transition, not a spring: the value only feeds a transform, and this keeps the
+ * essay layer from dragging in an animation runtime.
+ */
+export declare function ReadingProgressBar({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * Sticky rail with live scroll-spy. Both it and `ReadingProgressBar` read shared
+ * stores, so mounting them together costs one scroll subscription, not two.
+ */
+export declare function ReadingRail({ headings, className, }: {
+    headings: TocHeading[];
+    className?: string;
+}): import("react").JSX.Element | null;