@gusnips/react 0.9.25 → 0.9.27

package/src/commands.test.ts

@@ -0,0 +1,245 @@
+// @vitest-environment node
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, expectTypeOf, it, vi } from "vitest";
+import {
+  completeCommand,
+  matchCommands,
+  parseCommand,
+  resolveCommand,
+  useSlashCommands,
+} from "./commands.ts";
+
+const help = {
+  name: "help",
+  description: "Show available commands",
+  aliases: ["assist", "GUIDE"],
+  tags: ["manual"],
+};
+const schedule = {
+  name: "schedule",
+  description: "Run a task later",
+  aliases: ["later", "book"],
+  tags: ["timer"],
+  takesArg: true,
+};
+const commands = [help, schedule];
+
+describe("parseCommand", () => {
+  it.each([
+    { text: "/", expected: { name: "" } },
+    { text: "/ ", expected: { name: "", arg: "" } },
+    { text: "/HELP", expected: { name: "help" } },
+    { text: "/help ", expected: { name: "help", arg: "" } },
+    { text: " \t/HeLp", expected: { name: "help" } },
+    {
+      text: "/SCHEDULE   Keep  these spaces\tand case  ",
+      expected: { name: "schedule", arg: "Keep  these spaces\tand case  " },
+    },
+  ])("parses a single line: $text", ({ text, expected }) => {
+    expect(parseCommand(text)).toEqual(expected);
+  });
+
+  it.each(["/tmp/file", "/help/topic", "//help"])(
+    "keeps a slash path as an unknown command token: %s",
+    (text) => {
+      const name = text.slice(1);
+      expect(parseCommand(text)).toEqual({ name });
+      expect(resolveCommand(commands, name)).toEqual({ kind: "unknown", name });
+    },
+  );
+
+  it.each(["", " \t", "help", "Please /help", "https://example.test/help", "Hello /help there"])(
+    "ignores non-command prose: %s",
+    (text) => {
+      expect(parseCommand(text)).toBeNull();
+    },
+  );
+
+  it.each(["\n", "\r", "\r\n", "\u{2028}", "\u{2029}"])(
+    "rejects a line terminator anywhere: %j",
+    (separator) => {
+      for (const text of [`${separator}/help`, `/help${separator}`, `/help ${separator}topic`]) {
+        expect(parseCommand(text)).toBeNull();
+      }
+    },
+  );
+});
+
+describe("resolveCommand", () => {
+  it("prefers an exact canonical name over an earlier alias", () => {
+    const alias = { ...schedule, aliases: ["help"] };
+    expect(resolveCommand([alias, help], "HELP")).toEqual({ kind: "matched", command: help });
+  });
+
+  it.each([
+    { token: "guide", command: help },
+    { token: "LATER", command: schedule },
+  ])("matches an alias without case sensitivity: $token", ({ token, command }) => {
+    expect(resolveCommand(commands, token)).toEqual({ kind: "matched", command });
+  });
+
+  it("reports aliases shared by different commands in registry order", () => {
+    const first = { ...schedule, aliases: ["shared", "SHARED"] };
+    const second = { ...help, aliases: ["shared"] };
+    expect(resolveCommand([first, second], "SHARED")).toEqual({
+      kind: "ambiguous",
+      name: "SHARED",
+      commands: [first, second],
+    });
+    expect(resolveCommand([first], "shared")).toEqual({ kind: "matched", command: first });
+  });
+
+  it("reports duplicate canonical names even when an alias also matches", () => {
+    const duplicate = { ...schedule, name: "HELP" };
+    const alias = { ...schedule, aliases: ["help"] };
+    expect(resolveCommand([help, alias, duplicate], "help")).toEqual({
+      kind: "ambiguous",
+      name: "help",
+      commands: [help, duplicate],
+    });
+  });
+
+  it.each(["manual", "timer", "Show available commands", "hel", "lat", "missing"])(
+    "does not execute a tag, description, prefix or unknown token: %s",
+    (name) => {
+      expect(resolveCommand(commands, name)).toEqual({ kind: "unknown", name });
+    },
+  );
+
+  it("never executes an empty token, even if the registry contains one", () => {
+    expect(resolveCommand([{ ...help, name: "", aliases: [""] }], "")).toEqual({
+      kind: "unknown",
+      name: "",
+    });
+  });
+});
+
+describe("matchCommands", () => {
+  it("ranks names, aliases, prefixes, tags and descriptions with stable ties", () => {
+    const registry = [
+      { name: "description", description: "Find a task", aliases: [], tags: [] },
+      { name: "tag", description: "", aliases: [], tags: ["finder"] },
+      { name: "shortcut", description: "", aliases: ["finder"], tags: [] },
+      { name: "finding", description: "", aliases: [], tags: [] },
+      { name: "alias", description: "", aliases: ["find"], tags: [] },
+      { name: "find", description: "", aliases: [], tags: [] },
+      { name: "second-tag", description: "", aliases: [], tags: ["find"] },
+      { name: "second-description", description: "Find another task", aliases: [], tags: [] },
+      { name: "unrelated", description: "", aliases: [], tags: [] },
+    ];
+    expect(matchCommands(registry, "find").map((command) => command.name)).toEqual([
+      "find",
+      "alias",
+      "finding",
+      "shortcut",
+      "tag",
+      "second-tag",
+      "description",
+      "second-description",
+    ]);
+  });
+
+  const translated = [
+    {
+      name: "ação",
+      description: "A próxima revisão",
+      aliases: ["café"],
+      tags: ["rápido"],
+    },
+    {
+      name: "mañana",
+      description: "Resumen de la reunión",
+      aliases: ["después"],
+      tags: ["configuración"],
+    },
+  ];
+  it.each([
+    { query: " ACAO ", name: "ação" },
+    { query: "ac\u{0327}a\u{0303}o", name: "ação" },
+    { query: "CAFE", name: "ação" },
+    { query: "RAPIDO", name: "ação" },
+    { query: "PROXIMA REVISAO", name: "ação" },
+    { query: "MANANA", name: "mañana" },
+    { query: "DESPUES", name: "mañana" },
+    { query: "CONFIGURACION", name: "mañana" },
+    { query: "REUNION", name: "mañana" },
+  ])("matches case and accents across search fields: $query", ({ query, name }) => {
+    expect(matchCommands(translated, query).map((command) => command.name)).toEqual([name]);
+  });
+
+  it("returns only the first descriptor for each canonical name", () => {
+    const duplicate = { ...help, name: "HELP" };
+    const registry = [help, schedule, duplicate];
+    expect(matchCommands(registry, "help")).toEqual([help]);
+    expect(matchCommands(registry, "")).toEqual(commands);
+  });
+
+  it("does not turn repeated or shared aliases into duplicate rows", () => {
+    const first = { ...help, aliases: ["shared", "shared", "SHARED"] };
+    const second = { ...schedule, aliases: ["shared"] };
+    expect(matchCommands([first, second], "shared")).toEqual([first, second]);
+  });
+
+  it("returns original descriptors and preserves their extra fields in the type", () => {
+    const custom = { ...help, execute: () => "done" };
+    const [matched] = matchCommands([custom], "assist");
+    expectTypeOf(matched).toEqualTypeOf<typeof custom | undefined>();
+    expect(matched).toBe(custom);
+    expect(matched?.execute()).toBe("done");
+  });
+
+  it.each(["", " \t "])("keeps registry order for an empty query: %j", (query) => {
+    expect(matchCommands([schedule, help], query)).toEqual([schedule, help]);
+  });
+
+  it("returns no rows for an unrelated query", () => {
+    expect(matchCommands(commands, "missing")).toEqual([]);
+  });
+});
+
+describe("completeCommand", () => {
+  it.each([
+    ["/later", "/schedule "],
+    ["/sche", "/schedule "],
+    ["/SCHEDULE", "/schedule "],
+    ["/", "/schedule "],
+    ["/later ", "/schedule "],
+    [" \t/later Keep  these spaces\tand case  ", "/schedule Keep  these spaces\tand case  "],
+  ])("canonicalizes an argument-taking command: %s", (text, expected) => {
+    expect(completeCommand(schedule, text)).toBe(expected);
+  });
+
+  it.each([
+    ["/assi", "/help"],
+    ["/GUIDE", "/help"],
+    ["/", "/help"],
+    ["/assist topic  with spaces  ", "/help topic  with spaces  "],
+  ])("canonicalizes a plain command without dropping its arguments: %s", (text, expected) => {
+    expect(completeCommand(help, text)).toBe(expected);
+  });
+});
+
+describe("useSlashCommands on the server", () => {
+  it("imports and renders in Node without browser globals or running callbacks", () => {
+    expect(typeof window).toBe("undefined");
+    expect(typeof document).toBe("undefined");
+    const onChange = vi.fn();
+    const onExecute = vi.fn();
+    const onError = vi.fn();
+
+    function Menu() {
+      const menu = useSlashCommands({ text: "/he", commands, onChange, onExecute, onError });
+      return createElement(
+        "output",
+        { id: menu.listId },
+        `${menu.open}/${menu.active?.name}/${menu.items.length}`,
+      );
+    }
+
+    expect(renderToString(createElement(Menu))).toContain("true/help/1");
+    expect(onChange).not.toHaveBeenCalled();
+    expect(onExecute).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+  });
+});

package/src/commands.ts

@@ -0,0 +1,268 @@
+import { useId, useState } from "react";
+
+export interface SlashCommand {
+  /** One token, without the leading slash. */
+  name: string;
+  description: string;
+  /** Other executable names. Tags only help search. */
+  aliases: readonly string[];
+  tags: readonly string[];
+  takesArg?: boolean;
+}
+
+export interface ParsedCommand {
+  name: string;
+  /** Undefined before a space; empty after a space with no argument yet. */
+  arg?: string;
+}
+
+/** Multiline text and a slash inside a message are not commands. */
+export function parseCommand(text: string): ParsedCommand | null {
+  if (/[\r\n\u{2028}\u{2029}]/u.test(text)) return null;
+  const match = /^\s*\/(\S*)(?:[^\S\r\n]+(.*))?$/u.exec(text);
+  if (!match) return null;
+  const name = (match[1] ?? "").toLowerCase();
+  return match[2] === undefined ? { name } : { name, arg: match[2] };
+}
+
+export type CommandResolution<T extends SlashCommand = SlashCommand> =
+  | { kind: "matched"; command: T }
+  | { kind: "unknown"; name: string }
+  | { kind: "ambiguous"; name: string; commands: readonly T[] };
+
+/** Exact names win over aliases. Search tags never execute an action. */
+export function resolveCommand<T extends SlashCommand>(
+  commands: readonly T[],
+  name: string,
+): CommandResolution<T> {
+  const token = name.toLowerCase();
+  if (!token) return { kind: "unknown", name };
+  let matches = commands.filter((command) => command.name.toLowerCase() === token);
+  if (matches.length === 0) {
+    matches = commands.filter((command) =>
+      command.aliases.some((alias) => alias.toLowerCase() === token),
+    );
+  }
+  if (matches.length > 1) return { kind: "ambiguous", name, commands: matches };
+  const command = matches[0];
+  return command ? { kind: "matched", command } : { kind: "unknown", name };
+}
+
+function searchText(text: string): string {
+  return text.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+}
+
+function rank(command: SlashCommand, query: string): number {
+  if (!query) return 0;
+  const name = searchText(command.name);
+  const aliases = command.aliases.map(searchText);
+  if (name === query) return 0;
+  if (aliases.includes(query)) return 1;
+  if (name.startsWith(query)) return 2;
+  if (aliases.some((alias) => alias.startsWith(query))) return 3;
+  if (command.tags.some((tag) => searchText(tag).includes(query))) return 4;
+  if (searchText(command.description).includes(query)) return 5;
+  return Infinity;
+}
+
+/** One row per name, in registry order when two results have the same rank. */
+export function matchCommands<T extends SlashCommand>(commands: readonly T[], query: string): T[] {
+  const token = searchText(query.trim());
+  const names = new Set<string>();
+  return commands
+    .filter((command) => {
+      const name = command.name.toLowerCase();
+      if (names.has(name)) return false;
+      names.add(name);
+      return true;
+    })
+    .map((command) => ({ command, rank: rank(command, token) }))
+    .filter((match) => Number.isFinite(match.rank))
+    .sort((a, b) => a.rank - b.rank)
+    .map((match) => match.command);
+}
+
+/** Replace only the name, keeping the argument already typed. */
+export function completeCommand(command: SlashCommand, text: string): string {
+  const arg = parseCommand(text)?.arg;
+  if (arg !== undefined) return `/${command.name} ${arg}`;
+  return `/${command.name}${command.takesArg ? " " : ""}`;
+}
+
+export type CommandProblem<T extends SlashCommand = SlashCommand> = Exclude<
+  CommandResolution<T>,
+  { kind: "matched" }
+>;
+
+export interface CommandOptions<T extends SlashCommand> {
+  text: string;
+  /** Supply only commands allowed here, with current translated descriptions and tags. */
+  commands: readonly T[];
+  onChange: (text: string) => void;
+  /** The app owns authorization, errors, draft cleanup and attachments. */
+  onExecute: (command: T, arg: string | undefined, altKey: boolean) => void;
+  /** Required: show a way back to the available commands, never send this text to the model. */
+  onError: (problem: CommandProblem<T>) => void;
+}
+
+/** Structural so React events and small test events both fit. */
+export interface CommandKeyEvent {
+  key: string;
+  shiftKey?: boolean;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  isComposing?: boolean;
+  keyCode?: number;
+  nativeEvent?: { isComposing?: boolean; keyCode?: number };
+  preventDefault: () => void;
+}
+
+export interface SlashCommandMenu<T extends SlashCommand = SlashCommand> {
+  parsed: ParsedCommand | null;
+  open: boolean;
+  items: readonly T[];
+  index: number;
+  active: T | undefined;
+  listId: string;
+  itemId: (command: T) => string;
+  activeId: string | undefined;
+  highlight: (index: number) => void;
+  close: () => void;
+  showAll: () => void;
+  pick: (command: T, altKey?: boolean) => void;
+  submit: (altKey?: boolean) => boolean;
+  handleKeyDown: (event: CommandKeyEvent) => boolean;
+}
+
+/** A controlled textarea menu. No UI, browser globals, timers or attachment state. */
+export function useSlashCommands<T extends SlashCommand>({
+  text,
+  commands,
+  onChange,
+  onExecute,
+  onError,
+}: CommandOptions<T>): SlashCommandMenu<T> {
+  const parsed = parseCommand(text);
+  const resolution = parsed ? resolveCommand(commands, parsed.name) : null;
+  const editingName =
+    parsed !== null && (parsed.arg === undefined || resolution?.kind !== "matched");
+  const items = editingName ? matchCommands(commands, parsed.name) : [];
+  const key = JSON.stringify([text, items.map((command) => command.name)]);
+  const [state, setState] = useState({ key, text, index: 0, deliberate: false, dismissed: false });
+  // Reset selection on a changed result set, but keep Escape's dismissal until the draft changes.
+  if (state.key !== key) {
+    setState({
+      key,
+      text,
+      index: 0,
+      deliberate: false,
+      dismissed: state.text === text && state.dismissed,
+    });
+  }
+
+  const listId = `${useId()}-commands`;
+  const open = editingName && !state.dismissed;
+  const active = open ? items[state.index] : undefined;
+  const itemId = (command: T) => `${listId}-${encodeURIComponent(command.name)}`;
+
+  function close(): void {
+    setState((current) => ({ ...current, dismissed: true }));
+  }
+
+  function showAll(): void {
+    setState((current) => ({ ...current, index: 0, deliberate: false, dismissed: false }));
+    onChange("/");
+  }
+
+  function highlight(index: number): void {
+    if (!items[index]) return;
+    setState((current) => ({ ...current, index, deliberate: true }));
+  }
+
+  function pick(command: T, altKey = false): void {
+    // Re-resolve against current capabilities, not a descriptor retained by a caller.
+    const selected = resolveCommand(commands, command.name);
+    if (selected.kind !== "matched") {
+      onError(selected);
+      return;
+    }
+    if (selected.command.takesArg || parsed?.arg) {
+      onChange(completeCommand(selected.command, text));
+      return;
+    }
+    onExecute(selected.command, parsed?.arg, altKey);
+  }
+
+  /** Call before the normal send/queue/quota path, including button and imperative submits. */
+  function submit(altKey = false): boolean {
+    if (!parsed || !resolution) return false;
+    if (resolution.kind !== "matched") {
+      onError(resolution);
+      return true;
+    }
+    if (
+      resolution.command.takesArg &&
+      parsed.arg === undefined &&
+      parsed.name !== resolution.command.name.toLowerCase()
+    ) {
+      onChange(completeCommand(resolution.command, text));
+      return true;
+    }
+    onExecute(resolution.command, parsed.arg, altKey);
+    return true;
+  }
+
+  /** Call first. True means skip your own key handler; IME still gets the browser's default. */
+  function handleKeyDown(event: CommandKeyEvent): boolean {
+    const native = event.nativeEvent ?? event;
+    if (native.isComposing || native.keyCode === 229) return true;
+    if (event.shiftKey) return false;
+    if (open && event.key === "Escape") {
+      event.preventDefault();
+      close();
+      return true;
+    }
+    if (open && items.length > 0 && !event.ctrlKey && !event.metaKey) {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault();
+        const step = event.key === "ArrowDown" ? 1 : -1;
+        highlight((state.index + step + items.length) % items.length);
+        return true;
+      }
+      if (active && (event.key === "Enter" || event.key === "Tab")) {
+        event.preventDefault();
+        if (event.key === "Tab") {
+          onChange(completeCommand(active, text));
+        } else if (resolution?.kind === "ambiguous" && !state.deliberate) {
+          onError(resolution);
+        } else {
+          pick(active, event.altKey);
+        }
+        return true;
+      }
+    }
+    if (parsed && event.key === "Enter") {
+      event.preventDefault();
+      return submit(event.altKey);
+    }
+    return false;
+  }
+
+  return {
+    parsed,
+    open,
+    items,
+    index: state.index,
+    active,
+    listId,
+    itemId,
+    activeId: active ? itemId(active) : undefined,
+    highlight,
+    close,
+    showAll,
+    pick,
+    submit,
+    handleKeyDown,
+  };
+}

package/src/held-pending.test.ts

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useHeldPending } from "./held-pending.ts";
+
+// A refresh that answers in 80 ms flipped `pending` on and off inside a frame, so the button never
+// visibly changed and the reader thought the press was ignored. The flag has to stay on for the
+// minimum once it turns on, and a slow request must not be made to wait any longer.
+
+vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+
+const roots = new Set<Root>();
+
+beforeEach(() => vi.useFakeTimers());
+
+afterEach(() => {
+  for (const root of roots) act(() => root.unmount());
+  roots.clear();
+  document.body.replaceChildren();
+  vi.useRealTimers();
+});
+
+function mount(initial: boolean, minMs?: number) {
+  const element = document.createElement("div");
+  document.body.append(element);
+  const root = createRoot(element);
+  roots.add(root);
+  const seen: boolean[] = [];
+
+  function Probe({ pending }: { pending: boolean }) {
+    const held = useHeldPending(pending, minMs);
+    seen.push(held);
+    return null;
+  }
+
+  const render = (pending: boolean) => act(() => root.render(createElement(Probe, { pending })));
+  render(initial);
+  return { render, current: () => seen.at(-1) };
+}
+
+describe("useHeldPending", () => {
+  it("is false while nothing is pending", () => {
+    expect(mount(false).current()).toBe(false);
+  });
+
+  it("is true on the very render pending starts true, with no wait for an effect", () => {
+    const { render, current } = mount(false);
+    render(true);
+    expect(current()).toBe(true);
+  });
+
+  it("holds a request that ended early until the minimum has passed", () => {
+    const { render, current } = mount(false, 400);
+    render(true);
+    act(() => void vi.advanceTimersByTime(80));
+    render(false);
+    expect(current()).toBe(true);
+    act(() => void vi.advanceTimersByTime(319));
+    expect(current()).toBe(true);
+    act(() => void vi.advanceTimersByTime(1));
+    expect(current()).toBe(false);
+  });
+
+  it("does not make a slow request wait longer than one timer tick", () => {
+    const { render, current } = mount(false, 400);
+    render(true);
+    act(() => void vi.advanceTimersByTime(900));
+    render(false);
+    act(() => void vi.advanceTimersByTime(0));
+    expect(current()).toBe(false);
+  });
+
+  it("starts the clock again when it turns on a second time", () => {
+    const { render, current } = mount(false, 400);
+    render(true);
+    act(() => void vi.advanceTimersByTime(100));
+    render(false);
+    act(() => void vi.advanceTimersByTime(300));
+    expect(current()).toBe(false);
+    render(true);
+    act(() => void vi.advanceTimersByTime(50));
+    render(false);
+    expect(current()).toBe(true);
+    act(() => void vi.advanceTimersByTime(350));
+    expect(current()).toBe(false);
+  });
+});

package/src/held-pending.ts

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react";
+
+// A refresh that answers in 80 ms flips its `pending` flag on and off inside a frame or two. The
+// reader pressed the button, nothing on screen changed, and the page looks like it ignored them.
+// A louder spinner does not fix that, because the spinner is never painted. The flag itself has
+// to stay on long enough to be seen.
+
+/**
+ * `pending`, kept on for at least `minMs` once it turns on.
+ *
+ * It answers `true` on the very render `pending` turns true, with no wait for an effect, so the
+ * busy state shows on the press and not a frame later. A slow request is not made slower: the
+ * hold only fills the gap when the request ended early, and ends within one timer tick of it
+ * otherwise.
+ *
+ * 400 ms is the floor for a busy state a person can read as "it ran". Use it for a button's busy
+ * look, a refresh icon, a save that returns at once. Do not use it to gate real work: it changes
+ * what is shown, never what the request does.
+ */
+export function useHeldPending(pending: boolean, minMs = 400): boolean {
+  const [held, setHeld] = useState(false);
+  const startedAt = useRef(0);
+
+  // Raised while rendering, not in an effect, so there is no frame where `pending` is true and the
+  // hold is not. It only ever turns on here. The timer below is the one place it turns off.
+  if (pending && !held) setHeld(true);
+
+  useEffect(() => {
+    if (pending) {
+      startedAt.current = Date.now();
+      return;
+    }
+    const remaining = Math.max(0, startedAt.current + minMs - Date.now());
+    const timer = setTimeout(() => setHeld(false), remaining);
+    return () => clearTimeout(timer);
+  }, [pending, minMs]);
+
+  return pending || held;
+}

package/src/index.ts

@@ -32,6 +32,8 @@
 
 export { cn } from "./cn.ts";
 export { copyText, useCopy, type CopyOptions, type CopyState } from "./copy.ts";
+export { BusyRing } from "./busy-ring.tsx";
+export { useHeldPending } from "./held-pending.ts";
 export { returnPathFromLocation, safeInternalPath, type PathParts } from "./internal-path.ts";
 
 export { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.ts";