@elabs-ai/components-ui 4.0.0

package/src/index.ts

@@ -0,0 +1,174 @@
+/**
+ * @elabs-ai/components-ui — foundation + app UI components.
+ *
+ * Source-owned shadcn-style components built on Radix primitives and the
+ * @elabs-ai/components-tokens semantic theme. Import the token stylesheet once at the app
+ * root ("import \"@elabs-ai/components-tokens/styles.css\"") and wrap in <ThemeProvider>.
+ *
+ * NOTE: this barrel is generated to include every component folder. Some
+ * components require their own peer libs (declared in package.json), e.g.
+ * Drawer (vaul), Command (cmdk), Toast (sonner), Calendar (react-day-picker),
+ * Carousel (embla-carousel-react), Resizable (react-resizable-panels),
+ * Form (react-hook-form + zod), InputOTP (input-otp).
+ */
+
+// Utilities
+export { cn } from "./lib/cn";
+// The canonical mobile-breakpoint check (Sidebar / ContextPanel Sheet fallback
+// pattern, research 09 §B.4) — exported so siblings don't fork a matchMedia hook.
+export { useIsMobile } from "./lib/use-mobile";
+// Browser file-download mechanics — one home for the Blob/URL → <a download> dance
+// (shared by ConversationDownload, downloadCsv, and Gallery). SSR-guarded.
+export { downloadBlob, downloadUrl } from "./lib/download";
+// Clipboard write + transient "copied" flag — one implementation for the
+// editor's copy button and `CopyableValue`, so the timing and the
+// "no clipboard in this context" answer are defined once.
+export {
+  COPY_FEEDBACK_MS,
+  useCopyToClipboard,
+  type CopyToClipboard,
+  type UseCopyToClipboardOptions,
+} from "./lib/use-copy-to-clipboard";
+// The shared file model (ADR 0024) — one input union + one coarse, CLOSED
+// category, so `ai`, `viewer` and future surfaces stop each inventing their own.
+// Fine-grained format matching belongs to the adapter manifests, not here.
+export { type FileSource, type ResolvedFileSource, normalizeFileSource } from "./lib/file-source";
+export {
+  type FileCategory,
+  type FileKind,
+  extensionOf,
+  mediaTypeFromName,
+  resolveFileKind,
+} from "./lib/file-kind";
+export { FILE_CATEGORY_ICONS, fileIconFor } from "./lib/file-icon";
+// How one PART of a document is addressed (ADR 0025). Lives here for the same
+// reason `FileSource` does: the producer of a citation (`ai`) and its consumer
+// (`viewer`) are Layer-2 siblings that may not import each other.
+export {
+  DOCUMENT_ADDRESS_KINDS,
+  type DocumentAddress,
+  type DocumentAddressKind,
+  type DocumentRect,
+  type NormalizedText,
+  type QuoteAddress,
+  type RangeAddress,
+  type RectAddress,
+  normalizeQuoteText,
+  normalizeQuoteTextWithOffsets,
+} from "./lib/document-address";
+// Streamdown's in-markdown chrome, resolved through `t()` (#310). Shared here
+// because both `ai` and `viewer` render Streamdown and may not import each other.
+export {
+  STREAMDOWN_TRANSLATION_KEYS,
+  useStreamdownTranslations,
+  type StreamdownTranslationKey,
+  type StreamdownTranslationMap,
+} from "./lib/streamdown-translations";
+
+// Components
+export * from "./components/accordion";
+export * from "./components/advanced-group";
+export * from "./components/app-sidebar";
+export * from "./components/alert";
+export * from "./components/alert-dialog";
+export * from "./components/app-shell";
+export * from "./components/aspect-ratio";
+export * from "./components/attribution-panel";
+export * from "./components/avatar";
+export * from "./components/badge";
+export * from "./components/bento-grid";
+export * from "./components/bounded-number";
+export * from "./components/breadcrumb";
+export * from "./components/button";
+export * from "./components/button-group";
+export * from "./components/calendar";
+export * from "./components/card";
+export * from "./components/carousel";
+export * from "./components/change-review";
+export * from "./components/checkbox";
+export * from "./components/collapsible";
+export * from "./components/collapsible-panel";
+export * from "./components/color-picker";
+export * from "./components/combobox";
+export * from "./components/command";
+export * from "./components/confirm-dialog";
+export * from "./components/context-menu";
+export * from "./components/copyable-value";
+export * from "./components/date-picker";
+export * from "./components/date-range-picker";
+export * from "./components/descriptions";
+export * from "./components/dialog";
+export * from "./components/drawer";
+export * from "./components/dropdown-menu";
+export * from "./components/empty-state";
+export * from "./components/error-state";
+export * from "./components/expand-dialog";
+export * from "./components/field-row";
+export * from "./components/file-upload";
+export * from "./components/form";
+export * from "./components/hover-card";
+export * from "./components/icon-button";
+export * from "./components/input";
+export * from "./components/input-group";
+export * from "./components/input-otp";
+export * from "./components/kbd";
+export * from "./components/key-value-editor";
+export * from "./components/label";
+export * from "./components/link-preview";
+export * from "./components/list-editor";
+export * from "./components/locale-provider";
+export * from "./components/loading-state";
+export * from "./components/match-highlight";
+export * from "./components/mention-input";
+export * from "./components/menubar";
+export * from "./components/model-picker";
+export * from "./components/metric-card";
+export * from "./components/nav-main";
+export * from "./components/nav-notifications";
+export * from "./components/nav-user";
+export * from "./components/navigation-menu";
+export * from "./components/number-input";
+export * from "./components/page-shell";
+export * from "./components/pagination";
+export * from "./components/popover";
+export * from "./components/progress";
+export * from "./components/radio-group";
+export * from "./components/rating";
+export * from "./components/resizable";
+export * from "./components/reveal";
+export * from "./components/scroll-area";
+export * from "./components/section-header";
+export * from "./components/segmented-field";
+export * from "./components/select";
+export * from "./components/separator";
+export * from "./components/sheet";
+export * from "./components/sidebar";
+export * from "./components/skeleton";
+export * from "./components/slider";
+export * from "./components/slider-number";
+export * from "./components/sonner";
+export * from "./components/spinner";
+export * from "./components/state-panel";
+export * from "./components/status-badge";
+export * from "./components/split-panel";
+export * from "./components/switch";
+export * from "./components/table";
+export * from "./components/tabs";
+export * from "./components/tag-input";
+export * from "./components/team-switcher";
+export * from "./components/textarea";
+export * from "./components/theme-switcher";
+export * from "./components/revision-timeline";
+export * from "./components/timeline";
+export * from "./components/toggle";
+export * from "./components/toggle-group";
+export * from "./components/toolbar";
+export * from "./components/tooltip";
+export * from "./components/top-nav";
+export * from "./components/transfer";
+export * from "./components/tree";
+export * from "./components/tree-select";
+export * from "./components/typography";
+export * from "./components/view-toolbar";
+export * from "./components/virtual-select";
+export * from "./components/wizard";

package/src/lib/cn.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { cn } from "./cn";
+
+describe("cn", () => {
+  it("later utilities win for a genuine conflict (e.g. padding)", () => {
+    expect(cn("p-2", "p-4")).toBe("p-4");
+  });
+
+  it("keeps semantic type-role and text-color independent (#187)", () => {
+    expect(cn("text-kpi", "text-foreground")).toContain("text-kpi");
+    expect(cn("text-kpi", "text-foreground")).toContain("text-foreground");
+  });
+
+  // #336: the CardDescription regression was NOT a tailwind-merge conflict — it
+  // was an invalid, misspelled utility name that isn't a real Tailwind class,
+  // which tailwind-merge's default `text-*` color group happily classified as
+  // an unrecognized color and dropped in favor of whichever `text-<color>`
+  // utility came later. `text-balance` is a real, already-registered Tailwind
+  // utility that tailwind-merge groups under its own `text-wrap` conflict
+  // group by default — no `cn.ts` registration is (or ever was) needed to
+  // keep it independent from `text-<color>`.
+  it("keeps text-balance and text-<color> independent regardless of order (#336)", () => {
+    const colorFirst = cn("text-sm", "text-muted-foreground", "text-balance");
+    expect(colorFirst).toContain("text-muted-foreground");
+    expect(colorFirst).toContain("text-balance");
+
+    const wrapFirst = cn("text-sm", "text-balance", "text-muted-foreground");
+    expect(wrapFirst).toContain("text-muted-foreground");
+    expect(wrapFirst).toContain("text-balance");
+  });
+
+  it("still dedupes conflicting text-wrap utilities against each other", () => {
+    expect(cn("text-balance", "text-pretty")).toBe("text-pretty");
+  });
+
+  it("still dedupes conflicting text-<color> utilities against each other", () => {
+    expect(cn("text-red-500", "text-blue-500")).toBe("text-blue-500");
+  });
+});

package/src/lib/cn.ts

@@ -0,0 +1,31 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * The semantic type roles (`--text-<role>` tokens → `text-<role>` utilities, #187).
+ * tailwind-merge doesn't know custom theme keys, so without registration it
+ * classifies `text-title` as a text COLOR — and `cn("text-kpi", "text-foreground")`
+ * would silently drop the role. Registering the roles in the `font-size` class
+ * group makes role-vs-role and role-vs-raw-size conflicts resolve correctly while
+ * keeping role + color independent.
+ */
+const TEXT_ROLES = ["display", "title", "subtitle", "body", "caption", "meta", "kpi", "code"];
+
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: TEXT_ROLES }],
+      // `font-display` is the display-face seam (sibling of font-mono, #187).
+      "font-family": [{ font: ["display"] }],
+    },
+  },
+});
+
+/**
+ * Merge class names with conflict resolution. `clsx` handles conditionals;
+ * `tailwind-merge` ensures later Tailwind utilities win (e.g. `p-2 p-4` -> `p-4`).
+ * Use this in every component that accepts a `className` prop.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/lib/compact-number.ts

@@ -0,0 +1,61 @@
+/**
+ * compact-number.ts — the same "shown short, copied exact" number rule the
+ * charts package applies to axis ticks and tooltips, available to `ui` surfaces
+ * that display a figure (today: `MetricCard`).
+ *
+ * DELIBERATE TWIN of `packages/charts/src/charts/value-format.ts`. Dependencies
+ * flow one way — `tokens → ui → charts` — so `ui` cannot import the charts
+ * module, and a chart-domain union does not belong in the `ui` public API just
+ * to be shared. The duplication is ~20 lines and the two must stay in step:
+ * **change one, change the other**, and keep {@link COMPACT_THRESHOLD} equal in
+ * both. `metric-card.test.tsx` and `value-format.test.ts` pin the same cases on
+ * each side so a drift shows up as a failing test rather than as two surfaces
+ * disagreeing about what `1500` looks like.
+ */
+
+/** How a numeric value is rendered. Mirrors the charts `ChartValueFormat`. */
+export type NumberFormatKind = "number" | "compact" | "currency" | "percent";
+
+/** Magnitude at or above which `compact`/`currency` switch to compact notation. */
+export const COMPACT_THRESHOLD = 1000;
+
+/** Used when a caller asks for currency without naming one. */
+export const DEFAULT_CURRENCY = "USD";
+
+/** One decimal keeps `1.5M` readable without implying precision it lacks. */
+export const DEFAULT_MAX_FRACTION_DIGITS = 1;
+
+/** `Intl.NumberFormatOptions` for `format` at this magnitude. */
+export function numberFormatOptions(
+  format: NumberFormatKind,
+  value: number,
+  currency: string = DEFAULT_CURRENCY,
+  maxFractionDigits?: number,
+): Intl.NumberFormatOptions {
+  const compact = Number.isFinite(value) && Math.abs(value) >= COMPACT_THRESHOLD;
+  // `"number"` is the exact-value escape hatch and keeps `Intl`'s own default
+  // (3 digits) unless the caller states one — capping it at the compact rung's
+  // single decimal would render 0.0512 as "0.1".
+  const digits = maxFractionDigits ?? DEFAULT_MAX_FRACTION_DIGITS;
+  switch (format) {
+    case "number":
+      return maxFractionDigits === undefined ? {} : { maximumFractionDigits: maxFractionDigits };
+    case "percent":
+      return { style: "percent", maximumFractionDigits: digits };
+    case "currency":
+      return compact
+        ? {
+            style: "currency",
+            currency,
+            notation: "compact",
+            compactDisplay: "short",
+            maximumFractionDigits: digits,
+          }
+        : { style: "currency", currency, maximumFractionDigits: digits };
+    case "compact":
+    default:
+      return compact
+        ? { notation: "compact", compactDisplay: "short", maximumFractionDigits: digits }
+        : { maximumFractionDigits: digits };
+  }
+}

package/src/lib/document-address.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeQuoteText, normalizeQuoteTextWithOffsets } from "./document-address";
+
+/** Map a normalized range back and read the slice it names in the original. */
+function sliceVia(original: string, from: number, to: number): string {
+  const { offsets } = normalizeQuoteTextWithOffsets(original);
+  return original.slice(offsets[from], offsets[to]);
+}
+
+describe("normalizeQuoteText", () => {
+  it("collapses every whitespace run to one space, and trims", () => {
+    expect(normalizeQuoteText("  the\n\n  quick\tbrown \r\n fox  ")).toBe("the quick brown fox");
+  });
+
+  it("straightens the quotes and dashes an extractor disagrees about", () => {
+    // The same sentence out of a PDF and out of a model. Neither side should
+    // have to know which glyph the other used.
+    expect(normalizeQuoteText("“Don’t”—she said")).toBe(normalizeQuoteText('"Don\'t"-she said'));
+  });
+
+  it("folds case, so a citation matches without a caller-set flag", () => {
+    expect(normalizeQuoteText("Total Revenue")).toBe(normalizeQuoteText("total revenue"));
+  });
+
+  it("drops the invisibles a line break leaves behind", () => {
+    // A soft hyphen at a PDF's line wrap, and a zero-width space.
+    expect(normalizeQuoteText("re­venue​")).toBe("revenue");
+  });
+
+  it("leaves a ligature alone — folding it would be a 1:many expansion", () => {
+    // The offset map is only trustworthy while every rule is a collapse, a drop
+    // or a 1:1 swap. A fuzzier match is not worth losing that.
+    expect(normalizeQuoteText("final")).toBe("final");
+  });
+});
+
+describe("normalizeQuoteTextWithOffsets", () => {
+  it("ends one past the last SURVIVING character, not at the input's length", () => {
+    // Ending at the input's length would drag the trailing space into every
+    // range that runs to the end of the document.
+    const input = "  hello   world ";
+    const { text, offsets } = normalizeQuoteTextWithOffsets(input);
+    expect(text).toBe("hello world");
+    expect(offsets).toHaveLength(text.length + 1);
+    expect(offsets[offsets.length - 1]).toBe(input.lastIndexOf("d") + 1);
+  });
+
+  it("maps a normalized range back onto the ORIGINAL characters", () => {
+    // "world" in the normalized string is at [6, 11); in the original it sits
+    // past a three-space run and a leading pair, at completely different indices.
+    const original = "  Hello   World ";
+    expect(sliceVia(original, 6, 11)).toBe("World");
+  });
+
+  it("points a collapsed space at where its run began", () => {
+    // Selecting across the gap must include the whole run, not just its last
+    // character — otherwise a highlight starts mid-whitespace.
+    const original = "a \n\t b";
+    expect(sliceVia(original, 0, 3)).toBe("a \n\t b");
+  });
+
+  it("keeps the map monotone across folds, drops and case changes", () => {
+    const { offsets } = normalizeQuoteTextWithOffsets(" “Süß”­ — DONE ");
+    for (let i = 1; i < offsets.length; i += 1) {
+      expect(offsets[i]).toBeGreaterThan(offsets[i - 1] as number);
+    }
+  });
+
+  it("survives a string that is nothing but whitespace", () => {
+    const { text, offsets } = normalizeQuoteTextWithOffsets("   \n  ");
+    expect(text).toBe("");
+    expect(offsets).toEqual([0]);
+  });
+});

package/src/lib/document-address.ts

@@ -0,0 +1,265 @@
+/**
+ * How one part of a document is addressed.
+ *
+ * A viewer that can only open a file answers "here is the document". A viewer
+ * that can be pointed at a PART of one answers "here is the sentence that
+ * claim came from" — the RAG-citation case, and the same machinery behind
+ * find-in-document.
+ *
+ * ## Why this lives in `@elabs-ai/components-ui`
+ *
+ * The producer of an address (a chat answer's citation, in
+ * `@elabs-ai/components-ai`) and its consumer (the file viewer, in
+ * `@elabs-ai/components-viewer`) are Layer-2 siblings that may not
+ * import each other. `ui` is the only layer both reach, which is exactly why
+ * `FileSource` and `MatchRange` already live here. This module is a
+ * dependency-free leaf: types plus pure string functions, no React.
+ *
+ * ## Three kinds, one union
+ *
+ * Real producers disagree about what they can emit, so the union carries all
+ * three rather than forcing everyone through the weakest:
+ *
+ * - **`quote`** — the snippet text. The only kind that survives crossing a tool
+ *   boundary: an indexing pipeline's character offsets are computed against ITS
+ *   extraction of the PDF, never against ours, so its numbers are meaningless
+ *   here while its text still is. Lossy (a repeated phrase is ambiguous) and the
+ *   most useful.
+ * - **`range`** — exact character offsets, and exact only against the SAME text
+ *   projection: `AdapterDocument.text` as this build's adapter produced it. Use
+ *   it when both ends are ours (find-in-document, a second pass over a document
+ *   already open).
+ * - **`rect`** — page-relative boxes, `0..1` fractions of the page. Needs no
+ *   text at all, which is what makes it the answer for a scanned page, a chart,
+ *   a photo region, or any layout-analysis model whose output is geometry.
+ *
+ * ## The rule that lets this union grow
+ *
+ * A consumer matches only the kinds it declared it honours and reports the rest
+ * as unsupported — it never writes an exhaustive `switch` with a `never`
+ * fallthrough. That is what lets a fourth kind (a spreadsheet `cell` address,
+ * say) be added later without breaking every consumer that predates it.
+ */
+
+/** The address kinds, as a value — for capability declarations and iteration. */
+export const DOCUMENT_ADDRESS_KINDS = ["quote", "range", "rect"] as const;
+
+/** Which way a part of a document is addressed. */
+export type DocumentAddressKind = (typeof DOCUMENT_ADDRESS_KINDS)[number];
+
+/**
+ * A box on a page, as fractions of that page's own box.
+ *
+ * Fractions, not pixels, because the page is not a fixed size: it rescales with
+ * zoom, with the pane's width and with the device's pixel ratio. A consumer
+ * multiplies by the page element's live measured size at paint time, so the box
+ * stays put through every one of those. Origin is top-left (CSS), so `y` grows
+ * downward — matching the DOM rather than the PDF's own bottom-left space.
+ */
+export interface DocumentRect {
+  /** Distance from the page's left edge, `0..1`. */
+  x: number;
+  /** Distance from the page's TOP edge, `0..1`. */
+  y: number;
+  /** Fraction of the page's width. */
+  width: number;
+  /** Fraction of the page's height. */
+  height: number;
+}
+
+/**
+ * Address by the text itself — the interoperable kind.
+ *
+ * Matching is done on the normalized form of both sides
+ * ({@link normalizeQuoteText}), so a quote survives the whitespace, quote-glyph
+ * and casing differences that every extractor introduces.
+ */
+export interface QuoteAddress {
+  kind: "quote";
+  /** The passage to find. Whitespace and quote glyphs need not match exactly. */
+  text: string;
+  /**
+   * Which occurrence to take when the passage appears more than once, 1-based.
+   * Omitted means the first — or the one nearest {@link QuoteAddress.near},
+   * when that is given.
+   */
+  occurrence?: number;
+  /**
+   * A hint about where to look. It disambiguates repeats rather than restricting
+   * the search: the occurrence closest to it wins, and a passage that turns out
+   * to be elsewhere is still found.
+   */
+  near?: {
+    /**
+     * 1-based page (or slide) the passage is expected on.
+     *
+     * Advisory, and deliberately NOT used to navigate: the viewer turns to the
+     * page the passage was actually located on, so a stale hint cannot send a
+     * reader to a blank page. Only {@link QuoteAddress.near.offset} takes part in
+     * tie-breaking today; a renderer may read this off the address if it wants
+     * more.
+     */
+    page?: number;
+    /** Approximate character offset the passage is expected near. */
+    offset?: number;
+  };
+}
+
+/**
+ * Address by character offsets into `AdapterDocument.text`, half-open
+ * `[start, end)` — the same convention as `MatchRange`.
+ *
+ * Only meaningful against the text projection THIS build produced. An offset
+ * from a foreign pipeline is not this kind; it is a {@link QuoteAddress}.
+ */
+export interface RangeAddress {
+  kind: "range";
+  start: number;
+  end: number;
+  /**
+   * 1-based page hint, when the producer knows it. Advisory only — the viewer
+   * derives the page from the offsets against its own index, so a hint that
+   * disagrees cannot misdirect the pager.
+   */
+  page?: number;
+}
+
+/** Address by geometry — one or more boxes on one page. */
+export interface RectAddress {
+  kind: "rect";
+  /** 1-based page (or slide) number. */
+  page: number;
+  /**
+   * The boxes making up this one addressed part. An array, not a single box,
+   * because a real passage wraps: a sentence spanning three lines is three
+   * boxes, and a two-column paragraph is more. Painting them as one shape each
+   * is what avoids stitching DOM ranges together.
+   */
+  rects: readonly DocumentRect[];
+}
+
+/** Which part of a document something refers to. */
+export type DocumentAddress = QuoteAddress | RangeAddress | RectAddress;
+
+/* -------------------------------------------------------------------------- */
+/* Quote normalization                                                         */
+/* -------------------------------------------------------------------------- */
+
+/** Straightened 1:1 — every one of these is one code unit in and one out. */
+const CHARACTER_FOLDS: Readonly<Record<string, string>> = {
+  // Curly quotes and primes. A model quoting a PDF re-types these constantly;
+  // the file has the other one.
+  "‘": "'",
+  "’": "'",
+  "‚": "'",
+  "‛": "'",
+  "′": "'",
+  "“": '"',
+  "”": '"',
+  "„": '"',
+  "‟": '"',
+  "″": '"',
+  // Dashes. PDF extraction yields the typographic one, prose yields a hyphen.
+  "‐": "-",
+  "‑": "-",
+  "‒": "-",
+  "–": "-",
+  "—": "-",
+  "―": "-",
+  "−": "-",
+};
+
+/**
+ * Invisible, and typically present in exactly one of the two strings being
+ * compared: soft hyphen (a PDF's line-break artefact), zero-width space, ZWNJ,
+ * ZWJ, word joiner. Written as escapes because a literal here is unreviewable —
+ * it renders as nothing.
+ */
+const DROPPED = new Set(["­", "​", "‌", "‍", "⁠"]);
+
+/**
+ * Anything that collapses into one space. Plain `\s` is already the full set in
+ * JavaScript — it covers NBSP, the `U+2000`–`U+200A` spaces, the line and
+ * paragraph separators, narrow NBSP, ideographic space and the BOM.
+ */
+const WHITESPACE = /\s/u;
+
+/**
+ * The result of normalizing, with the way back.
+ *
+ * `offsets` has one more entry than `text` has characters: `offsets[i]` is the
+ * index in the ORIGINAL string where normalized character `i` came from, and
+ * the final entry is one past the last character that survived — NOT the
+ * original's length, which would drag trailing whitespace into every range that
+ * runs to the end. So a normalized range `[a, b)` maps back to
+ * `[offsets[a], offsets[b])` with no arithmetic, which is the whole point of
+ * building the map rather than searching twice.
+ */
+export interface NormalizedText {
+  text: string;
+  offsets: readonly number[];
+}
+
+/**
+ * Fold a string to its canonical match key, keeping a map back to the original.
+ *
+ * Every rule is a collapse, a drop or a 1:1 swap — never an expansion — so the
+ * map stays monotone and a range maps back exactly. That constraint is why
+ * ligatures (`fi`) and the ellipsis character are deliberately left alone: both
+ * would be 1:many, and a fuzzier match is not worth an offset map that can no
+ * longer be trusted.
+ *
+ * What it does: collapses every whitespace run to one space and trims; drops
+ * zero-width characters and soft hyphens; straightens curly quotes and dashes;
+ * folds case — a citation is matched case-insensitively, and that is a property
+ * of the match key rather than a flag every caller has to remember.
+ */
+export function normalizeQuoteTextWithOffsets(input: string): NormalizedText {
+  const out: string[] = [];
+  const offsets: number[] = [];
+  let pendingSpaceAt: number | undefined;
+  /** One past the last surviving character — the map's terminal entry. */
+  let end = 0;
+
+  for (let i = 0; i < input.length; i += 1) {
+    const character = input[i] as string;
+
+    if (WHITESPACE.test(character)) {
+      // Held rather than emitted, so a trailing run never reaches the output
+      // and a leading one is dropped by the `out.length` test below.
+      pendingSpaceAt ??= i;
+      continue;
+    }
+    if (DROPPED.has(character)) continue;
+
+    if (pendingSpaceAt !== undefined) {
+      if (out.length > 0) {
+        out.push(" ");
+        // The single space stands for the whole run, so it points at where the
+        // run began — not at the character that ended it.
+        offsets.push(pendingSpaceAt);
+      }
+      pendingSpaceAt = undefined;
+    }
+
+    const folded = CHARACTER_FOLDS[character] ?? character;
+    const lowered = folded.toLowerCase();
+    // Guard the 1:1 invariant: a few code points grow when lowercased
+    // (`İ` → `i̇`). Keeping the original is a worse match and a correct map; the
+    // reverse trade would silently corrupt every offset after it.
+    out.push(lowered.length === folded.length ? lowered : folded);
+    offsets.push(i);
+    end = i + 1;
+  }
+
+  offsets.push(end);
+  return { text: out.join(""), offsets };
+}
+
+/**
+ * The canonical match key for a quote — {@link normalizeQuoteTextWithOffsets}
+ * without the map, for comparing or de-duplicating two quotes.
+ */
+export function normalizeQuoteText(input: string): string {
+  return normalizeQuoteTextWithOffsets(input).text;
+}