@elabs-ai/components-ui 4.0.0

package/src/components/mention-input/mention-value.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import {
+  defaultMentionFilter,
+  insertMention,
+  mentionAt,
+  mentionEnd,
+  remapMentions,
+  serializeMentions,
+  type MentionOption,
+  type MentionValue,
+} from "./mention-value";
+
+const ada: MentionOption = { id: "u1", label: "Ada Lovelace", keywords: ["ada", "math"] };
+const grace: MentionOption = { id: "u2", label: "Grace Hopper" };
+
+/** "Hi @Ada Lovelace how are you" with the mention recorded at offset 3. */
+const oneMention: MentionValue = {
+  text: "Hi @Ada Lovelace how are you",
+  mentions: [{ id: "u1", label: "Ada Lovelace", start: 3 }],
+};
+
+/** "@Ada Lovelace and @Grace Hopper ship" — two mentions, at 0 and 18. */
+const twoMentions: MentionValue = {
+  text: "@Ada Lovelace and @Grace Hopper ship",
+  mentions: [
+    { id: "u1", label: "Ada Lovelace", start: 0 },
+    { id: "u2", label: "Grace Hopper", start: 18 },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// T1 — remapMentions offset algebra
+// ---------------------------------------------------------------------------
+
+describe("T1 remapMentions — offset algebra", () => {
+  it("is idempotent when the text is unchanged", () => {
+    expect(remapMentions(oneMention, oneMention.text)).toEqual(oneMention.mentions);
+  });
+
+  it("shifts a mention when text is inserted BEFORE it", () => {
+    // "Hi " -> "Oh Hi " (3 chars inserted at 0)
+    const next = "Oh Hi @Ada Lovelace how are you";
+    expect(remapMentions(oneMention, next)).toEqual([
+      { id: "u1", label: "Ada Lovelace", start: 6 },
+    ]);
+  });
+
+  it("holds the offset when text is inserted AFTER it", () => {
+    const next = "Hi @Ada Lovelace how are you today";
+    expect(remapMentions(oneMention, next)).toEqual([
+      { id: "u1", label: "Ada Lovelace", start: 3 },
+    ]);
+  });
+
+  it("holds the first and shifts the second when text is inserted BETWEEN them", () => {
+    const next = "@Ada Lovelace and also @Grace Hopper ship";
+    expect(remapMentions(twoMentions, next)).toEqual([
+      { id: "u1", label: "Ada Lovelace", start: 0 },
+      { id: "u2", label: "Grace Hopper", start: 23 },
+    ]);
+  });
+
+  it("shifts every mention when text is removed before both", () => {
+    // Drop the leading "Hi " from a two-mention value.
+    const prev: MentionValue = {
+      text: "Hi @Ada Lovelace and @Grace Hopper",
+      mentions: [
+        { id: "u1", label: "Ada Lovelace", start: 3 },
+        { id: "u2", label: "Grace Hopper", start: 21 },
+      ],
+    };
+    expect(remapMentions(prev, "@Ada Lovelace and @Grace Hopper")).toEqual([
+      { id: "u1", label: "Ada Lovelace", start: 0 },
+      { id: "u2", label: "Grace Hopper", start: 18 },
+    ]);
+  });
+
+  it("DROPS a mention when the edit intersects its range", () => {
+    // Delete one character out of the middle of "@Ada Lovelace".
+    const next = "Hi @Ada Loveace how are you";
+    expect(remapMentions(oneMention, next)).toEqual([]);
+  });
+
+  it("DROPS a mention when a character is inserted inside its range", () => {
+    const next = "Hi @Adda Lovelace how are you";
+    expect(remapMentions(oneMention, next)).toEqual([]);
+  });
+
+  it("keeps a mention when a character is inserted flush against its end", () => {
+    const next = "Hi @Ada Lovelace! how are you";
+    expect(remapMentions(oneMention, next)).toEqual([
+      { id: "u1", label: "Ada Lovelace", start: 3 },
+    ]);
+  });
+
+  it("survives a multi-mention paste that replaces a middle span", () => {
+    // Replace " and " (between the two mentions) with " plus ".
+    const next = "@Ada Lovelace plus @Grace Hopper ship";
+    expect(remapMentions(twoMentions, next)).toEqual([
+      { id: "u1", label: "Ada Lovelace", start: 0 },
+      { id: "u2", label: "Grace Hopper", start: 19 },
+    ]);
+  });
+
+  it("drops every mention when the whole text is replaced", () => {
+    expect(remapMentions(twoMentions, "totally different text")).toEqual([]);
+  });
+
+  it("re-validates survivors against the new text (a shifted offset that no longer spells the token is dropped)", () => {
+    // A hand-crafted value whose recorded offset is a lie: re-validation must
+    // reject it rather than trusting the arithmetic.
+    const lying: MentionValue = {
+      text: "Hi @Ada Lovelace",
+      mentions: [{ id: "u1", label: "Grace Hopper", start: 3 }],
+    };
+    expect(remapMentions(lying, "Hi! @Ada Lovelace")).toEqual([]);
+  });
+
+  it("honours a non-default trigger character", () => {
+    const hash: MentionValue = {
+      text: "see #Roadmap now",
+      mentions: [{ id: "t1", label: "Roadmap", start: 4 }],
+    };
+    expect(remapMentions(hash, "please see #Roadmap now", "#")).toEqual([
+      { id: "t1", label: "Roadmap", start: 11 },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// T2 — serializeMentions shape
+// ---------------------------------------------------------------------------
+
+describe("T2 serializeMentions — the consumer contract", () => {
+  it("returns { text, mentionedIds }", () => {
+    expect(serializeMentions(twoMentions)).toEqual({
+      text: "@Ada Lovelace and @Grace Hopper ship",
+      mentionedIds: ["u1", "u2"],
+    });
+  });
+
+  it("returns an empty id list for a mention-free value", () => {
+    expect(serializeMentions({ text: "just words", mentions: [] })).toEqual({
+      text: "just words",
+      mentionedIds: [],
+    });
+  });
+
+  it("dedupes ids — two mentions of the same person yield one id", () => {
+    const twice: MentionValue = {
+      text: "@Ada Lovelace and @Ada Lovelace",
+      mentions: [
+        { id: "u1", label: "Ada Lovelace", start: 0 },
+        { id: "u1", label: "Ada Lovelace", start: 18 },
+      ],
+    };
+    expect(serializeMentions(twice).mentionedIds).toEqual(["u1"]);
+  });
+
+  it("emits ids in DOCUMENT order, not insertion order", () => {
+    const outOfOrder: MentionValue = {
+      text: "@Ada Lovelace and @Grace Hopper",
+      mentions: [
+        { id: "u2", label: "Grace Hopper", start: 18 },
+        { id: "u1", label: "Ada Lovelace", start: 0 },
+      ],
+    };
+    expect(serializeMentions(outOfOrder).mentionedIds).toEqual(["u1", "u2"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// insertMention
+// ---------------------------------------------------------------------------
+
+describe("insertMention", () => {
+  it("replaces trigger+query with trigger+label+space and reports the caret after the space", () => {
+    const value: MentionValue = { text: "Hi @ad", mentions: [] };
+    const result = insertMention(value, ada, "@", 3, 6);
+    expect(result.value.text).toBe("Hi @Ada Lovelace ");
+    expect(result.value.mentions).toEqual([{ id: "u1", label: "Ada Lovelace", start: 3 }]);
+    expect(result.caret).toBe(17);
+  });
+
+  it("keeps text that follows the caret and shifts later mentions", () => {
+    const value: MentionValue = {
+      text: "@gr ping @Ada Lovelace",
+      mentions: [{ id: "u1", label: "Ada Lovelace", start: 9 }],
+    };
+    const result = insertMention(value, grace, "@", 0, 3);
+    expect(result.value.text).toBe("@Grace Hopper  ping @Ada Lovelace");
+    expect(result.value.mentions).toEqual([
+      { id: "u2", label: "Grace Hopper", start: 0 },
+      { id: "u1", label: "Ada Lovelace", start: 20 },
+    ]);
+  });
+
+  it("records mentions sorted by document order", () => {
+    const value: MentionValue = {
+      text: "@Grace Hopper @ad",
+      mentions: [{ id: "u2", label: "Grace Hopper", start: 0 }],
+    };
+    const result = insertMention(value, ada, "@", 14, 17);
+    expect(result.value.mentions.map((m) => m.id)).toEqual(["u2", "u1"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mentionAt / mentionEnd — the basis for chip atomicity
+// ---------------------------------------------------------------------------
+
+describe("mentionAt / mentionEnd", () => {
+  it("mentionEnd covers trigger + label", () => {
+    expect(mentionEnd(oneMention.mentions[0]!, "@")).toBe(16);
+  });
+
+  it("finds the mention containing an index inside its range", () => {
+    expect(mentionAt(oneMention, 3)?.id).toBe("u1");
+    expect(mentionAt(oneMention, 10)?.id).toBe("u1");
+    expect(mentionAt(oneMention, 15)?.id).toBe("u1");
+  });
+
+  it("treats the range as half-open — the end offset is OUTSIDE", () => {
+    expect(mentionAt(oneMention, 16)).toBeUndefined();
+    expect(mentionAt(oneMention, 2)).toBeUndefined();
+  });
+
+  it("returns undefined for a mention-free value", () => {
+    expect(mentionAt({ text: "nothing here", mentions: [] }, 4)).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultMentionFilter
+// ---------------------------------------------------------------------------
+
+describe("defaultMentionFilter", () => {
+  it("matches everything on an empty query", () => {
+    expect(defaultMentionFilter(ada, "")).toBe(true);
+    expect(defaultMentionFilter(grace, "")).toBe(true);
+  });
+
+  it("matches the label case-insensitively, as a substring", () => {
+    expect(defaultMentionFilter(ada, "love")).toBe(true);
+    expect(defaultMentionFilter(ada, "ADA")).toBe(true);
+    expect(defaultMentionFilter(ada, "zz")).toBe(false);
+  });
+
+  it("matches extra keywords", () => {
+    expect(defaultMentionFilter(ada, "math")).toBe(true);
+    expect(defaultMentionFilter(grace, "math")).toBe(false);
+  });
+});

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

@@ -0,0 +1,193 @@
+import type { ReactNode } from "react";
+
+/**
+ * The pure offset algebra behind `MentionInput`.
+ *
+ * Chip atomicity in a real `<textarea>` is **selection arithmetic over a token
+ * map**, not DOM nodes: the field holds ordinary text, and this module keeps a
+ * parallel list of `{ id, label, start }` records honest as that text is edited,
+ * pasted over and deleted. Nothing here touches React or the DOM, so every
+ * acceptance criterion about backspace atomicity, caret skipping and the
+ * `{ text, mentionedIds }` payload reduces to a unit test on these functions.
+ */
+
+/** One selectable roster entry. */
+export interface MentionOption {
+  /** Stable id — this is what `serializeMentions` emits. */
+  id: string;
+  /** Inserted verbatim after the trigger character. */
+  label: string;
+  /** Optional secondary line shown under the label. */
+  description?: string;
+  /** Optional leading glyph (avatar, icon). */
+  icon?: ReactNode;
+  /** Extra match terms, so "ada" can find "Ada Lovelace". */
+  keywords?: string[];
+  /** Rendered but not selectable. */
+  disabled?: boolean;
+}
+
+/** A resolved mention inside `MentionValue.text`. */
+export interface Mention {
+  /** The option id this run refers to. */
+  id: string;
+  /** The label WITHOUT the trigger character. */
+  label: string;
+  /** Offset of the trigger character in `text`. */
+  start: number;
+}
+
+/** The component's value: plain text plus the mentions it contains. */
+export interface MentionValue {
+  text: string;
+  mentions: Mention[];
+}
+
+/** The result of inserting an option: the new value and where the caret goes. */
+export interface InsertMentionResult {
+  value: MentionValue;
+  /** Offset immediately after the inserted token's trailing space. */
+  caret: number;
+}
+
+/** Exclusive end offset of a mention's `trigger + label` run. */
+export function mentionEnd(mention: Mention, trigger = "@"): number {
+  return mention.start + trigger.length + mention.label.length;
+}
+
+/**
+ * The mention whose half-open range `[start, end)` contains `index`, if any.
+ *
+ * Half-open on purpose: the offset one past the token is *outside* it, so a
+ * caret sitting immediately after `@Ada Lovelace` is "next to" the mention
+ * rather than "in" it. Backspace therefore asks about `caret - 1` and Delete
+ * about `caret`, and both get an unambiguous answer.
+ */
+export function mentionAt(value: MentionValue, index: number, trigger = "@"): Mention | undefined {
+  return value.mentions.find((m) => index >= m.start && index < mentionEnd(m, trigger));
+}
+
+/** Length of the longest common prefix of two strings. */
+function commonPrefixLength(a: string, b: string): number {
+  const max = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < max && a[i] === b[i]) i++;
+  return i;
+}
+
+/**
+ * Re-derive the mention list after the text changed underneath it.
+ *
+ * The edit is treated as ONE contiguous replacement — which is what a
+ * keystroke, a paste, a cut and a native undo all are. The common prefix and
+ * common suffix bracket it; a mention entirely before the edit keeps its
+ * offset, one entirely after it shifts by the length delta, and one the edit
+ * reaches into is **dropped** (its text no longer spells the person's name, so
+ * the id would be a lie).
+ *
+ * Every survivor is then **re-validated** against the new text: the run at its
+ * offset must still read exactly `trigger + label`. That second pass is what
+ * makes a multi-mention paste safe — the arithmetic alone can be fooled by a
+ * replacement whose prefix/suffix boundaries land ambiguously, but a run that
+ * no longer spells the token can never survive the check.
+ */
+export function remapMentions(prev: MentionValue, nextText: string, trigger = "@"): Mention[] {
+  if (prev.text === nextText) return prev.mentions;
+
+  const prevText = prev.text;
+  const p = commonPrefixLength(prevText, nextText);
+
+  const maxSuffix = Math.min(prevText.length, nextText.length) - p;
+  let s = 0;
+  while (s < maxSuffix && prevText[prevText.length - 1 - s] === nextText[nextText.length - 1 - s]) {
+    s++;
+  }
+
+  /** End of the replaced span, in PREVIOUS coordinates. */
+  const editEnd = prevText.length - s;
+  const delta = nextText.length - prevText.length;
+
+  const remapped: Mention[] = [];
+  for (const mention of prev.mentions) {
+    const end = mentionEnd(mention, trigger);
+    if (end <= p) {
+      remapped.push(mention);
+    } else if (mention.start >= editEnd) {
+      remapped.push({ ...mention, start: mention.start + delta });
+    }
+    // else: the edit reached into the token — drop it.
+  }
+
+  return remapped.filter(
+    (m) => nextText.slice(m.start, mentionEnd(m, trigger)) === trigger + m.label,
+  );
+}
+
+/**
+ * Replace the in-progress `trigger + query` run with `trigger + label + " "`.
+ *
+ * `queryStart` is the offset of the trigger character; `caret` is where the
+ * query ends. The trailing space is deliberate: it terminates the query so the
+ * popup closes, and it gives the next word somewhere to start.
+ */
+export function insertMention(
+  value: MentionValue,
+  option: MentionOption,
+  trigger: string,
+  queryStart: number,
+  caret: number,
+): InsertMentionResult {
+  const inserted = `${trigger}${option.label} `;
+  const nextText = value.text.slice(0, queryStart) + inserted + value.text.slice(caret);
+  const delta = inserted.length - (caret - queryStart);
+
+  const mentions: Mention[] = [];
+  for (const mention of value.mentions) {
+    if (mentionEnd(mention, trigger) <= queryStart) {
+      mentions.push(mention);
+    } else if (mention.start >= caret) {
+      mentions.push({ ...mention, start: mention.start + delta });
+    }
+    // else: it overlapped the query run being replaced — drop it.
+  }
+  mentions.push({ id: option.id, label: option.label, start: queryStart });
+  mentions.sort((a, b) => a.start - b.start);
+
+  return {
+    value: {
+      text: nextText,
+      mentions: mentions.filter(
+        (m) => nextText.slice(m.start, mentionEnd(m, trigger)) === trigger + m.label,
+      ),
+    },
+    caret: queryStart + inserted.length,
+  };
+}
+
+/**
+ * The serialization contract a consumer gets out: the raw text plus the option
+ * ids it references, **deduped** and in **document order** (two mentions of the
+ * same person yield one id).
+ */
+export function serializeMentions(value: MentionValue): { text: string; mentionedIds: string[] } {
+  const ordered = [...value.mentions].sort((a, b) => a.start - b.start);
+  const mentionedIds: string[] = [];
+  const seen = new Set<string>();
+  for (const mention of ordered) {
+    if (seen.has(mention.id)) continue;
+    seen.add(mention.id);
+    mentionedIds.push(mention.id);
+  }
+  return { text: value.text, mentionedIds };
+}
+
+/**
+ * Case-insensitive substring match over `label` and `keywords`. An empty query
+ * matches everything, so the full roster shows the moment the trigger is typed.
+ */
+export function defaultMentionFilter(option: MentionOption, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (q.length === 0) return true;
+  if (option.label.toLowerCase().includes(q)) return true;
+  return (option.keywords ?? []).some((k) => k.toLowerCase().includes(q));
+}

package/src/components/menubar/index.ts

@@ -0,0 +1,17 @@
+export {
+  Menubar,
+  MenubarMenu,
+  MenubarGroup,
+  MenubarPortal,
+  MenubarSub,
+  MenubarRadioGroup,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarItem,
+  MenubarSubTrigger,
+  MenubarSubContent,
+  MenubarCheckboxItem,
+  MenubarRadioItem,
+  MenubarSeparator,
+  MenubarShortcut,
+} from "./menubar";

package/src/components/menubar/menubar.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarSeparator,
+  MenubarShortcut,
+  MenubarTrigger,
+} from "./menubar";
+const meta = {
+  title: "Navigation/Menubar",
+  component: Menubar,
+  tags: ["autodocs"],
+  argTypes: {
+    loop: {
+      description: "Whether keyboard navigation wraps from the last menu back to the first.",
+      control: "boolean",
+      table: { category: "Behaviour" },
+    },
+    dir: {
+      description: "Reading direction for the menubar.",
+      control: { type: "select" },
+      options: ["ltr", "rtl"],
+      table: { category: "Behaviour" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the menubar root.",
+      control: "text",
+      table: { category: "Styling" },
+    },
+  },
+} satisfies Meta<typeof Menubar>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <Menubar>
+      <MenubarMenu>
+        <MenubarTrigger>File</MenubarTrigger>
+        <MenubarContent>
+          <MenubarItem>
+            New <MenubarShortcut>⌘N</MenubarShortcut>
+          </MenubarItem>
+          <MenubarItem>Open</MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem>Quit</MenubarItem>
+        </MenubarContent>
+      </MenubarMenu>
+    </Menubar>
+  ),
+  // Clicks the "File" trigger to open the portalled menubar content and
+  // confirms the menu items are visible, then presses Escape to close it.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    await userEvent.click(canvas.getByRole("menuitem", { name: /file/i }));
+    const body = within(canvasElement.ownerDocument.body);
+    const menu = await body.findByRole("menu");
+    await waitFor(() =>
+      expect(within(menu).getByRole("menuitem", { name: /open/i })).toBeVisible(),
+    );
+    await waitFor(() =>
+      expect(within(menu).getByRole("menuitem", { name: /quit/i })).toBeVisible(),
+    );
+    await userEvent.keyboard("{Escape}");
+  },
+};