@elabs-ai/components-ui 4.0.0

package/src/components/locale-provider/locale-provider.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { createContext, use, useMemo, type ReactNode } from "react";
+import { DirectionProvider } from "@radix-ui/react-direction";
+import { DEFAULT_MESSAGES } from "./messages";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** A flat map of string keys to their translated values. */
+export type Messages = Record<string, string>;
+
+export interface LocaleContextValue {
+  /** BCP-47 locale tag, e.g. "en-US", "ar-EG", "de-DE". */
+  locale: string;
+  /** Layout direction for the locale region. */
+  dir: "ltr" | "rtl";
+  /**
+   * Translate a key.
+   * Falls back to: consumer messages → English default → the key itself.
+   * Supports simple `{name}`-style variable interpolation.
+   */
+  t: (key: string, vars?: Record<string, string | number>) => string;
+  /** Format a number using the active locale. Memoized per locale+opts hash. */
+  formatNumber: (n: number, opts?: Intl.NumberFormatOptions) => string;
+  /** Format a date using the active locale. Memoized per locale+opts hash. */
+  formatDate: (d: Date | number, opts?: Intl.DateTimeFormatOptions) => string;
+}
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const LocaleContext = createContext<LocaleContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Default (no-provider) value — en-US / ltr
+// ---------------------------------------------------------------------------
+
+function interpolate(template: string, vars?: Record<string, string | number>): string {
+  if (!vars) return template;
+  return template.replace(/\{(\w+)\}/g, (_, key: string) =>
+    key in vars ? String(vars[key]) : `{${key}}`,
+  );
+}
+
+function makeDefaultValue(): LocaleContextValue {
+  const locale = "en-US";
+  // Simple cache: one Intl object per serialized opts string
+  const numberCache = new Map<string, Intl.NumberFormat>();
+  const dateCache = new Map<string, Intl.DateTimeFormat>();
+
+  return {
+    locale,
+    dir: "ltr",
+    t(key, vars) {
+      const template = DEFAULT_MESSAGES[key] ?? key;
+      return interpolate(template, vars);
+    },
+    formatNumber(n, opts) {
+      const k = JSON.stringify(opts ?? null);
+      if (!numberCache.has(k)) numberCache.set(k, new Intl.NumberFormat(locale, opts));
+      return numberCache.get(k)!.format(n);
+    },
+    formatDate(d, opts) {
+      const k = JSON.stringify(opts ?? null);
+      if (!dateCache.has(k)) dateCache.set(k, new Intl.DateTimeFormat(locale, opts));
+      return dateCache.get(k)!.format(d);
+    },
+  };
+}
+
+// Singleton default — stable across renders when no provider is mounted
+const DEFAULT_LOCALE_VALUE = makeDefaultValue();
+
+// ---------------------------------------------------------------------------
+// Provider props
+// ---------------------------------------------------------------------------
+
+export interface LocaleProviderProps {
+  /**
+   * BCP-47 locale tag. Defaults to "en-US".
+   * Used by `t`, `formatNumber`, and `formatDate`.
+   */
+  locale?: string;
+  /**
+   * Layout direction for the subtree.
+   * Defaults to "ltr". Set "rtl" for Arabic, Hebrew, Farsi, etc.
+   */
+  dir?: "ltr" | "rtl";
+  /**
+   * Additional/overriding message strings merged on top of the shipped English
+   * defaults. Only the keys you provide are overridden; the rest fall through
+   * to the English bundle.
+   */
+  messages?: Messages;
+  children: ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// LocaleProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * `LocaleProvider` supplies locale, layout direction, component microcopy, and
+ * Intl formatting helpers to the component subtree.
+ *
+ * - Wrap your app (or a regional subtree) with it to localise brand-ui components.
+ * - Components call `useLocale()` unconditionally; without a provider they
+ *   degrade gracefully to "en-US" / "ltr" / English defaults.
+ * - Portalled Radix content (Dialog, Sheet, Popover, DropdownMenu) still honors
+ *   `dir` because the subtree is wrapped in Radix's `DirectionProvider`, which
+ *   every Radix primitive reads via context regardless of DOM position (ADR-0014).
+ *   The `<div dir={dir}>` continues to carry direction for non-Radix content.
+ */
+export function LocaleProvider({
+  locale = "en-US",
+  dir = "ltr",
+  messages,
+  children,
+}: LocaleProviderProps) {
+  // Merge consumer messages over the shipped English defaults.
+  const merged: Messages = useMemo(
+    () => (messages ? { ...DEFAULT_MESSAGES, ...messages } : DEFAULT_MESSAGES),
+    // We intentionally deep-compare via JSON only when messages reference changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [messages],
+  );
+
+  // Memoized Intl formatter caches — keyed by serialised opts
+  const numberCache = useMemo(() => new Map<string, Intl.NumberFormat>(), [locale]);
+  const dateCache = useMemo(() => new Map<string, Intl.DateTimeFormat>(), [locale]);
+
+  const value = useMemo<LocaleContextValue>(
+    () => ({
+      locale,
+      dir,
+      t(key, vars) {
+        const template = merged[key] ?? key;
+        return interpolate(template, vars);
+      },
+      formatNumber(n, opts) {
+        const k = JSON.stringify(opts ?? null);
+        if (!numberCache.has(k)) numberCache.set(k, new Intl.NumberFormat(locale, opts));
+        return numberCache.get(k)!.format(n);
+      },
+      formatDate(d, opts) {
+        const k = JSON.stringify(opts ?? null);
+        if (!dateCache.has(k)) dateCache.set(k, new Intl.DateTimeFormat(locale, opts));
+        return dateCache.get(k)!.format(d);
+      },
+    }),
+    [locale, dir, merged, numberCache, dateCache],
+  );
+
+  return (
+    <LocaleContext.Provider value={value}>
+      {/*
+       * `DirectionProvider` makes `dir` reach portalled Radix overlays (Dialog,
+       * Sheet, Popover, DropdownMenu, Select, Tooltip, …) which escape the DOM
+       * `dir` ancestor (ADR-0014). The `<div dir={dir}>` still carries direction
+       * for non-Radix content.
+       */}
+      <DirectionProvider dir={dir}>
+        <div dir={dir}>{children}</div>
+      </DirectionProvider>
+    </LocaleContext.Provider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// useLocale
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the active locale, direction, `t`, `formatNumber`, and `formatDate`.
+ *
+ * Provider-optional: without a `<LocaleProvider>` this returns the en-US
+ * defaults so components can call it unconditionally and remain usable in
+ * unwrapped contexts.
+ */
+export function useLocale(): LocaleContextValue {
+  // React 19 `use()` — can be called conditionally and composes with Suspense.
+  const ctx = use(LocaleContext);
+  return ctx ?? DEFAULT_LOCALE_VALUE;
+}

package/src/components/locale-provider/messages.ts

@@ -0,0 +1,300 @@
+"use client";
+
+/**
+ * Shipped English (en-US) default microcopy bundle.
+ *
+ * Keys are intentionally terse, semantic, and framework-agnostic so they
+ * translate cleanly into any target locale. Keep this list small and real —
+ * only add a key here when a component actually needs it.
+ */
+export const DEFAULT_MESSAGES: Record<string, string> = {
+  // ── Generic (shared across packages — reuse these before minting a new key) ──
+  close: "Close",
+  copy: "Copy",
+  previous: "Previous",
+  next: "Next",
+  previousSlide: "Previous slide",
+  nextSlide: "Next slide",
+  noResults: "No results.",
+  noRows: "No rows.",
+  loading: "Loading…",
+  more: "More",
+  selectAll: "Select all",
+
+  // ── @elabs-ai/components-ui ───────────────────────────────────────────────────────────────
+  "ui.metricCard.loading": "Loading metric…",
+  // CopyableValue. `hint` is APPENDED to the visible (compact) value, so the
+  // accessible name contains what the reader sees — WCAG 2.5.3, Label in Name.
+  "ui.copyableValue.hint": "Copy exact value",
+  "ui.copyableValue.copied": "Copied",
+  // ExpandDialog. Names the context pane beside the enlarged content, so a
+  // screen-reader user can tell the two scrollable regions apart.
+  "ui.expandDialog.detail": "Details",
+  // AttributionPanel. `required` labels a notice a licence obliges us to show —
+  // it is the WORD, not a colour, so the distinction survives greyscale (1.4.1).
+  "ui.attributionPanel.label": "Third-party attributions",
+  "ui.attributionPanel.required": "Required",
+  "ui.attributionPanel.empty": "No attributions match this filter.",
+  // ModelPicker. `refreshFailed` sits ABOVE a list that still works; `loadFailed`
+  // replaces the list. The distinction is load-bearing — see modelPickerBody.
+  "ui.modelPicker.label": "Choose a target",
+  "ui.modelPicker.searchPlaceholder": "Search…",
+  "ui.modelPicker.refreshFailed": "Couldn't refresh the list",
+  "ui.modelPicker.loadFailed": "Couldn't load the list",
+  "ui.modelPicker.nothingYet": "Nothing to show yet",
+  "ui.modelPicker.retry": "Retry",
+  // ViewToolbar (#331). `removeFilter` deliberately WRAPS the visible chip text
+  // so the accessible name contains it (WCAG 2.5.3 Label in Name).
+  "ui.viewToolbar.about": "About this view",
+  "ui.viewToolbar.activeFilters": "Active filters",
+  "ui.viewToolbar.clearAll": "Clear all",
+  "ui.viewToolbar.countOfTotal": "{count} of {total}",
+  "ui.viewToolbar.removeFilter": "Remove filter: {label}",
+  // Combobox `allowCustomValue` mode (#359) — `{value}` interpolates the
+  // currently typed, non-matching search text.
+  "ui.combobox.useCustomValue": 'Use "{value}"',
+  "ui.combobox.emptyAllowCustom": "No matches. Type to add a custom value.",
+  // Form kit (#370–#374).
+  "ui.boundedNumber.emptyLabel": "No limit",
+  "ui.keyValueEditor.addRow": "Add row",
+  "ui.keyValueEditor.keyLabel": "Key {n}",
+  "ui.keyValueEditor.valueLabel": "Value {n}",
+  "ui.keyValueEditor.removeRow": "Remove row {n}",
+  "ui.keyValueEditor.reveal": "Reveal value {n}",
+  "ui.keyValueEditor.hide": "Hide value {n}",
+  "ui.keyValueEditor.empty": "No entries yet.",
+  "ui.listEditor.addItem": "Add item",
+  "ui.listEditor.itemLabel": "Item {n}",
+  "ui.listEditor.removeItem": "Remove item {n}",
+  "ui.listEditor.moveUp": "Move item {n} up",
+  "ui.listEditor.moveDown": "Move item {n} down",
+  "ui.listEditor.empty": "No items yet.",
+  "ui.sliderNumber.reset": "Reset",
+  // MentionInput (#368). The listbox lives in a portal with no visible label of
+  // its own, so this IS its accessible name. The empty state deliberately
+  // reuses the generic `noResults` key rather than minting a near-duplicate.
+  "ui.mentionInput.listLabel": "Mention suggestions",
+  // ConfirmDialog's fallback action labels. A real confirmation replaces
+  // `confirmLabel` with the CONSEQUENCE ("Delete skill"); this generic default
+  // exists so the component is never unlabelled.
+  "ui.confirmDialog.confirm": "Confirm",
+  "ui.confirmDialog.cancel": "Cancel",
+  "ui.advancedGroup.title": "Advanced",
+  "ui.advancedGroup.changed": "{count} changed",
+
+  // ── @elabs-ai/components-data ─────────────────────────────────────────────────────────────
+  // The scroll region's accessible name is rendered ONLY when the table actually
+  // overflows its container, so it is never announced for a table that fits.
+  "data.table.scrollRegion": "Table contents, scrollable",
+  // Fallback name for a row's activation control when the row's first cell holds
+  // no primitive value to name it after (see `rowActionLabel`).
+  "data.table.rowAction": "Activate row",
+
+  // ── @elabs-ai/components-charts ───────────────────────────────────────────────────────────
+  // Shared caption for any bare chart surface's layout-shaped skeleton
+  // (ChartFrame, ChartCard, AutoChart all show the same "a chart is loading"
+  // concept — one key, reused, rather than three near-duplicate strings).
+  "charts.chart.loading": "Loading chart…",
+  "charts.metricGrid.loading": "Loading metrics…",
+  // Chart drill-down (#349). The chart SVG is aria-hidden, so these names are
+  // the ONLY thing AT reads for an interactive datapoint — there is no
+  // consumer-side workaround if they stay English.
+  "charts.datapointLayer.label": "Chart data points",
+  "charts.datapoint.label": "{series}, {category}: {value}",
+  "charts.datapoint.labelNoSeries": "{category}: {value}",
+  // Announced when `copyValueOnActivate` puts a datapoint's exact value on the
+  // clipboard — the recovery path for a compact axis label.
+  "charts.datapoint.copied": "Exact value copied",
+
+  // ── @elabs-ai/components-ai ───────────────────────────────────────────────────────────────
+  // Namespaced `ai.<area>.<key>` so package microcopy can't collide with the
+  // generic keys above, or with a future package's. See ADR 0017.
+  //
+  // The three attachment errors are the only @elabs-ai/components-ai strings a user reads as a
+  // SYSTEM MESSAGE rather than a control label — they are the reason this bundle
+  // grew beyond the generic set.
+  "ai.promptInput.errorAccept": "No files match the accepted types.",
+  "ai.promptInput.errorMaxFileSize": "All files exceed the maximum size.",
+  "ai.promptInput.errorMaxFiles": "Too many files. Some were not added.",
+  "ai.promptInput.placeholder": "What would you like to know?",
+  "ai.promptInput.uploadFiles": "Upload files",
+  "ai.promptInput.submit": "Submit",
+  "ai.promptInput.stop": "Stop",
+  "ai.codeBlock.generating": "Generating…",
+  "ai.composer.placeholder": "Ask me anything…",
+  "ai.context.usage": "Model context usage",
+  "ai.contextPanel.back": "Back to context",
+  "ai.contextPanel.toggle": "Toggle context panel",
+  "ai.environmentVariables.toggleVisibility": "Toggle value visibility",
+  "ai.gallery.label": "Image gallery",
+  "ai.gallery.expandImage": "Expand image",
+  "ai.gallery.downloadImage": "Download image",
+  "ai.message.actions": "Message actions",
+  "ai.message.editMessage": "Edit message",
+  "ai.message.feedback": "Message feedback",
+  "ai.message.previousBranch": "Previous branch",
+  "ai.message.nextBranch": "Next branch",
+  "ai.persona.idle": "Assistant idle",
+  "ai.persona.listening": "Assistant listening",
+  "ai.persona.thinking": "Assistant thinking…",
+  "ai.persona.speaking": "Assistant speaking",
+  "ai.persona.asleep": "Assistant asleep",
+  "ai.selectionToolbar.label": "Selection actions",
+  "ai.webPreview.urlPlaceholder": "Enter URL...",
+  "ai.micSelector.searchPlaceholder": "Search microphones...",
+  "ai.messageForm.selectPlaceholder": "Select…",
+  "ai.messageForm.label": "Form",
+  "ai.messageTable.label": "Data table",
+  "ai.voiceSelector.playPreview": "Play preview",
+  "ai.voiceSelector.pausePreview": "Pause preview",
+
+  // ── Streamdown chrome (third-party rendering surface) ──────────────────────
+  // `streamdown` renders its OWN controls inside every streamed-markdown block
+  // (code header, table menus, Mermaid toolbar, external-link interstitial) and
+  // exposes them through a `translations` prop. Those strings live in the
+  // dependency, not in our source, so `pnpm microcopy:check` structurally cannot
+  // see them — without this block a `<LocaleProvider>` stops at the boundary and
+  // the chrome stays English (#310).
+  //
+  // Values are BYTE-IDENTICAL to streamdown@2.5.0's `defaultTranslations`, so
+  // wiring them through `t()` is a no-op for anyone who overrides nothing
+  // (ADR 0017's defaults-unchanged property). Keep them that way on upgrade.
+  //
+  // Deliberately NOT aliased onto the generic `close` / `ai.gallery.downloadImage`
+  // keys: a locale may want different wording inside markdown chrome than in the
+  // surrounding app, and a translator needs the Streamdown surface addressable as
+  // one block.
+  "ai.streamdown.copyCode": "Copy Code",
+  "ai.streamdown.downloadFile": "Download file",
+  "ai.streamdown.downloadDiagram": "Download diagram",
+  "ai.streamdown.downloadDiagramAsSvg": "Download diagram as SVG",
+  "ai.streamdown.downloadDiagramAsPng": "Download diagram as PNG",
+  "ai.streamdown.downloadDiagramAsMmd": "Download diagram as MMD",
+  "ai.streamdown.viewFullscreen": "View fullscreen",
+  "ai.streamdown.exitFullscreen": "Exit fullscreen",
+  "ai.streamdown.mermaidFormatSvg": "SVG",
+  "ai.streamdown.mermaidFormatPng": "PNG",
+  "ai.streamdown.mermaidFormatMmd": "MMD",
+  "ai.streamdown.copyTable": "Copy table",
+  "ai.streamdown.copyTableAsMarkdown": "Copy table as Markdown",
+  "ai.streamdown.copyTableAsCsv": "Copy table as CSV",
+  "ai.streamdown.copyTableAsTsv": "Copy table as TSV",
+  "ai.streamdown.downloadTable": "Download table",
+  "ai.streamdown.downloadTableAsCsv": "Download table as CSV",
+  "ai.streamdown.downloadTableAsMarkdown": "Download table as Markdown",
+  "ai.streamdown.tableFormatMarkdown": "Markdown",
+  "ai.streamdown.tableFormatCsv": "CSV",
+  "ai.streamdown.tableFormatTsv": "TSV",
+  "ai.streamdown.imageNotAvailable": "Image not available",
+  "ai.streamdown.downloadImage": "Download image",
+  "ai.streamdown.openExternalLink": "Open external link?",
+  // Straight apostrophe on purpose — must stay byte-identical to streamdown's
+  // default, so the micro-typography curly-quote preference does not apply here.
+  "ai.streamdown.externalLinkWarning": "You're about to visit an external website.",
+  "ai.streamdown.close": "Close",
+  "ai.streamdown.copyLink": "Copy link",
+  "ai.streamdown.copied": "Copied",
+  "ai.streamdown.openLink": "Open link",
+
+  // ── @elabs-ai/components-viewer (ADR 0024) ─────────────────────────
+  // FileViewer chrome. Every control here is icon-only, so these ARE the
+  // accessible names — a non-English screen-reader user has no workaround.
+  "viewer.label": "File viewer",
+  // The scrolling content region's accessible name. It is a focusable tab stop
+  // (WCAG 2.1.1: a pane that scrolls but holds nothing focusable is unreachable
+  // from a keyboard), so it needs a name as well as a role.
+  "viewer.content": "File content",
+  "viewer.download": "Download {name}",
+  "viewer.raw": "Show source",
+  "viewer.rendered": "Show rendered",
+  // States. `loading` announces the region once (role="status"); the skeleton
+  // itself is aria-hidden, so this is the only thing AT hears.
+  "viewer.loading": "Loading {name}…",
+  "viewer.empty": "No file selected",
+  "viewer.emptyBody": "Choose a file to preview it here.",
+  // Failures. Each maps to one ViewerErrorCode, so the code is the contract and
+  // the wording can change per locale without touching component logic.
+  "viewer.error.unsupportedFormat": "Can't preview this file type",
+  "viewer.error.unsupportedFormatBody":
+    "{name} can be downloaded, but there's no preview for it here.",
+  "viewer.error.parserMissing": "Preview unavailable",
+  "viewer.error.parserMissingBody": "Previewing {name} needs {packages} to be installed.",
+  "viewer.error.readFailed": "Couldn't open this file",
+  "viewer.error.readFailedBody":
+    "{name} couldn't be read. It may have moved, or you may not have access.",
+  "viewer.error.parseFailed": "Couldn't read this file",
+  "viewer.error.parseFailedBody": "{name} isn't a valid {format} file, or it's damaged.",
+  "viewer.error.imageFailedTitle": "Couldn't show this image",
+  "viewer.error.imageFailed": "{name} could not be displayed.",
+  "viewer.retry": "Try again",
+  // Table view (CSV/TSV). The count is a summary for the whole grid.
+  "viewer.table.caption": "{rows} rows, {columns} columns",
+  "viewer.table.truncated": "Showing the first {count} rows.",
+  "viewer.table.emptyCell": "Empty",
+  // Text and JSON views.
+  "viewer.text.truncated": "Showing the first {shown} of {total} characters.",
+  "viewer.json.tree": "JSON structure",
+  // Page, scale and rotation chrome (ADR 0026). Format-agnostic: one pager
+  // serves PDF pages and PowerPoint slides, so the words are about "pages" and
+  // the slide-specific wording lives on the slide itself.
+  "viewer.pager.controls": "Pages",
+  "viewer.pager.previous": "Previous page",
+  "viewer.pager.next": "Next page",
+  // The field's own accessible name. The visible "of {total}" beside it is not
+  // a label — a screen reader would read the two as one run without this.
+  "viewer.pager.pageNumber": "Page number",
+  "viewer.pager.of": "of {total}",
+  // Live region: a repainted canvas and a changed input value both announce
+  // nothing, so this sentence is the only confirmation a page turned.
+  "viewer.pager.status": "Page {page} of {total}",
+  "viewer.zoom.controls": "Zoom",
+  "viewer.zoom.in": "Zoom in",
+  "viewer.zoom.out": "Zoom out",
+  "viewer.zoom.level": "Zoom level",
+  "viewer.zoom.fitWidth": "Fit width",
+  "viewer.zoom.fitPage": "Fit page",
+  "viewer.zoom.status": "Zoom {level}",
+  "viewer.rotate": "Rotate clockwise",
+  // PDF view.
+  "viewer.pdf.page": "Page {page}",
+  "viewer.pdf.pages": "Document pages",
+  "viewer.pdf.pageFailed": "Page {page} couldn't be drawn.",
+  // Media view (video / audio).
+  "viewer.media.label": "{name} player",
+  "viewer.media.unsupportedTitle": "Can't play this file",
+  "viewer.media.unsupported": "This browser can't play {name}.",
+  // Office views. A preview shows a document's STRUCTURE, not Word's or
+  // PowerPoint's page layout — the copy never promises a faithful reproduction.
+  "viewer.docx.empty": "This document has no text",
+  "viewer.sheet.tabs": "Sheets",
+  "viewer.pptx.slide": "Slide {slide}",
+  "viewer.pptx.untitled": "Untitled slide",
+  "viewer.pptx.notes": "Speaker notes",
+  "viewer.pptx.empty": "This slide has no text",
+  // Code and markdown views. `file.empty` is shared: "the file opened and there
+  // is nothing in it" is one message whatever the format.
+  "viewer.file.empty": "This file is empty",
+  // Find-in-document (ADR 0025). The count is a live region read on every step,
+  // so it stays short; `findNone` replaces it rather than sitting beside it, so
+  // a fruitless search never reads as "0 of 0".
+  "viewer.find.open": "Find in document",
+  "viewer.find.label": "Find in document",
+  "viewer.find.placeholder": "Find…",
+  "viewer.find.close": "Close find",
+  "viewer.find.previous": "Previous match",
+  "viewer.find.next": "Next match",
+  "viewer.find.caseSensitive": "Match case",
+  "viewer.find.count": "{index} of {total}",
+  "viewer.find.none": "No matches",
+  "viewer.find.capped": "Showing the first {limit} matches of {total}.",
+  // Citations / passages the app points the viewer at. A miss is a STATE, not a
+  // silent no-op — the reader is told the passage could not be located, and
+  // "past the part we previewed" is different news from "not in this document".
+  "viewer.highlight.notFound": "Couldn't find that passage in this document.",
+  "viewer.highlight.notFoundTruncated":
+    "That passage may be beyond the part of this document we could preview.",
+  "viewer.highlight.unsupported": "This build can't point at part of a {format} file.",
+  "viewer.highlight.previous": "Previous passage",
+  "viewer.highlight.next": "Next passage",
+  "viewer.highlight.count": "Passage {index} of {total}",
+};

package/src/components/match-highlight/index.ts

@@ -0,0 +1,7 @@
+export {
+  MatchHighlight,
+  queryToRanges,
+  normalizeRanges,
+  type MatchHighlightProps,
+  type MatchRange,
+} from "./match-highlight";

package/src/components/match-highlight/match-highlight.stories.tsx

@@ -0,0 +1,146 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../button";
+import { MatchHighlight, queryToRanges } from "./match-highlight";
+
+const meta = {
+  title: "Typography/MatchHighlight",
+  component: MatchHighlight,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Wraps query matches inside a string in real `<mark>` elements, styled with the semantic `--highlight` token pair (AA-legible ink in every theme). Presentation-only — pass `query` (case-insensitive by default) or precomputed `ranges` from your own fuzzy matcher.",
+      },
+    },
+  },
+  argTypes: {
+    text: { control: "text" },
+    query: { control: "text" },
+    caseSensitive: { control: "boolean" },
+    activeIndex: { control: "number" },
+  },
+} satisfies Meta<typeof MatchHighlight>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { text: "My Notes note", query: "note" },
+  render: (args) => (
+    <p className="max-w-md text-body text-foreground">
+      <MatchHighlight {...args} />
+    </p>
+  ),
+};
+
+/** A search-result title inside a paragraph — the canonical omnisearch use. */
+export const InParagraph: Story = {
+  render: () => (
+    <p className="max-w-md text-body text-foreground">
+      The <MatchHighlight text="quarterly revenue report" query="revenue" /> was updated after the{" "}
+      <MatchHighlight text="board meeting" query="board" /> concluded.
+    </p>
+  ),
+};
+
+/** Multiple needles (e.g. every token of a multi-word query). */
+export const MultipleNeedles: Story = {
+  args: { text: "red green blue amber", query: ["red", "blue"] },
+  render: (args) => (
+    <p className="text-body text-foreground">
+      <MatchHighlight {...args} />
+    </p>
+  ),
+};
+
+/** Precomputed ranges from a fuzzy matcher (overlapping/adjacent are merged). */
+export const PrecomputedRanges: Story = {
+  render: () => (
+    <p className="text-body text-foreground">
+      <MatchHighlight
+        text="src/features/document/backlinks-panel.tsx"
+        ranges={[
+          [4, 12],
+          [13, 21],
+        ]}
+      />
+    </p>
+  ),
+};
+
+/**
+ * `activeIndex` marks ONE of the matches as the current one — the "3 of 12" a
+ * find bar or a document citation is pointing at. It is never colour-only: the
+ * current mark also carries an outline and `aria-current="true"`, and it can be
+ * found for scrolling via `[data-slot="match-highlight-mark"][data-active]`.
+ */
+export const CurrentMatch: Story = {
+  args: {
+    text: "Revenue rose in Q1. Revenue fell in Q2. Revenue held flat in Q3.",
+    query: "revenue",
+    activeIndex: 1,
+  },
+  render: (args) => (
+    <p className="max-w-md text-body text-foreground">
+      <MatchHighlight {...args} />
+    </p>
+  ),
+};
+
+/** Stepping through matches — what a find bar drives. */
+export const SteppingThroughMatches: Story = {
+  args: { text: "", query: "" },
+  render: function SteppingThroughMatches() {
+    const text =
+      "The report notes a delay, the delay was escalated, and the delay is now resolved.";
+    const total = queryToRanges(text, "delay").length;
+    const [index, setIndex] = useState(0);
+    const step = (by: number) => setIndex((i) => (i + by + total) % total);
+    return (
+      <div className="max-w-md space-y-3">
+        <p className="text-body text-foreground">
+          <MatchHighlight text={text} query="delay" activeIndex={index} />
+        </p>
+        <div className="flex items-center gap-2">
+          <Button size="sm" variant="outline" onClick={() => step(-1)}>
+            Previous
+          </Button>
+          <Button size="sm" variant="outline" onClick={() => step(1)}>
+            Next
+          </Button>
+          <span aria-live="polite" className="text-meta text-muted-foreground">
+            {index + 1} of {total}
+          </span>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** No match → the string renders normally (never broken markup). */
+export const NoMatch: Story = {
+  args: { text: "nothing to highlight here", query: "zzz" },
+  render: (args) => (
+    <p className="text-body text-foreground">
+      <MatchHighlight {...args} />
+    </p>
+  ),
+};
+
+/**
+ * Long content truncates cleanly. The flex child needs `min-w-0` for `truncate`
+ * to engage (the interaction-guidelines "silent culprit").
+ */
+export const LongStringTruncation: Story = {
+  render: () => (
+    <div className="flex w-64 items-center gap-2 rounded-md border border-border bg-card p-2">
+      <span className="min-w-0 flex-1 truncate text-body text-foreground">
+        <MatchHighlight
+          text="A very long document title that will definitely overflow its container and must ellipsis"
+          query="document"
+        />
+      </span>
+    </div>
+  ),
+};