@elabs-ai/components-ui 4.0.0

package/src/components/typography/prose.tsx

@@ -0,0 +1,194 @@
+/**
+ * Prose primitives — reading-surface typography, promoted from @elabs-ai/components-editor
+ * (#188; ADR-0012 own/re-export model: @elabs-ai/components-ui owns the canonical source,
+ * `@elabs-ai/components-editor/markdown` re-exports them under their original names —
+ * Heading, Text, Link, List, Blockquote, InlineCode). The markdown preview maps
+ * onto them (`#` → ProseHeading, paragraph → ProseText, `[]()` → ProseLink,
+ * `-` → ProseList, `>` → ProseBlockquote, `` `code` `` → ProseInlineCode).
+ * Generic, composable, theme-safe; usable in any app surface, not just markdown.
+ *
+ * `Prose*`-prefixed here because this barrel also exports the app `Heading` /
+ * `Text` primitives (typography.tsx): the app scale ranks UI chrome against the
+ * page; the prose scale ranks rungs WITHIN one reading column, so a document h1
+ * deliberately sits BELOW the app `display` rung.
+ */
+import {
+  forwardRef,
+  type AnchorHTMLAttributes,
+  type HTMLAttributes,
+  type OlHTMLAttributes,
+} from "react";
+import { cn } from "../../lib/cn";
+import { TEXT_ROLE_REM } from "./typography";
+
+export type ProseHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * Canonical reading-scale heading sizes in rem — the single source the markdown
+ * WYSIWYG editor derives its CSS vars from (@elabs-ai/components-editor `markdown-scale`).
+ * h2/h4/h5/h6 sit exactly on the title/subtitle/body roles; h1 (1.5rem) and
+ * h3 (1.125rem) are intermediate reading rungs with no app role.
+ */
+export const PROSE_HEADING_REM: Record<ProseHeadingLevel, number> = {
+  1: 1.5,
+  2: TEXT_ROLE_REM.title,
+  3: 1.125,
+  4: TEXT_ROLE_REM.subtitle,
+  5: TEXT_ROLE_REM.body,
+  6: TEXT_ROLE_REM.body,
+};
+
+/** Canonical prose heading weight (Tailwind `font-semibold`). */
+export const PROSE_HEADING_WEIGHT = 600;
+
+/** Canonical prose heading letter-spacing (Tailwind `tracking-tight`). */
+export const PROSE_HEADING_TRACKING = "-0.025em";
+
+/*
+ * h1/h3 keep raw Tailwind steps (2xl / lg): the reading scale needs rungs
+ * BETWEEN the app roles (see PROSE_HEADING_REM) — baselined in the text-scale
+ * ratchet. The base classes' font-semibold / tracking-tight override the role
+ * companions, so the role re-points are render-identical to the old raw steps.
+ */
+const HEADING_SIZE: Record<ProseHeadingLevel, string> = {
+  1: "text-2xl",
+  2: "text-title",
+  3: "text-lg",
+  4: "text-subtitle",
+  5: "text-body",
+  6: "text-body text-muted-foreground",
+};
+
+export interface ProseHeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  level?: ProseHeadingLevel;
+}
+
+export const ProseHeading = forwardRef<HTMLHeadingElement, ProseHeadingProps>(function ProseHeading(
+  { level = 2, className, ...props },
+  ref,
+) {
+  const Tag = `h${level}` as const;
+  return (
+    <Tag
+      ref={ref}
+      className={cn(
+        "scroll-m-20 font-semibold tracking-tight text-foreground",
+        HEADING_SIZE[level],
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+const TEXT_VARIANT = {
+  body: "text-body leading-relaxed text-foreground",
+  muted: "text-body leading-relaxed text-muted-foreground",
+  lead: "text-subtitle font-normal leading-relaxed text-foreground",
+  small: "text-meta font-normal text-muted-foreground",
+} as const;
+
+export interface ProseTextProps extends HTMLAttributes<HTMLParagraphElement> {
+  variant?: keyof typeof TEXT_VARIANT;
+  /** Render as a different element (e.g. "span"). Defaults to "p". */
+  as?: "p" | "span" | "div";
+}
+
+export const ProseText = forwardRef<HTMLParagraphElement, ProseTextProps>(function ProseText(
+  { variant = "body", as: Tag = "p", className, ...props },
+  ref,
+) {
+  return <Tag ref={ref} className={cn(TEXT_VARIANT[variant], className)} {...props} />;
+});
+
+export interface ProseLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  /** Opens in a new tab with safe rel. Auto-detected for http(s) hrefs when unset. */
+  external?: boolean;
+}
+
+export const ProseLink = forwardRef<HTMLAnchorElement, ProseLinkProps>(function ProseLink(
+  { external, href, className, ...props },
+  ref,
+) {
+  const isExternal = external ?? (typeof href === "string" && /^https?:\/\//.test(href));
+  return (
+    <a
+      ref={ref}
+      href={href}
+      className={cn(
+        // #399 — `text-primary-text`, not the `text-primary` FILL rung: a prose
+        // link is ordinary body text and owes WCAG 1.4.3 AA (4.5:1), which the
+        // fill only guarantees at the 1.4.11 mark bar (3:1).
+        "font-medium text-primary-text underline underline-offset-4 hover:no-underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+      {...(isExternal ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+      {...props}
+    />
+  );
+});
+
+export interface ProseListProps extends OlHTMLAttributes<HTMLElement> {
+  ordered?: boolean;
+}
+
+export const ProseList = forwardRef<HTMLUListElement & HTMLOListElement, ProseListProps>(
+  function ProseList({ ordered = false, className, ...props }, ref) {
+    const Tag = ordered ? "ol" : "ul";
+    return (
+      <Tag
+        ref={ref}
+        className={cn(
+          "my-1 space-y-1 ps-6 text-body text-foreground",
+          ordered ? "list-decimal" : "list-disc",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+export const ProseListItem = forwardRef<HTMLLIElement, HTMLAttributes<HTMLLIElement>>(
+  function ProseListItem({ className, ...props }, ref) {
+    return (
+      <li
+        ref={ref}
+        className={cn("leading-relaxed [&>ul]:mt-1 [&>ol]:mt-1", className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export const ProseBlockquote = forwardRef<HTMLQuoteElement, HTMLAttributes<HTMLQuoteElement>>(
+  function ProseBlockquote({ className, ...props }, ref) {
+    return (
+      <blockquote
+        ref={ref}
+        className={cn(
+          "border-s-2 border-border ps-4 text-body italic text-muted-foreground",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+export const ProseInlineCode = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(
+  function ProseInlineCode({ className, ...props }, ref) {
+    return (
+      <code
+        ref={ref}
+        // 0.85em (not the fixed `code` role): inline code must scale RELATIVE to
+        // whatever text it sits in (body, a heading, …). Baselined in the ratchet.
+        className={cn(
+          "rounded bg-muted px-1.5 py-0.5 font-mono text-[0.85em] text-foreground",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);

package/src/components/typography/typography.stories.tsx

@@ -0,0 +1,244 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { Heading, Text } from "./typography";
+import {
+  ProseBlockquote,
+  ProseHeading,
+  ProseInlineCode,
+  ProseLink,
+  ProseList,
+  ProseListItem,
+  ProseText,
+} from "./prose";
+
+const meta = {
+  title: "Foundations/Typography",
+  component: Text,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The semantic type-role API (#187/#188): `Heading` maps a level to the " +
+          "display/title/subtitle rungs; `Text` maps intent (lead/body/caption/meta/kpi/code) " +
+          "to a role. Roles bundle size + leading + weight + tracking and stay composable. " +
+          "`Prose*` primitives carry the reading-column scale the markdown preview maps onto.\n\n" +
+          '**Type is density-aware** (#340): `data-density="compact"` shrinks the whole scale ' +
+          "(−6.25%) as well as the spacing, and `spacious` grows it (+6.25%) — see the " +
+          "*Density scale* story. `comfortable` is the exact identity.\n\n" +
+          "**Font smoothing ships with the tokens stylesheet** (#345): the `@layer base` `body` rule in " +
+          "`@elabs-ai/components-tokens/styles.css` sets `-webkit-font-smoothing: antialiased` and " +
+          "`-moz-osx-font-smoothing: grayscale`, so every consumer inherits it from the one import. Do not " +
+          "re-add those two lines in an app stylesheet. It is a base-layer rule, so an app that genuinely " +
+          "wants subpixel rendering can still override it.",
+      },
+    },
+  },
+} satisfies Meta<typeof Text>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: "Body text — the default role (text-body == text-sm by design)." },
+};
+
+export const TextVariants: Story = {
+  render: () => (
+    <div className="max-w-2xl space-y-3">
+      <Text variant="lead">Lead — a lead paragraph: the subtitle rung at body weight.</Text>
+      <Text variant="body">Body — default reading text for app surfaces.</Text>
+      <Text variant="caption">Caption — secondary / supporting body.</Text>
+      <Text variant="meta">Meta — metadata, eyebrows, timestamps.</Text>
+      <Text variant="kpi">12,480</Text>
+      <Text variant="code">pnpm --filter @elabs-ai/components-ui test</Text>
+    </div>
+  ),
+};
+
+export const Tones: Story = {
+  render: () => (
+    <div className="space-y-2">
+      <Text tone="default">Default tone — foreground.</Text>
+      <Text tone="muted">Muted tone — secondary information.</Text>
+      <Text tone="primary">Primary tone — brand emphasis.</Text>
+    </div>
+  ),
+};
+
+export const Headings: Story = {
+  render: () => (
+    <div className="space-y-3">
+      <Heading level={1}>Level 1 — display</Heading>
+      <Heading level={2}>Level 2 — title</Heading>
+      <Heading level={3}>Level 3 — title</Heading>
+      <Heading level={4}>Level 4 — subtitle</Heading>
+      <Heading level={5}>Level 5 — subtitle</Heading>
+      <Heading level={6}>Level 6 — subtitle</Heading>
+    </div>
+  ),
+};
+
+export const HeadingSizeOverride: Story = {
+  render: () => (
+    <div className="space-y-3">
+      <Heading level={2} size="display">
+        An h2 that reads as display
+      </Heading>
+      <Heading level={2} size="subtitle">
+        An h2 that reads as subtitle — the tag keeps the document outline
+      </Heading>
+    </div>
+  ),
+};
+
+export const AsAndAsChild: Story = {
+  render: () => (
+    <div className="space-y-3">
+      <Text as="span" variant="meta" tone="muted">
+        Rendered as a span
+      </Text>
+      <Heading level={2} asChild>
+        <a href="#typography">A heading that is a link (asChild)</a>
+      </Heading>
+    </div>
+  ),
+};
+
+/**
+ * The DENSITY dial rescales type as well as spacing (#340). Literal `text-<role>`
+ * classes (not a template string) so Tailwind statically emits every rung.
+ */
+const DENSITY_COLUMNS = [
+  { mode: "compact", label: "Compact", note: "−6.25% type · −11% spacing" },
+  { mode: "comfortable", label: "Comfortable", note: "identity — the default" },
+  { mode: "spacious", label: "Spacious", note: "+6.25% type · +12% spacing" },
+] as const;
+
+const DENSITY_ROLES = [
+  { role: "display", cls: "text-display", sample: "Pipeline health" },
+  { role: "title", cls: "text-title", sample: "Ingestion failures" },
+  { role: "subtitle", cls: "text-subtitle", sample: "Last 24 hours" },
+  {
+    role: "body",
+    cls: "text-body",
+    sample: "Four sources missed their window; two recovered on retry.",
+  },
+  { role: "caption", cls: "text-caption", sample: "Retries are counted per source, not per file." },
+  { role: "meta", cls: "text-meta", sample: "Updated 3 minutes ago" },
+  { role: "kpi", cls: "text-kpi tabular-nums", sample: "12,480" },
+  { role: "code", cls: "text-code font-mono", sample: "sources.retry(max=3)" },
+] as const;
+
+/** One role row, with its measured rendered size so the dial is observable. */
+function DensityRoleRow({ role, cls, sample }: (typeof DENSITY_ROLES)[number]) {
+  const ref = useRef<HTMLParagraphElement>(null);
+  const [measured, setMeasured] = useState("");
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const { fontSize, lineHeight } = getComputedStyle(el);
+    setMeasured(fontSize && lineHeight ? `${fontSize} / ${lineHeight}` : "");
+  }, []);
+  return (
+    <div className="space-y-1 border-t border-border py-2 first:border-t-0">
+      <p className="m-0 flex items-baseline justify-between gap-3 text-meta text-muted-foreground">
+        <span>{role}</span>
+        <span className="tabular-nums" data-testid={`measured-${role}`}>
+          {measured}
+        </span>
+      </p>
+      <p ref={ref} className={`m-0 ${cls}`} data-testid={`sample-${role}`}>
+        {sample}
+      </p>
+    </div>
+  );
+}
+
+export const DensityScale: Story = {
+  name: "Density scale",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The same eight roles at all three densities, side by side. Density scales the " +
+          "type SIZE and LINE-HEIGHT (weight and tracking are untouched) alongside the " +
+          "spacing, so a compact surface tightens as a whole. `comfortable` is the exact " +
+          "identity — pixel-identical to a pre-#340 build. The measured `font-size / " +
+          "line-height` under each role name is read live from the browser, so the columns " +
+          "cannot claim a difference they do not render.",
+      },
+    },
+  },
+  render: () => (
+    <div className="space-y-4">
+      <p className="m-0 max-w-prose text-caption text-muted-foreground">
+        Each column pins its own <code className="text-code">data-density</code>. Type shrinks at
+        roughly HALF the rate of spacing — whitespace can be cut hard before a layout stops working,
+        text cannot. Compact body lands at 13.125px, above the 13px reading floor.
+      </p>
+      <div className="flex flex-wrap gap-6">
+        {DENSITY_COLUMNS.map(({ mode, label, note }) => (
+          <section key={mode} className="min-w-64 flex-1 space-y-2">
+            <Heading level={3} size="subtitle">
+              {label}
+            </Heading>
+            <Text variant="meta" tone="muted">
+              {note}
+            </Text>
+            {/* The dial itself — everything below scales, the label above does not,
+                so the three columns stay comparable. */}
+            <div data-density={mode} className="rounded-lg border border-border p-3">
+              {DENSITY_ROLES.map((r) => (
+                <DensityRoleRow key={r.role} {...r} />
+              ))}
+            </div>
+          </section>
+        ))}
+      </div>
+    </div>
+  ),
+  // Asserts the dial on the REAL rendered surface: the source-parsed token test
+  // proves the arithmetic, this proves a browser actually applies it.
+  play: async ({ canvas }) => {
+    const px = (el: HTMLElement) => parseFloat(getComputedStyle(el).fontSize);
+    const columns = canvas.getAllByTestId("sample-body");
+    expect(columns).toHaveLength(3);
+    const [compact, comfortable, spacious] = columns.map(px);
+
+    // Identity: comfortable is still the shipped 14px body.
+    expect(comfortable).toBe(14);
+    // Direction: the dial actually moves type, both ways.
+    expect(compact).toBeLessThan(comfortable);
+    expect(spacious).toBeGreaterThan(comfortable);
+    // Legibility floor: compact body never drops below 13px.
+    expect(compact).toBeGreaterThanOrEqual(13);
+    // Weight is a semantic rung — it does NOT scale with density.
+    for (const el of columns) expect(getComputedStyle(el).fontWeight).toBe("400");
+  },
+};
+
+export const Prose: Story = {
+  render: () => (
+    <div className="max-w-2xl space-y-3">
+      <ProseHeading level={1}>Prose heading level 1</ProseHeading>
+      <ProseHeading level={2}>Prose heading level 2</ProseHeading>
+      <ProseHeading level={3}>Prose heading level 3</ProseHeading>
+      <ProseText>
+        Body text with an <ProseLink href="https://example.com">external link</ProseLink> and some{" "}
+        <ProseInlineCode>inline code</ProseInlineCode>.
+      </ProseText>
+      <ProseText variant="muted">Muted helper text.</ProseText>
+      <ProseBlockquote>A blockquote rendered through the branded primitive.</ProseBlockquote>
+      <ProseList>
+        <ProseListItem>First bullet</ProseListItem>
+        <ProseListItem>Second bullet</ProseListItem>
+      </ProseList>
+      <ProseList ordered>
+        <ProseListItem>First step</ProseListItem>
+        <ProseListItem>Second step</ProseListItem>
+      </ProseList>
+    </div>
+  ),
+};

package/src/components/typography/typography.test.tsx

@@ -0,0 +1,140 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { cn } from "../../lib/cn";
+import { PROSE_HEADING_REM, ProseHeading } from "./prose";
+import { Heading, TEXT_ROLE_REM, Text } from "./typography";
+
+afterEach(cleanup);
+
+describe("Text", () => {
+  it("maps variants to type roles (kpi bundles tabular-nums, code bundles mono)", () => {
+    render(
+      <>
+        <Text>body</Text>
+        <Text variant="kpi">42</Text>
+        <Text variant="code">cn()</Text>
+        <Text variant="lead">lead</Text>
+      </>,
+    );
+    expect(screen.getByText("body")).toHaveClass("text-body", "text-foreground");
+    expect(screen.getByText("42")).toHaveClass("text-kpi", "tabular-nums");
+    expect(screen.getByText("cn()")).toHaveClass("text-code", "font-mono");
+    // lead == the subtitle rung at body weight (research 07 §B.3).
+    expect(screen.getByText("lead")).toHaveClass("text-subtitle", "font-normal");
+  });
+
+  it("applies tone and renders as p / span / asChild", () => {
+    render(
+      <>
+        <Text tone="muted">muted</Text>
+        <Text as="span" data-testid="span-text">
+          span
+        </Text>
+        <Text asChild>
+          <em>emphasized</em>
+        </Text>
+      </>,
+    );
+    expect(screen.getByText("muted")).toHaveClass("text-muted-foreground");
+    expect(screen.getByText("muted").tagName).toBe("P");
+    expect(screen.getByTestId("span-text").tagName).toBe("SPAN");
+    expect(screen.getByText("emphasized").tagName).toBe("EM");
+    expect(screen.getByText("emphasized")).toHaveClass("text-body");
+  });
+
+  it("merges className last (a caller's role wins over the variant's)", () => {
+    render(<Text className="text-title">override</Text>);
+    const el = screen.getByText("override");
+    expect(el).toHaveClass("text-title");
+    expect(el).not.toHaveClass("text-body");
+  });
+});
+
+describe("Heading", () => {
+  it("derives the tag and the default size from level (1→display, 2-3→title, 4-6→subtitle)", () => {
+    render(
+      <>
+        <Heading level={1}>one</Heading>
+        <Heading level={3}>three</Heading>
+        <Heading level={5}>five</Heading>
+      </>,
+    );
+    const h1 = screen.getByRole("heading", { level: 1 });
+    expect(h1.tagName).toBe("H1");
+    expect(h1).toHaveClass("text-display", "font-display", "text-balance");
+    const h3 = screen.getByRole("heading", { level: 3 });
+    expect(h3.tagName).toBe("H3");
+    expect(h3).toHaveClass("text-title");
+    const h5 = screen.getByRole("heading", { level: 5 });
+    expect(h5.tagName).toBe("H5");
+    expect(h5).toHaveClass("text-subtitle");
+  });
+
+  it("size overrides the visual rung while keeping the tag", () => {
+    render(
+      <Heading level={2} size="subtitle">
+        small h2
+      </Heading>,
+    );
+    const h2 = screen.getByRole("heading", { level: 2 });
+    expect(h2.tagName).toBe("H2");
+    expect(h2).toHaveClass("text-subtitle");
+    expect(h2).not.toHaveClass("text-title");
+  });
+
+  it("supports asChild (the child element becomes the heading root)", () => {
+    render(
+      <Heading level={2} asChild>
+        <a href="#section">linked heading</a>
+      </Heading>,
+    );
+    const a = screen.getByRole("link", { name: "linked heading" });
+    expect(a).toHaveClass("text-title");
+  });
+});
+
+describe("cn() role merging (lib/cn extension)", () => {
+  it("keeps a role alongside a text color, and lets later role/raw sizes win", () => {
+    // Without the font-size registration tailwind-merge classifies text-<role>
+    // as a COLOR and `text-foreground` would silently drop `text-kpi`.
+    expect(cn("text-kpi", "tabular-nums", "text-foreground")).toBe(
+      "text-kpi tabular-nums text-foreground",
+    );
+    expect(cn("text-body", "text-title")).toBe("text-title");
+    expect(cn("text-sm", "text-body")).toBe("text-body");
+  });
+});
+
+describe("type-role rems (drift guards)", () => {
+  it("TEXT_ROLE_REM mirrors the --text-<role> tokens in themes.css", () => {
+    // vitest runs with cwd = packages/ui.
+    const css = readFileSync(resolve(process.cwd(), "../tokens/src/themes.css"), "utf8");
+    for (const [role, rem] of Object.entries(TEXT_ROLE_REM)) {
+      // Since #340 the rem LITERAL lives one layer down, in themes.css
+      // § TYPE SCALE BASE, so the density dial can scale from it (density.css);
+      // `--text-<role>` aliases it. Both halves are pinned here: the mirror must
+      // track the literal, AND the role must still resolve to that literal —
+      // a role re-inlined or re-pointed elsewhere would silently detach the
+      // runtime mirror @elabs-ai/components-editor's markdown scale reads.
+      expect(css).toContain(`--type-size-${role}: ${rem}rem;`);
+      expect(css).toContain(`--text-${role}: var(--type-size-${role});`);
+    }
+  });
+
+  it("the prose reading scale keeps the canonical markdown rems (issue #18 contract)", () => {
+    expect(PROSE_HEADING_REM).toEqual({ 1: 1.5, 2: 1.25, 3: 1.125, 4: 1, 5: 0.875, 6: 0.875 });
+  });
+});
+
+describe("ProseHeading", () => {
+  it("renders the heading element for the given level with the role class", () => {
+    render(<ProseHeading level={4}>Doc title</ProseHeading>);
+    const h = screen.getByRole("heading", { level: 4, name: "Doc title" });
+    expect(h.tagName).toBe("H4");
+    expect(h).toHaveClass("text-subtitle");
+  });
+});