@runtypelabs/persona 4.8.0 → 4.9.0

package/src/utils/mention-trigger.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseMentionTrigger,
+  parseAnyTrigger,
+  isMenuOpeningInput,
+  stripMentionQuery,
+  MENTION_PLACEHOLDER,
+} from "./mention-trigger";
+
+describe("parseMentionTrigger", () => {
+  it("activates on @ at the start of input", () => {
+    const m = parseMentionTrigger("@App", 4);
+    expect(m).toEqual({ triggerIndex: 0, query: "App" });
+  });
+
+  it("activates on @ after whitespace mid-sentence", () => {
+    const m = parseMentionTrigger("check @fo", 9);
+    expect(m).toEqual({ triggerIndex: 6, query: "fo" });
+  });
+
+  it("returns an empty query right after a bare @", () => {
+    const m = parseMentionTrigger("hi @", 4);
+    expect(m).toEqual({ triggerIndex: 3, query: "" });
+  });
+
+  it("does NOT activate for an email (@ glued to a word char)", () => {
+    expect(parseMentionTrigger("user@example.com", 16)).toBeNull();
+    expect(parseMentionTrigger("user@", 5)).toBeNull();
+  });
+
+  it("closes once a space follows the trigger", () => {
+    // caret after "fo bar" — whitespace between query and caret ends the mention
+    expect(parseMentionTrigger("@fo bar", 7)).toBeNull();
+  });
+
+  it("tracks the nearest active trigger when caret is mid-query", () => {
+    const m = parseMentionTrigger("a @one @two", 11);
+    expect(m).toEqual({ triggerIndex: 7, query: "two" });
+  });
+
+  it("returns null at caret 0 or out of range", () => {
+    expect(parseMentionTrigger("@x", 0)).toBeNull();
+    expect(parseMentionTrigger("@x", 99)).toBeNull();
+  });
+
+  it("honors a custom trigger character", () => {
+    expect(parseMentionTrigger("see #iss", 8, "#")).toEqual({
+      triggerIndex: 4,
+      query: "iss",
+    });
+    expect(parseMentionTrigger("see #iss", 8, "@")).toBeNull();
+  });
+
+  it("handles multi-byte characters in the query", () => {
+    const m = parseMentionTrigger("@café", 5);
+    expect(m).toEqual({ triggerIndex: 0, query: "café" });
+  });
+
+  it("exports MENTION_PLACEHOLDER as the U+FFFC object-replacement char", () => {
+    expect(MENTION_PLACEHOLDER).toBe("");
+  });
+
+  it("treats U+FFFC (inline mention token placeholder) as a query terminator", () => {
+    // In inline-mode logical text an existing token is a single `` char. A new
+    // `@query` must not scan back THROUGH that token: "@ab" with caret after "b"
+    // has no active trigger (the `` ends the backscan like whitespace/newline).
+    expect(parseMentionTrigger(`@a${MENTION_PLACEHOLDER}b`, 4)).toBeNull();
+    // A fresh `@` typed AFTER a token still activates (scan stops at ``, not the @).
+    expect(parseMentionTrigger(" @fo", 5)).toEqual({
+      triggerIndex: 2,
+      query: "fo",
+    });
+  });
+
+  describe("position gating (for / slash-commands)", () => {
+    it("line-start: activates at input start and after a newline", () => {
+      expect(parseMentionTrigger("/dep", 4, "/", "line-start")).toEqual({
+        triggerIndex: 0,
+        query: "dep",
+      });
+      expect(parseMentionTrigger("hi\n/dep", 7, "/", "line-start")).toEqual({
+        triggerIndex: 3,
+        query: "dep",
+      });
+    });
+
+    it("line-start: does NOT activate mid-line (after a space)", () => {
+      expect(parseMentionTrigger("hi /dep", 7, "/", "line-start")).toBeNull();
+    });
+
+    it("input-start: only at index 0", () => {
+      expect(parseMentionTrigger("/x", 2, "/", "input-start")).toEqual({
+        triggerIndex: 0,
+        query: "x",
+      });
+      expect(parseMentionTrigger("hi\n/x", 5, "/", "input-start")).toBeNull();
+    });
+  });
+});
+
+describe("parseAnyTrigger", () => {
+  const channels = [
+    { trigger: "@", position: "anywhere" as const },
+    { trigger: "/", position: "line-start" as const },
+  ];
+
+  it("picks the @ channel for a mid-sentence mention", () => {
+    const hit = parseAnyTrigger("hey @fo", 7, channels);
+    expect(hit?.channel.trigger).toBe("@");
+    expect(hit?.match).toEqual({ triggerIndex: 4, query: "fo" });
+  });
+
+  it("picks the / channel only at line-start", () => {
+    const hit = parseAnyTrigger("/dep", 4, channels);
+    expect(hit?.channel.trigger).toBe("/");
+    expect(hit?.match).toEqual({ triggerIndex: 0, query: "dep" });
+  });
+
+  it("does not match / mid-line even though @ is anywhere", () => {
+    expect(parseAnyTrigger("hi /dep", 7, channels)).toBeNull();
+  });
+
+  it("returns null when no channel is active", () => {
+    expect(parseAnyTrigger("plain text", 10, channels)).toBeNull();
+  });
+});
+
+describe("isMenuOpeningInput", () => {
+  it("opens on typed text and unknown input types", () => {
+    expect(isMenuOpeningInput("insertText")).toBe(true);
+    expect(isMenuOpeningInput(undefined)).toBe(true);
+  });
+
+  it("does not open on paste or drop", () => {
+    expect(isMenuOpeningInput("insertFromPaste")).toBe(false);
+    expect(isMenuOpeningInput("insertFromDrop")).toBe(false);
+  });
+});
+
+describe("stripMentionQuery", () => {
+  it("removes the @query span and moves the caret to the trigger", () => {
+    const value = "check @App for bugs";
+    const match = parseMentionTrigger("check @App", 10)!;
+    // caret sits right after "@App" (index 10)
+    const out = stripMentionQuery(value, match, 10);
+    expect(out.value).toBe("check  for bugs");
+    expect(out.caret).toBe(6);
+  });
+
+  it("strips a bare trigger with empty query", () => {
+    const out = stripMentionQuery("hi @", { triggerIndex: 3, query: "" }, 4);
+    expect(out.value).toBe("hi ");
+    expect(out.caret).toBe(3);
+  });
+});

package/src/utils/mention-trigger.ts

@@ -0,0 +1,156 @@
+/**
+ * Pure `@`-trigger detection for the composer mention menu.
+ *
+ * No DOM, no contenteditable — a small function over `(value, caret)` mirroring
+ * the Slack/Discord approach. Shared by the core orchestrator's lightweight
+ * "should I open?" pre-check and the lazy-loaded controller's full parse, so the
+ * trigger rule lives in exactly one place.
+ */
+
+export type MentionTriggerMatch = {
+  /** Index of the trigger character in `value`. */
+  triggerIndex: number;
+  /** The text typed after the trigger, up to the caret (no leading trigger). */
+  query: string;
+};
+
+/**
+ * Where a trigger may open. `"anywhere"` is the `@` rule (after any whitespace/
+ * start); `"line-start"` and `"input-start"` are the natural rules for `/`
+ * slash-commands. Kept as a local string union so the parser stays free of the
+ * public config types.
+ */
+export type MentionTriggerPosition = "anywhere" | "line-start" | "input-start";
+
+/** One trigger channel for `parseAnyTrigger` — a char plus its position rule. */
+export type MentionTriggerSpec = {
+  trigger: string;
+  position?: MentionTriggerPosition;
+  /**
+   * Allow the query to span spaces/tabs (a newline still ends it). Needed for
+   * slash-command ARGS (`/deploy staging` → query `"deploy staging"`); leave
+   * false for single-token `@` mentions (a space ends the mention).
+   */
+  allowSpaces?: boolean;
+};
+
+const WHITESPACE = /\s/;
+
+/**
+ * OBJECT REPLACEMENT CHAR (U+FFFC) — one inline mention token in the composer's
+ * *logical* text (see `toLogicalText` in composer-document.ts). Defined HERE, in
+ * the dependency-free trigger module, and re-exported from composer-document.ts so
+ * the constant has a single source without dragging the document-model runtime
+ * into the chip chunk (which imports this module but not composer-document).
+ */
+export const MENTION_PLACEHOLDER = "";
+
+/** Does `triggerIndex` satisfy the channel's position rule? */
+function positionAllowed(
+  value: string,
+  triggerIndex: number,
+  position: MentionTriggerPosition
+): boolean {
+  if (position === "input-start") return triggerIndex === 0;
+  const before = triggerIndex > 0 ? value[triggerIndex - 1] : "";
+  if (position === "line-start") return before === "" || before === "\n";
+  // "anywhere": preceded by whitespace or start (also excludes `user@example.com`).
+  return before === "" || WHITESPACE.test(before);
+}
+
+/**
+ * Detect an active mention trigger ending at `caret`.
+ *
+ * Active when, scanning back from the caret, a trigger char is reached with no
+ * intervening whitespace AND the trigger satisfies `position`. Returns `null`
+ * otherwise — notably for `user@example.com` (trigger glued to a word char) and
+ * once a space follows the trigger.
+ *
+ * @param value       Full textarea value.
+ * @param caret       Caret offset (selectionStart). Out-of-range → `null`.
+ * @param trigger     Single trigger character. @default "@"
+ * @param position    Where the trigger may open. @default "anywhere"
+ * @param allowSpaces Let the query span spaces/tabs (for command args). @default false
+ */
+export function parseMentionTrigger(
+  value: string,
+  caret: number,
+  trigger = "@",
+  position: MentionTriggerPosition = "anywhere",
+  allowSpaces = false
+): MentionTriggerMatch | null {
+  if (!trigger) return null;
+  if (caret <= 0 || caret > value.length) return null;
+
+  let i = caret - 1;
+  while (i >= 0) {
+    const ch = value[i];
+    if (ch === trigger) {
+      if (positionAllowed(value, i, position)) {
+        return { triggerIndex: i, query: value.slice(i + 1, caret) };
+      }
+      // Trigger present but disallowed here (glued word char / not line-start).
+      return null;
+    }
+    // A newline always ends the query. Spaces/tabs end it too, unless the
+    // channel allows multi-word queries (slash-command args).
+    if (ch === "\n") return null;
+    // The mention-token placeholder always terminates the backscan so a query
+    // never spans an existing token (`@a<token>b` must not report a query through
+    // the token). Never appears in a plain textarea value, so chip mode is
+    // unaffected.
+    if (ch === MENTION_PLACEHOLDER) return null;
+    if (!allowSpaces && WHITESPACE.test(ch)) return null;
+    i--;
+  }
+  return null;
+}
+
+/**
+ * Resolve which of several trigger channels is active at `caret`. Channels are
+ * tested in order; the FIRST with an active match wins (put `@` first, `/`
+ * next). At any caret at most one channel can match — the scan stops at the
+ * nearest trigger/whitespace — so ordering only matters if two channels share a
+ * trigger char (don't do that). Returns the winning channel + its match.
+ */
+export function parseAnyTrigger<T extends MentionTriggerSpec>(
+  value: string,
+  caret: number,
+  channels: readonly T[]
+): { channel: T; match: MentionTriggerMatch } | null {
+  for (const channel of channels) {
+    const match = parseMentionTrigger(
+      value,
+      caret,
+      channel.trigger,
+      channel.position ?? "anywhere",
+      channel.allowSpaces ?? false
+    );
+    if (match) return { channel, match };
+  }
+  return null;
+}
+
+/**
+ * Whether a given `inputType` (from an `InputEvent`) is one that may OPEN the
+ * menu. Paste never opens it (`insertFromPaste`); only real typing does. The
+ * caller separately guards `event.isComposing` for IME safety.
+ */
+export function isMenuOpeningInput(inputType: string | undefined): boolean {
+  if (!inputType) return true; // older browsers omit inputType; treat as typing
+  return inputType !== "insertFromPaste" && inputType !== "insertFromDrop";
+}
+
+/**
+ * Remove the `@query` span (trigger char through the caret) from `value`,
+ * returning the new value + the caret position after removal. Used on select to
+ * strip the typed query while leaving the rest of the prose intact.
+ */
+export function stripMentionQuery(
+  value: string,
+  match: MentionTriggerMatch,
+  caret: number
+): { value: string; caret: number } {
+  const next = value.slice(0, match.triggerIndex) + value.slice(caret);
+  return { value: next, caret: match.triggerIndex };
+}

package/src/utils/theme.test.ts

@@ -169,6 +169,31 @@ describe('theme utils', () => {
     expect(customVars['--persona-header-action-icon-fg']).toBe('#9ca3af');
   });
 
+  it('maps button.ghost tokens to the composer ghost icon-button CSS variables', () => {
+    const cssVars = themeToCssVariables(createTheme());
+
+    // The composer's transparent icon buttons (.persona-mention-button /
+    // .persona-attachment-button) read these instead of hardcoded inline styles.
+    expect(cssVars['--persona-button-ghost-bg']).toBe('transparent');
+    expect(cssVars['--persona-button-ghost-fg']).toBe('#111827'); // semantic.text → gray.900
+    expect(cssVars['--persona-button-ghost-radius']).toBe('0.375rem'); // radius.md
+    expect(cssVars['--persona-button-ghost-hover-bg']).toBe('rgba(0, 0, 0, 0.05)');
+
+    const custom = createTheme({
+      components: {
+        button: {
+          ghost: {
+            foreground: 'palette.colors.accent.500',
+            hoverBackground: 'palette.colors.gray.100',
+          },
+        },
+      },
+    } as any);
+    const customVars = themeToCssVariables(custom);
+    expect(customVars['--persona-button-ghost-fg']).toBe('#06b6d4'); // accent.500
+    expect(customVars['--persona-button-ghost-hover-bg']).toBe('#f3f4f6'); // gray.100
+  });
+
   it('defaults artifact pane fill from semantic container and resolves toolbar background token refs', () => {
     const theme = createTheme();
     const cssVars = themeToCssVariables(theme);
@@ -312,12 +337,11 @@ describe('theme utils', () => {
     );
   });
 
-  it('falls back to the legacy intro-card shadow when no token is set', () => {
+  it('defaults the intro card to flat (transparent, no shadow) when no token is set', () => {
     const theme = createTheme({});
     const cssVars = themeToCssVariables(theme);
-    expect(cssVars['--persona-intro-card-shadow']).toBe(
-      '0 5px 15px rgba(15, 23, 42, 0.08)'
-    );
+    expect(cssVars['--persona-intro-card-shadow']).toBe('none');
+    expect(cssVars['--persona-intro-card-bg']).toBe('transparent');
   });
 
   it('drives --persona-tool-bubble-shadow from the theme token (config.toolCall.shadow is applied inline on the bubble, not the root var)', () => {

package/src/utils/tokens.ts

@@ -263,6 +263,9 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       foreground: 'semantic.colors.text',
       borderRadius: 'palette.radius.md',
       padding: 'semantic.spacing.sm',
+      // Subtle neutral tint on hover — the composer's transparent icon buttons
+      // (attachment, mention) read this via `--persona-button-ghost-hover-bg`.
+      hoverBackground: 'rgba(0, 0, 0, 0.05)',
     },
   },
   input: {
@@ -326,12 +329,12 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     border: 'semantic.colors.border',
   },
   introCard: {
-    // Defaults preserve the legacy `persona-shadow-sm` look exactly so existing
-    // pages render unchanged when no token is set.
-    background: 'semantic.colors.surface',
+    // Flat by default: the greeting reads as plain text on the transcript
+    // background (the industry norm), not an elevated card.
+    background: 'transparent',
     borderRadius: 'palette.radius.2xl',
     padding: 'semantic.spacing.lg',
-    shadow: '0 5px 15px rgba(15, 23, 42, 0.08)',
+    shadow: 'palette.shadows.none',
   },
   toolBubble: {
     shadow: 'palette.shadows.sm',
@@ -739,6 +742,21 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-button-primary-borderRadius'] ??
     cssVars['--persona-palette-radius-full'] ??
     '9999px';
+  // Ghost variant: transparent, neutral-foreground icon buttons (the composer's
+  // attachment + mention affordances). Wired to `components.button.ghost.*`.
+  cssVars['--persona-button-ghost-bg'] =
+    cssVars['--persona-components-button-ghost-background'] ??
+    'transparent';
+  cssVars['--persona-button-ghost-fg'] =
+    cssVars['--persona-components-button-ghost-foreground'] ??
+    cssVars['--persona-text'];
+  cssVars['--persona-button-ghost-radius'] =
+    cssVars['--persona-components-button-ghost-borderRadius'] ??
+    cssVars['--persona-radius-md'] ??
+    '0.375rem';
+  cssVars['--persona-button-ghost-hover-bg'] =
+    cssVars['--persona-components-button-ghost-hoverBackground'] ??
+    'rgba(0, 0, 0, 0.05)';
   cssVars['--persona-panel-radius'] =
     cssVars['--persona-components-panel-borderRadius'] ??
     cssVars['--persona-radius-xl'] ??
@@ -791,19 +809,17 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   if (headerTokens?.borderBottom) cssVars['--persona-header-border-bottom'] = headerTokens.borderBottom;
 
   // Intro card aliases: short names the panel inline-styles read directly.
-  // The full-path `--persona-components-introCard-*` variables auto-emit above;
-  // these mirror them with sensible fallbacks so existing pages keep their look.
-  const introCardTokens = theme.components?.introCard;
+  // The full-path `--persona-components-introCard-*` variables auto-emit above.
+  // Default is flat (transparent, no shadow): the greeting renders as plain
+  // text on the transcript background; set introCard tokens for a card look.
   cssVars['--persona-intro-card-bg'] =
-    cssVars['--persona-components-introCard-background'] ?? cssVars['--persona-surface'];
+    cssVars['--persona-components-introCard-background'] ?? 'transparent';
   cssVars['--persona-intro-card-radius'] =
     cssVars['--persona-components-introCard-borderRadius'] ?? '1rem';
   cssVars['--persona-intro-card-padding'] =
     cssVars['--persona-components-introCard-padding'] ?? '1.5rem';
   cssVars['--persona-intro-card-shadow'] =
-    introCardTokens?.shadow
-      ?? cssVars['--persona-components-introCard-shadow']
-      ?? '0 5px 15px rgba(15, 23, 42, 0.08)';
+    cssVars['--persona-components-introCard-shadow'] ?? 'none';
 
   cssVars['--persona-input-background'] =
     cssVars['--persona-components-input-background'] ?? cssVars['--persona-surface'];