@elabs-ai/components-ui 4.0.0

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

@@ -0,0 +1,202 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import { MatchHighlight, queryToRanges, normalizeRanges } from "./match-highlight";
+
+describe("MatchHighlight", () => {
+  it("renders one <mark> per case-insensitive query occurrence, text intact", () => {
+    const { container } = render(<MatchHighlight text="My Notes note" query="note" />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(2);
+    expect(marks[0]?.textContent).toBe("Note");
+    expect(marks[1]?.textContent).toBe("note");
+    // Full string is preserved for screen readers.
+    expect(container.textContent).toBe("My Notes note");
+  });
+
+  it("merges adjacent precomputed ranges into a single <mark>", () => {
+    const { container } = render(
+      <MatchHighlight
+        text="abcdef"
+        ranges={[
+          [0, 2],
+          [2, 4],
+        ]}
+      />,
+    );
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.textContent).toBe("abcd"); // [0,4)
+  });
+
+  it("renders no <mark> for a non-matching query", () => {
+    const { container } = render(<MatchHighlight text="hello world" query="xyz" />);
+    expect(container.querySelectorAll("mark")).toHaveLength(0);
+    expect(container.textContent).toBe("hello world");
+  });
+
+  it("renders no <mark> for empty / whitespace-only-vs-nothing query", () => {
+    const { container } = render(<MatchHighlight text="hello" query="" />);
+    expect(container.querySelectorAll("mark")).toHaveLength(0);
+    expect(container.textContent).toBe("hello");
+  });
+
+  it("highlights multiple needles", () => {
+    const { container } = render(<MatchHighlight text="red green blue" query={["red", "blue"]} />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(2);
+    expect(marks[0]?.textContent).toBe("red");
+    expect(marks[1]?.textContent).toBe("blue");
+  });
+
+  it("respects caseSensitive", () => {
+    const { container } = render(<MatchHighlight text="Note note" query="note" caseSensitive />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.textContent).toBe("note");
+  });
+
+  it("ranges win over query", () => {
+    const { container } = render(<MatchHighlight text="abcdef" query="ef" ranges={[[0, 1]]} />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.textContent).toBe("a");
+  });
+
+  it("handles matches at string start and end (non-adjacent stay separate)", () => {
+    const { container } = render(<MatchHighlight text="abc abc" query="abc" />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(2);
+    expect(marks[0]?.textContent).toBe("abc"); // at index 0 (start)
+    expect(marks[1]?.textContent).toBe("abc"); // ending at text.length (end)
+    expect(container.textContent).toBe("abc abc");
+  });
+
+  it("merges two adjacent query matches into one contiguous mark (no seam)", () => {
+    const { container } = render(<MatchHighlight text="abcabc" query="abc" />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.textContent).toBe("abcabc");
+  });
+
+  it("handles unicode / accented needles without index drift", () => {
+    const { container } = render(<MatchHighlight text="café Café" query="café" />);
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(2);
+    expect(container.textContent).toBe("café Café");
+  });
+
+  it("styles the mark with the semantic highlight token pair", () => {
+    const { container } = render(<MatchHighlight text="find me" query="me" />);
+    const mark = container.querySelector("mark");
+    expect(mark?.className).toContain("bg-highlight");
+    expect(mark?.className).toContain("text-highlight-foreground");
+  });
+
+  it("marks exactly one mark as current for activeIndex, and none by default", () => {
+    const { container, rerender } = render(<MatchHighlight text="abc abc abc" query="abc" />);
+    expect(container.querySelectorAll("mark[data-active]")).toHaveLength(0);
+    expect(container.querySelectorAll("mark[aria-current]")).toHaveLength(0);
+
+    rerender(<MatchHighlight text="abc abc abc" query="abc" activeIndex={1} />);
+    const active = container.querySelectorAll("mark[data-active]");
+    expect(active).toHaveLength(1);
+    expect(active[0]?.getAttribute("aria-current")).toBe("true");
+    // Second of the three, in document order.
+    expect(container.querySelectorAll("mark")[1]).toBe(active[0]);
+  });
+
+  it("gives the current mark its own token pair, distinct from the rest", () => {
+    const { container } = render(
+      <MatchHighlight text="abc abc" query="abc" activeIndex={0} data-testid="mh" />,
+    );
+    const [current, other] = Array.from(container.querySelectorAll("mark"));
+    expect(current?.className).toContain("bg-highlight-active");
+    expect(current?.className).toContain("text-highlight-active-foreground");
+    expect(other?.className).toContain("bg-highlight");
+    expect(other?.className).not.toContain("bg-highlight-active");
+  });
+
+  it("signals the current mark without relying on colour (WCAG 1.4.1)", () => {
+    const { container } = render(<MatchHighlight text="abc abc" query="abc" activeIndex={0} />);
+    const current = container.querySelector("mark[data-active]");
+    // An outline is a shape cue that survives greyscale; aria-current carries it
+    // to assistive tech, which never sees either colour.
+    expect(current?.className).toContain("outline-2");
+    expect(current?.getAttribute("aria-current")).toBe("true");
+  });
+
+  it("ignores an out-of-range activeIndex rather than clamping", () => {
+    const { container } = render(<MatchHighlight text="abc abc" query="abc" activeIndex={7} />);
+    expect(container.querySelectorAll("mark")).toHaveLength(2);
+    expect(container.querySelectorAll("mark[data-active]")).toHaveLength(0);
+  });
+
+  it("counts activeIndex against the MERGED ranges, not the raw ones", () => {
+    // [0,2) + [2,4) merge into one "abcd", so index 1 is the SECOND mark ("f").
+    const { container } = render(
+      <MatchHighlight
+        text="abcdef"
+        ranges={[
+          [0, 2],
+          [2, 4],
+          [5, 6],
+        ]}
+        activeIndex={1}
+      />,
+    );
+    const marks = container.querySelectorAll("mark");
+    expect(marks).toHaveLength(2);
+    expect(container.querySelector("mark[data-active]")?.textContent).toBe("f");
+  });
+
+  it("exposes stable data-slot selectors on the root and every mark", () => {
+    const { container } = render(<MatchHighlight text="abc abc" query="abc" />);
+    expect(container.querySelector('[data-slot="match-highlight"]')?.tagName).toBe("SPAN");
+    expect(container.querySelectorAll('[data-slot="match-highlight-mark"]')).toHaveLength(2);
+  });
+
+  it("merges className last and spreads props onto the span", () => {
+    const { container } = render(
+      <MatchHighlight text="x" query="x" className="custom-x" data-testid="mh" />,
+    );
+    const span = container.querySelector("span");
+    expect(span?.className).toContain("custom-x");
+    expect(span?.getAttribute("data-testid")).toBe("mh");
+  });
+});
+
+describe("range helpers", () => {
+  it("queryToRanges finds overlapping-needle matches", () => {
+    // "ab" [0,2) and "bc" [1,3) overlap; normalize should later merge.
+    expect(queryToRanges("abc", ["ab", "bc"])).toEqual([
+      [0, 2],
+      [1, 3],
+    ]);
+  });
+
+  it("normalizeRanges clamps, sorts, and merges overlaps + adjacency", () => {
+    expect(
+      normalizeRanges(
+        [
+          [1, 3],
+          [2, 5],
+          [5, 6],
+        ],
+        10,
+      ),
+    ).toEqual([[1, 6]]);
+    expect(
+      normalizeRanges(
+        [
+          [-2, 2],
+          [8, 99],
+        ],
+        10,
+      ),
+    ).toEqual([
+      [0, 2],
+      [8, 10],
+    ]);
+    expect(normalizeRanges([[4, 4]], 10)).toEqual([]); // empty range dropped
+  });
+});

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

@@ -0,0 +1,145 @@
+import { type HTMLAttributes, type ReactNode, forwardRef, Fragment } from "react";
+import { cn } from "../../lib/cn";
+
+/** A half-open `[start, end)` character range within the text. */
+export type MatchRange = readonly [number, number];
+
+export interface MatchHighlightProps extends HTMLAttributes<HTMLSpanElement> {
+  /** The full string to render. */
+  text: string;
+  /**
+   * One or more needles to highlight. Case-insensitive by default. Ignored when
+   * `ranges` is supplied.
+   */
+  query?: string | string[];
+  /**
+   * Precomputed match ranges (e.g. from a fuzzy matcher / MiniSearch). Wins over
+   * `query` when supplied. Overlapping and adjacent ranges are merged.
+   */
+  ranges?: readonly MatchRange[];
+  /** Match `query` case-sensitively. @default false */
+  caseSensitive?: boolean;
+  /**
+   * Which mark is the CURRENT one, 0-based among the resolved (merged, sorted)
+   * ranges. `-1` or omitted means none is.
+   *
+   * "One of twelve" and "the one you are on" are different meanings, so the
+   * current mark gets its own token pair rather than an opacity tweak — and,
+   * because colour is never the only channel (WCAG 1.4.1), an outline and
+   * `aria-current="true"` as well. It also carries `data-active`, which is how
+   * a caller finds it to scroll it into view:
+   * `root.querySelector('[data-slot="match-highlight-mark"][data-active]')`.
+   */
+  activeIndex?: number;
+}
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Find every occurrence of each needle in `text` and return their `[start, end)`
+ * ranges. Uses a per-needle global regex so indices land on the ORIGINAL string
+ * (unicode-safe — no `toLowerCase()` length drift), handling multiple needles and
+ * case folding. Empty needles are ignored.
+ */
+export function queryToRanges(
+  text: string,
+  query: string | string[],
+  caseSensitive = false,
+): MatchRange[] {
+  const needles = (Array.isArray(query) ? query : [query]).filter((q) => q.length > 0);
+  if (needles.length === 0 || text.length === 0) return [];
+  const flags = caseSensitive ? "gu" : "giu";
+  const out: MatchRange[] = [];
+  for (const needle of needles) {
+    let re: RegExp;
+    try {
+      re = new RegExp(escapeRegExp(needle), flags);
+    } catch {
+      continue; // pathological needle — skip rather than throw
+    }
+    for (const m of text.matchAll(re)) {
+      if (m.index === undefined) continue;
+      const end = m.index + m[0].length;
+      if (end > m.index) out.push([m.index, end]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Clamp ranges to `[0, len)`, drop empty/invalid ones, sort, and merge
+ * overlapping AND adjacent ranges (so `[0,2]` + `[2,4]` → a single `[0,4]`).
+ */
+export function normalizeRanges(ranges: readonly MatchRange[], len: number): MatchRange[] {
+  const clamped = ranges
+    .map(([a, b]): MatchRange => [Math.max(0, Math.min(a, b)), Math.min(len, Math.max(a, b))])
+    .filter(([a, b]) => a < b);
+  clamped.sort((x, y) => x[0] - y[0] || x[1] - y[1]);
+  const merged: [number, number][] = [];
+  for (const [a, b] of clamped) {
+    const last = merged[merged.length - 1];
+    if (last && a <= last[1]) {
+      last[1] = Math.max(last[1], b);
+    } else {
+      merged.push([a, b]);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Render `text` with the query matches wrapped in real `<mark>` elements. Purely
+ * presentational: pass `query` to let it compute ranges (case-insensitive by
+ * default), or `ranges` from your own fuzzy engine. Marks use the semantic
+ * `--highlight` token pair (AA-legible ink in every theme). Screen readers read
+ * the full string naturally.
+ */
+export const MatchHighlight = forwardRef<HTMLSpanElement, MatchHighlightProps>(
+  function MatchHighlight(
+    { text, query, ranges, caseSensitive = false, activeIndex = -1, className, ...props },
+    ref,
+  ) {
+    const resolved = normalizeRanges(
+      ranges ?? (query != null ? queryToRanges(text, query, caseSensitive) : []),
+      text.length,
+    );
+
+    const segments: ReactNode[] = [];
+    let cursor = 0;
+    resolved.forEach(([start, end], index) => {
+      if (start > cursor) {
+        segments.push(<Fragment key={`t${cursor}`}>{text.slice(cursor, start)}</Fragment>);
+      }
+      const active = index === activeIndex;
+      segments.push(
+        <mark
+          key={`m${start}`}
+          data-slot="match-highlight-mark"
+          // Present-or-absent, so the current mark is still identifiable in
+          // greyscale and to a screen reader — the colour swap below is the
+          // enhancement, not the signal (WCAG 1.4.1).
+          data-active={active ? "" : undefined}
+          aria-current={active ? "true" : undefined}
+          className={cn(
+            "rounded-sm px-0.5 font-medium",
+            active
+              ? "outline-foreground bg-highlight-active text-highlight-active-foreground outline-2 outline-offset-1"
+              : "bg-highlight text-highlight-foreground",
+          )}
+        >
+          {text.slice(start, end)}
+        </mark>,
+      );
+      cursor = end;
+    });
+    if (cursor < text.length) {
+      segments.push(<Fragment key={`t${cursor}`}>{text.slice(cursor)}</Fragment>);
+    }
+
+    return (
+      <span ref={ref} data-slot="match-highlight" className={cn(className)} {...props}>
+        {segments}
+      </span>
+    );
+  },
+);

package/src/components/mention-input/index.ts

@@ -0,0 +1,28 @@
+export {
+  MentionInput,
+  MentionInputContent,
+  MentionInputEmpty,
+  MentionInputItem,
+  MentionInputList,
+  MentionInputTextarea,
+  useMentionInput,
+  type MentionInputContentProps,
+  type MentionInputContextValue,
+  type MentionInputEmptyProps,
+  type MentionInputItemProps,
+  type MentionInputListProps,
+  type MentionInputProps,
+  type MentionInputTextareaProps,
+} from "./mention-input";
+export {
+  defaultMentionFilter,
+  insertMention,
+  mentionAt,
+  mentionEnd,
+  remapMentions,
+  serializeMentions,
+  type InsertMentionResult,
+  type Mention,
+  type MentionOption,
+  type MentionValue,
+} from "./mention-value";

package/src/components/mention-input/mention-input-mirror.stories.tsx

@@ -0,0 +1,171 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import { useId, type CSSProperties } from "react";
+import { Label } from "../label";
+import {
+  MentionInput,
+  MentionInputContent,
+  MentionInputEmpty,
+  MentionInputItem,
+  MentionInputList,
+  MentionInputTextarea,
+} from "./mention-input";
+import type { MentionOption, MentionValue } from "./mention-value";
+
+/**
+ * The `MutationObserver` arm of the mirror re-measure, pinned on its own.
+ *
+ * ### Why this lives in its own file
+ *
+ * The lock is **order-dependent**, and that was measured, not guessed. With this
+ * story co-resident with the other `MentionInput` stories, deleting the
+ * `MutationObserver` left the whole suite green; running the same story in
+ * isolation, the same deletion is RED 2/2. Something a preceding story leaves
+ * behind in the shared page re-measures the mirror for an unrelated reason. A
+ * lock that only holds when it runs alone is not a lock at all in CI — so it
+ * gets its own story file, which the runner loads as its own test file.
+ *
+ * ### What it pins
+ *
+ * Every box-affecting property of the field is nailed to absolute pixels, so
+ * `ResizeObserver` is structurally unable to fire, and `document.fonts.ready` is
+ * awaited before the flip so that arm cannot fire late. `h-20 w-[26rem]` was NOT
+ * enough: padding and border derived from `rem` can move by sub-integer amounts
+ * across a theme change, which `clientWidth`'s integer rounding hides but
+ * `ResizeObserver` still reports.
+ *
+ * The play function asserts the box did not move — fractionally via
+ * `getBoundingClientRect` as well as in integers — so the isolation is proven in
+ * the test rather than argued for in a comment.
+ */
+const meta = {
+  title: "Forms/MentionInput/Mirror re-measure",
+  component: MentionInput,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Regression lock for the chip mirror's re-measure. Isolated in its own " +
+          "story file so no sibling story can mask the arm it pins.",
+      },
+    },
+  },
+} satisfies Meta<typeof MentionInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const ROSTER: MentionOption[] = [
+  { id: "u-lovelace", label: "Ada Lovelace", description: "Analytical Engine" },
+  { id: "u-hopper", label: "Grace Hopper", description: "Compilers" },
+];
+
+const MIRROR_VALUE: MentionValue = {
+  text: "@Ada Lovelace ships",
+  mentions: [{ id: "u-lovelace", label: "Ada Lovelace", start: 0 }],
+};
+
+/** Every degree of freedom the field's box has, removed. */
+const NAILED_BOX: CSSProperties = {
+  boxSizing: "border-box",
+  width: "420px",
+  height: "80px",
+  paddingTop: "8px",
+  paddingRight: "12px",
+  paddingBottom: "8px",
+  paddingLeft: "12px",
+  borderWidth: "1px",
+  lineHeight: "20px",
+  fontSize: "14px",
+  overflow: "hidden",
+  resize: "none",
+};
+
+/** The element the theme decorator actually wrote `data-theme` onto. */
+function themeHost(): HTMLElement {
+  return document.body.hasAttribute("data-theme") ? document.body : document.documentElement;
+}
+
+/**
+ * **Regression lock — the `MutationObserver` arm, individually pinned.**
+ *
+ * An in-place `data-theme` flip, exactly what `ThemeSwitcher` does (no remount).
+ * Deleting the `MutationObserver` block turns this RED with the original bug's
+ * symptom verbatim: the overlay stuck on the `:root` fallback `Inter` while the
+ * field renders `IBM Plex Mono`.
+ */
+export const TracksThemeChangeWithNailedBox: Story = {
+  args: { options: ROSTER, children: null },
+  render: function MirrorNailedBoxStory() {
+    const id = useId();
+    return (
+      <div className="space-y-2">
+        <Label htmlFor={id}>Comment</Label>
+        <MentionInput options={ROSTER} defaultValue={MIRROR_VALUE}>
+          <MentionInputTextarea id={id} style={NAILED_BOX} placeholder="Type @ to mention…" />
+          <MentionInputContent>
+            <MentionInputList>
+              {(option) => <MentionInputItem key={option.id} option={option} />}
+            </MentionInputList>
+            <MentionInputEmpty />
+          </MentionInputContent>
+        </MentionInput>
+      </div>
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const field = within(canvasElement).getByRole("textbox", {
+      name: "Comment",
+    }) as HTMLTextAreaElement;
+    const overlay = canvasElement.querySelector<HTMLElement>('[data-slot="mention-input-overlay"]');
+    await expect(overlay).not.toBeNull();
+
+    // Settle the fonts arm before touching anything, so it cannot fire late.
+    await document.fonts.ready;
+
+    const boxOf = (el: HTMLElement) => {
+      const r = el.getBoundingClientRect();
+      return { w: r.width, h: r.height, cw: el.clientWidth, ch: el.clientHeight };
+    };
+    const before = boxOf(field);
+    const host = themeHost();
+    const original = host.getAttribute("data-theme");
+    const fontBefore = getComputedStyle(field).fontFamily;
+
+    try {
+      await step("the mirror starts in parity with the field", async () => {
+        await expect(getComputedStyle(overlay!).fontFamily).toBe(fontBefore);
+      });
+
+      await step("flip data-theme in place", async () => {
+        // The shipped themes share one font stack, so the attribute flip alone
+        // changes nothing measurable. Pair it with a scoped `--font-sans`
+        // override (the same root `style` the observer also watches) so the
+        // parity assertion below cannot pass vacuously.
+        host.style.setProperty("--font-sans", '"Times New Roman", serif');
+        host.setAttribute("data-theme", original === "dark" ? "light" : "dark");
+        await waitFor(() => {
+          expect(getComputedStyle(field).fontFamily).not.toBe(fontBefore);
+        });
+      });
+
+      await step("the box did not move — ResizeObserver cannot have fired", async () => {
+        const after = boxOf(field);
+        await expect(after.w).toBe(before.w);
+        await expect(after.h).toBe(before.h);
+        await expect(after.cw).toBe(before.cw);
+        await expect(after.ch).toBe(before.ch);
+      });
+
+      await step("the mirror re-measured — only the MutationObserver could have", async () => {
+        await waitFor(() => {
+          expect(getComputedStyle(overlay!).fontFamily).toBe(getComputedStyle(field).fontFamily);
+        });
+      });
+    } finally {
+      host.style.removeProperty("--font-sans");
+      if (original === null) host.removeAttribute("data-theme");
+      else host.setAttribute("data-theme", original);
+    }
+  },
+};