@supertype.ai/foundations 0.1.24

package/dist/essay/reading.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../cn.js";
+import { Rail, RailLink } from "./rail.js";
+import { useReadingProgress, useScrollSpy } from "./scroll.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 function ReadingProgressBar({ className }) {
+    const progress = useReadingProgress();
+    return (_jsx("div", { "aria-hidden": true, className: cn("fixed inset-x-0 top-0 z-[60] h-0.5 origin-left bg-primary", "transition-transform duration-150 ease-out", className), style: { transform: `scaleX(${progress})` } }));
+}
+/** Circular percentage indicator at the head of the rail. */
+function ProgressDonut({ progress }) {
+    const radius = 16;
+    const circumference = 2 * Math.PI * radius;
+    return (_jsxs("div", { className: "relative grid size-10 place-items-center", children: [_jsxs("svg", { viewBox: "0 0 40 40", className: "size-10 -rotate-90", "aria-hidden": true, children: [_jsx("circle", { cx: "20", cy: "20", r: radius, fill: "none", strokeWidth: "3", className: "stroke-border" }), _jsx("circle", { cx: "20", cy: "20", r: radius, fill: "none", strokeWidth: "3", strokeLinecap: "round", className: "stroke-primary transition-[stroke-dashoffset] duration-150 ease-out", strokeDasharray: circumference, strokeDashoffset: circumference * (1 - progress) })] }), _jsx("span", { className: "absolute font-mono text-3xs font-medium tabular-nums text-muted-foreground", children: Math.round(progress * 100) })] }));
+}
+/**
+ * Sticky rail with live scroll-spy. Both it and `ReadingProgressBar` read shared
+ * stores, so mounting them together costs one scroll subscription, not two.
+ */
+export function ReadingRail({ headings, className, }) {
+    const progress = useReadingProgress();
+    const active = useScrollSpy(headings.map((h) => h.id));
+    if (headings.length === 0)
+        return null;
+    return (_jsxs("nav", { "aria-label": "On this page", className: cn("flex flex-col gap-4", className), children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx(ProgressDonut, { progress: progress }), _jsx("p", { className: "text-xs font-medium uppercase tracking-widest text-muted-foreground", children: "On this page" })] }), _jsx(Rail, { children: headings.map(({ id, label, depth }) => (_jsx(RailLink, { href: `#${id}`, active: active === id, nested: depth === 3, children: label }, id))) })] }));
+}

package/dist/essay/scroll.d.ts

@@ -0,0 +1,8 @@
+export declare function useReadingProgress(): number;
+/**
+ * One IntersectionObserver across all headings, not one each — the observer
+ * already reports what changed. Topmost wins when several are on screen.
+ */
+export declare function useScrollSpy(ids: string[], { rootMargin }?: {
+    rootMargin?: string;
+}): string;

package/dist/essay/scroll.js

@@ -0,0 +1,78 @@
+"use client";
+import { useEffect, useState, useSyncExternalStore } from "react";
+/**
+ * Reading progress 0→1 from one shared listener: a page mounts both the bar and
+ * the rail, and hook-local state would double every subscription. Reads coalesce
+ * to a frame, since `scrollHeight` forces layout.
+ */
+let progress = 0;
+let frame = 0;
+const listeners = new Set();
+function measure() {
+    frame = 0;
+    const scrollable = document.documentElement.scrollHeight - window.innerHeight;
+    const next = scrollable > 0 ? window.scrollY / scrollable : 0;
+    const clamped = Math.min(1, Math.max(0, next));
+    if (clamped === progress)
+        return;
+    progress = clamped;
+    listeners.forEach((l) => l());
+}
+function schedule() {
+    if (frame)
+        return;
+    frame = requestAnimationFrame(measure);
+}
+function subscribe(listener) {
+    if (listeners.size === 0) {
+        window.addEventListener("scroll", schedule, { passive: true });
+        window.addEventListener("resize", schedule);
+        measure();
+    }
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+            window.removeEventListener("scroll", schedule);
+            window.removeEventListener("resize", schedule);
+            if (frame)
+                cancelAnimationFrame(frame);
+            frame = 0;
+        }
+    };
+}
+export function useReadingProgress() {
+    // The server snapshot is 0, an unscrolled document. That is also the client's
+    // value on first paint, so the two agree.
+    return useSyncExternalStore(subscribe, () => progress, () => 0);
+}
+/**
+ * One IntersectionObserver across all headings, not one each — the observer
+ * already reports what changed. Topmost wins when several are on screen.
+ */
+export function useScrollSpy(ids, { rootMargin = "-15% 0px -75% 0px" } = {}) {
+    const [active, setActive] = useState("");
+    // Depend on the joined ids rather than the array: a caller that maps headings
+    // inline passes a new array identity every render, which would tear the
+    // observer down and rebuild it on each one.
+    const key = ids.join("|");
+    useEffect(() => {
+        const elements = key
+            .split("|")
+            .filter(Boolean)
+            .map((id) => document.getElementById(id))
+            .filter((el) => el !== null);
+        if (elements.length === 0)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            const visible = entries
+                .filter((e) => e.isIntersecting)
+                .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+            if (visible[0])
+                setActive(visible[0].target.id);
+        }, { rootMargin });
+        elements.forEach((el) => observer.observe(el));
+        return () => observer.disconnect();
+    }, [key, rootMargin]);
+    return active;
+}

package/dist/essay/toc.d.ts

@@ -0,0 +1,23 @@
+/** A heading in the table of contents. */
+export interface TocHeading {
+    /** 2 = h2 (top level), 3 = h3 (nested). */
+    depth: 2 | 3;
+    /** Matches the id rehype-slug stamps on the heading, so anchors line up. */
+    id: string;
+    label: string;
+}
+/**
+ * GitHub's slug algorithm, reimplemented. Must agree exactly with rehype-slug or
+ * the rail's anchors point at headings that do not exist.
+ */
+export declare function createSlugger(): (value: string) => string;
+/**
+ * h2/h3 from raw markdown. Fenced code is skipped — a `# comment` in a shell
+ * block is not a heading. Works on source, so it needs no DOM or compiled MDX.
+ */
+export declare function extractHeadings(markdown: string): TocHeading[];
+/**
+ * Computed, never stored: a hand-declared `readingMinutes` is correct once.
+ * 200 wpm, code blocks excluded — counting them inflates every technical post.
+ */
+export declare function readingTime(source: string, wordsPerMinute?: number): number;

package/dist/essay/toc.js

@@ -0,0 +1,50 @@
+/**
+ * GitHub's slug algorithm, reimplemented. Must agree exactly with rehype-slug or
+ * the rail's anchors point at headings that do not exist.
+ */
+export function createSlugger() {
+    const seen = new Map();
+    return (value) => {
+        const base = value
+            .toLowerCase()
+            .trim()
+            .replace(/[^\w\s-]/g, "")
+            .replace(/\s+/g, "-");
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        return count === 0 ? base : `${base}-${count}`;
+    };
+}
+/**
+ * h2/h3 from raw markdown. Fenced code is skipped — a `# comment` in a shell
+ * block is not a heading. Works on source, so it needs no DOM or compiled MDX.
+ */
+export function extractHeadings(markdown) {
+    const slug = createSlugger();
+    const headings = [];
+    let inFence = false;
+    for (const line of markdown.split("\n")) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = /^(#{2,3})\s+(.+?)\s*$/.exec(line);
+        if (!match)
+            continue;
+        const depth = match[1].length;
+        const label = match[2].replace(/[*_`]/g, "").trim();
+        headings.push({ depth, id: slug(label), label });
+    }
+    return headings;
+}
+/**
+ * Computed, never stored: a hand-declared `readingMinutes` is correct once.
+ * 200 wpm, code blocks excluded — counting them inflates every technical post.
+ */
+export function readingTime(source, wordsPerMinute = 200) {
+    const prose = source.replace(/```[\s\S]*?```/g, " ");
+    const words = prose.trim() ? prose.trim().split(/\s+/).length : 0;
+    return Math.max(1, Math.round(words / wordsPerMinute));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { cn } from "./cn.js";
+export * from "./typography/index.js";

package/dist/index.js

@@ -0,0 +1,33 @@
+export { cn } from "./cn.js";
+export * from "./typography/index.js";
+// NOTE: blocks, the MDX map, and the Shiki plugin are all deliberately absent
+// from this barrel.
+//
+// A barrel's transitive dependencies are paid by every name it exports. mdx.tsx
+// imports `next/image`, and a bare subpath like that fails to resolve from
+// inside node_modules under a plain Node ESM loader, which is the loader a
+// consumer's test runner uses. Pulling it in here made every test that touches a
+// Typography component fail to import.
+//
+// blocks/ carries the same hazard one dependency over: interactive-accordion.tsx
+// and tabs.tsx pull `@base-ui/react`, so re-exporting them made a bare
+// `import { TypographyH2 }` resolve Base UI. They live at
+// "@supertype.ai/foundations/blocks" for that reason, not for tree-shaking — the
+// bundlers already handle that.
+//
+// What the split does NOT buy is a plain-Node-importable root. Measured, not
+// assumed: `node -e "import('@supertype.ai/foundations')"` from a consumer fails on
+// ERR_MODULE_NOT_FOUND for next/link, because TypographyLink imports
+// `next-view-transitions`, whose dist/index.js:3 imports `next/link` — the same
+// unresolvable bare subpath as next/image above, one package further out. The
+// blocks entry fails identically through card.tsx.
+//
+// This is survivable because the runner that matters resolves it: both consumers'
+// vitest suites import typography freely and pass. Do not "fix" it by reinstating
+// injection — that was tried, and paragraph.tsx documents the call site it
+// silently left unbound. Isolating it would mean a /next subpath for
+// TypographyLink and Card, against ~230 and ~100 call sites.
+//
+// The Shiki plugin has build-time consumers (source.config.ts, next.config) that
+// run in bare Node where React is not resolvable. Import it from
+// "@supertype.ai/foundations/rehype".

package/dist/injection.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentType } from "react";
+/**
+ * A component the app injects — its Link, its Image. Untyped in its props on
+ * purpose: no hand-written signature accepts `next/link`, `next/image` and
+ * react-router at once, and tightening it only moves the cast to every consumer.
+ * What must hold is checked where these are rendered, against a fixed prop set.
+ */
+export type InjectedComponent = ComponentType<any>;

package/dist/injection.js

@@ -0,0 +1 @@
+export {};

package/dist/mdx.d.ts

@@ -0,0 +1,47 @@
+import type { ComponentProps } from "react";
+import { Disclosure, DisclosureGroup } from "./blocks/accordion.js";
+import { Callout } from "./blocks/callout.js";
+import { Card, Cards } from "./blocks/card.js";
+import { Step, Steps } from "./blocks/steps.js";
+import { TabGroup, Tab } from "./blocks/tabs.js";
+/**
+ * Rendered from markdown syntax, so there is no call site and no knob — a knob
+ * here is one every project turns differently. Headings carry variants and this
+ * map binds them; retune in CSS by moving the `--text-*` rung, or with
+ * `.editorial` over the subtree.
+ *
+ * A constant rather than a factory: the router and the image component are the
+ * package's now, so there is nothing left for a consumer to inject.
+ */
+export declare const proseMdxComponents: {
+    Card: typeof Card;
+    Cards: typeof Cards;
+    Accordions: typeof DisclosureGroup;
+    Accordion: typeof Disclosure;
+    Banner: (props: ComponentProps<typeof Callout>) => import("react").JSX.Element;
+    Tabs: typeof TabGroup;
+    Tab: typeof Tab;
+    Steps: typeof Steps;
+    Step: typeof Step;
+    h1: (props: ComponentProps<"h1">) => import("react").JSX.Element;
+    h2: (props: ComponentProps<"h2">) => import("react").JSX.Element;
+    h3: (props: ComponentProps<"h3">) => import("react").JSX.Element;
+    h4: (props: ComponentProps<"h4">) => import("react").JSX.Element;
+    p: (props: ComponentProps<"p">) => import("react").JSX.Element;
+    ul: (props: ComponentProps<"ul">) => import("react").JSX.Element;
+    ol: (props: ComponentProps<"ol">) => import("react").JSX.Element;
+    li: (props: ComponentProps<"li">) => import("react").JSX.Element;
+    blockquote: ({ className, ...props }: ComponentProps<"blockquote">) => import("react").JSX.Element;
+    a: ({ href, children }: ComponentProps<"a">) => import("react").JSX.Element;
+    /**
+     * The frame only — never set `color`, or it beats shiki's token spans.
+     * `tabIndex` keeps a horizontally scrolling block reachable by keyboard.
+     */
+    pre: ({ className, ...props }: ComponentProps<"pre">) => import("react").JSX.Element;
+    img: ({ alt, src, width, height, ...props }: ComponentProps<"img">) => import("react").JSX.Element;
+    hr: () => import("react").JSX.Element;
+    strong: (props: ComponentProps<"strong">) => import("react").JSX.Element;
+    table: (props: ComponentProps<"table">) => import("react").JSX.Element;
+    th: (props: ComponentProps<"th">) => import("react").JSX.Element;
+    td: (props: ComponentProps<"td">) => import("react").JSX.Element;
+};

package/dist/mdx.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TypographyH1, TypographyH2, TypographyH3, TypographyH4, } from "./typography/header.js";
+import { cn } from "./cn.js";
+import Image from "next/image";
+import { Disclosure, DisclosureGroup } from "./blocks/accordion.js";
+import { Callout } from "./blocks/callout.js";
+import { Card, Cards } from "./blocks/card.js";
+import { Step, Steps } from "./blocks/steps.js";
+import { TabGroup, Tab } from "./blocks/tabs.js";
+import { TypographyProse, TypographyProseList, TypographyLink, } from "./typography/paragraph.js";
+/**
+ * Rendered from markdown syntax, so there is no call site and no knob — a knob
+ * here is one every project turns differently. Headings carry variants and this
+ * map binds them; retune in CSS by moving the `--text-*` rung, or with
+ * `.editorial` over the subtree.
+ *
+ * A constant rather than a factory: the router and the image component are the
+ * package's now, so there is nothing left for a consumer to inject.
+ */
+export const proseMdxComponents = {
+    // Authorable blocks. Unlike the elements below these ARE called by hand in
+    // MDX, so they take props — but never a `className`: an author writing
+    // <Card> is choosing a component, not restyling one.
+    Card,
+    Cards,
+    Accordions: DisclosureGroup,
+    Accordion: Disclosure,
+    Banner: (props) => (_jsx(Callout, { density: "editorial", ...props })),
+    Tabs: TabGroup,
+    Tab,
+    Steps,
+    Step,
+    h1: (props) => (_jsx(TypographyH1, { variant: "display", ...props })),
+    h2: (props) => _jsx(TypographyH2, { ...props }),
+    h3: (props) => _jsx(TypographyH3, { ...props }),
+    h4: (props) => _jsx(TypographyH4, { ...props }),
+    p: (props) => _jsx(TypographyProse, { ...props }),
+    ul: (props) => _jsx(TypographyProseList, { ...props }),
+    ol: (props) => (_jsx(TypographyProseList, { ordered: true, ...props })),
+    li: (props) => (_jsx("li", { className: "[&>ul]:mt-2 [&>ol]:mt-2", ...props })),
+    // No quotemark glyph: a markdown `>` block is already marked as a quote by
+    // its rule and its indent, and a mark on top of that reads as decoration.
+    blockquote: ({ className, ...props }) => (_jsx("blockquote", { className: cn("my-6 border-l-[3px] border-border pl-5 text-lg italic leading-relaxed text-foreground", className), ...props })),
+    a: ({ href = "", children }) => (_jsx(TypographyLink, { href: href, children: children })),
+    /**
+     * The frame only — never set `color`, or it beats shiki's token spans.
+     * `tabIndex` keeps a horizontally scrolling block reachable by keyboard.
+     */
+    pre: ({ className, ...props }) => (_jsx("pre", { tabIndex: 0, className: cn("my-6 overflow-x-auto rounded-xl border border-border p-4 text-sm leading-relaxed", "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className), ...props })),
+    img: ({ alt = "", src, width, height, ...props }) => {
+        const className = "my-6 h-auto max-w-full rounded-xl border border-border";
+        // `next/image` needs a real src and intrinsic dimensions, which a markdown
+        // `![](…)` lacks unless a remark plugin measured them. The plain `<img>` is
+        // the fallback for when it did not.
+        const w = Number(width);
+        const h = Number(height);
+        if (typeof src === "string" && w > 0 && h > 0) {
+            return (_jsx(Image, { src: src, width: w, height: h, alt: alt, className: className, ...props }));
+        }
+        // eslint-disable-next-line @next/next/no-img-element
+        return (_jsx("img", { src: typeof src === "string" ? src : undefined, width: width, height: height, alt: alt, className: className, ...props }));
+    },
+    hr: () => _jsx("hr", { className: "my-12 border-border" }),
+    strong: (props) => (_jsx("strong", { className: "font-semibold text-foreground", ...props })),
+    table: (props) => (_jsx("div", { className: "mt-6 overflow-x-auto rounded-xl border border-border", children: _jsx("table", { className: "w-full border-collapse text-sm", ...props }) })),
+    th: (props) => (_jsx("th", { className: "border-b border-border bg-muted/40 px-4 py-2.5 text-left font-semibold text-foreground", ...props })),
+    td: (props) => (_jsx("td", { className: "border-b border-border/60 px-4 py-2.5 align-top text-muted-foreground", ...props })),
+};

package/dist/og.d.ts

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+/** Open Graph card dimensions. The 1.91:1 ratio every major network crops to. */
+export declare const OG_SIZE: {
+    readonly width: 1200;
+    readonly height: 630;
+};
+export interface OgCardOptions {
+    title: string;
+    description?: string;
+    /** The site or brand name, set small at the foot of the card. */
+    site?: string;
+    /** Accent colour for the rule and the site name. Any CSS colour. */
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+}
+export declare function ogCard({ title, description, site, accent, background, foreground, muted, }: OgCardOptions): ReactElement;

package/dist/og.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Open Graph card dimensions. The 1.91:1 ratio every major network crops to. */
+export const OG_SIZE = { width: 1200, height: 630 };
+/** Measured, not guessed: ~45 chars/line at 62px over three lines, two at 28px. */
+const TITLE_MAX = 135;
+const DESCRIPTION_MAX = 160;
+/**
+ * A tree, not an image, so the package never imports `next/og`. Rendered by
+ * satori: no stylesheets, no classes, no default block layout — hence inline
+ * styles and an explicit `display: flex` on everything. Text is truncated in JS
+ * because `-webkit-line-clamp` needs a display mode that contradicts the flex.
+ */
+/** Truncates on a word boundary, so a cut title does not end mid-word. */
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${(lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+export function ogCard({ title, description, site, accent = "#b1976b", background = "#0c0a09", foreground = "#fafaf9", muted = "#a8a29e", }) {
+    return (_jsxs("div", { style: {
+            width: "100%",
+            height: "100%",
+            display: "flex",
+            flexDirection: "column",
+            justifyContent: "space-between",
+            background,
+            padding: "72px",
+            fontFamily: "sans-serif",
+        }, children: [_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: "28px" }, children: [_jsx("div", { style: { display: "flex", width: "88px", height: "6px", background: accent } }), _jsx("div", { style: {
+                            display: "flex",
+                            fontSize: 62,
+                            fontWeight: 700,
+                            lineHeight: 1.15,
+                            letterSpacing: "-0.02em",
+                            color: foreground,
+                        }, children: truncate(title, TITLE_MAX) }), description ? (_jsx("div", { style: {
+                            display: "flex",
+                            fontSize: 28,
+                            lineHeight: 1.4,
+                            color: muted,
+                        }, children: truncate(description, DESCRIPTION_MAX) })) : null] }), site ? (_jsx("div", { style: {
+                    display: "flex",
+                    fontSize: 26,
+                    fontWeight: 600,
+                    letterSpacing: "0.04em",
+                    color: accent,
+                }, children: site })) : null] }));
+}

package/dist/rehype.d.ts

@@ -0,0 +1,18 @@
+import rehypeShiki, { type RehypeShikiOptions } from "@shikijs/rehype";
+/**
+ * Explicit rather than Shiki's full set — every grammar is build-time parsing.
+ * Anything unlisted falls back to `text`: content uses labels that are not real
+ * grammars (`tree`, `spark-defaults`), and dying over a fence label is a bad trade.
+ */
+export declare const PROSE_LANGS: readonly ["bash", "csv", "diff", "docker", "json", "python", "sql", "toml", "tsx", "typescript", "javascript", "yaml"];
+export declare const PROSE_THEMES: {
+    readonly light: "github-light";
+    readonly dark: "github-dark";
+};
+/**
+ * `defaultColor: false` emits `--shiki-light` / `--shiki-dark` per token instead
+ * of a baked colour, so one compiled document serves both themes; `shiki.css`
+ * maps them. A `[plugin, options]` tuple, so it drops into `rehypePlugins`.
+ */
+export declare const proseCodeOptions: RehypeShikiOptions;
+export declare const rehypeProseCode: [typeof rehypeShiki, RehypeShikiOptions];

package/dist/rehype.js

@@ -0,0 +1,41 @@
+import rehypeShiki, {} from "@shikijs/rehype";
+/**
+ * Explicit rather than Shiki's full set — every grammar is build-time parsing.
+ * Anything unlisted falls back to `text`: content uses labels that are not real
+ * grammars (`tree`, `spark-defaults`), and dying over a fence label is a bad trade.
+ */
+export const PROSE_LANGS = [
+    "bash",
+    "csv",
+    "diff",
+    "docker",
+    "json",
+    "python",
+    "sql",
+    "toml",
+    "tsx",
+    "typescript",
+    "javascript",
+    "yaml",
+];
+export const PROSE_THEMES = {
+    light: "github-light",
+    dark: "github-dark",
+};
+/**
+ * `defaultColor: false` emits `--shiki-light` / `--shiki-dark` per token instead
+ * of a baked colour, so one compiled document serves both themes; `shiki.css`
+ * maps them. A `[plugin, options]` tuple, so it drops into `rehypePlugins`.
+ */
+export const proseCodeOptions = {
+    themes: PROSE_THEMES,
+    defaultColor: false,
+    langs: [...PROSE_LANGS],
+    fallbackLanguage: "text",
+};
+// Typed as a mutable tuple, not `as const`: unified's `Pluggable` does not
+// accept a readonly tuple, and a readonly one fails to assign in consumers.
+export const rehypeProseCode = [
+    rehypeShiki,
+    proseCodeOptions,
+];