@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/src/ui-tailwind/chrome/tw-command-palette.tsx

@@ -0,0 +1,358 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+/**
+ * TwCommandPalette — Ctrl+K / Cmd+K overflow-relief valve for every
+ * editor command (designsystem §6.25, Lane 6b §6b.N1).
+ *
+ * Mounted once in the shell zone.  Host controls visibility via `open` +
+ * `onOpenChange` and supplies the command graph.  The component itself
+ * handles:
+ *
+ *   - Fuzzy substring / token / subsequence matching
+ *   - Keyboard navigation (ArrowUp / ArrowDown / Enter / Escape)
+ *   - Grouped result rendering with Lane 6a tokens
+ *   - Click-off-backdrop close
+ *   - auto-focus on the search input when opened
+ *
+ * Shortcut wiring (Ctrl+K) lives with the host — we do NOT subscribe to
+ * global keydown here to keep the component pure and testable.  See the
+ * exported `createCommandPaletteKeyBinding` helper for a ready-to-use
+ * listener that hosts can drop into their runtime-shortcut-dispatch path.
+ */
+
+export interface CommandPaletteItem {
+  /** Stable id used as React key and for onInvoke dispatch. */
+  id: string;
+  /** User-visible label. */
+  label: string;
+  /** Optional leading icon (Lucide or equivalent). */
+  icon?: ReactNode;
+  /** Optional keyboard shortcut hint rendered on the row. */
+  shortcut?: string;
+  /** Optional search synonyms — boosts match ranking. */
+  synonyms?: readonly string[];
+  /** Optional description rendered below the label. */
+  description?: string;
+  /** Disabled items still render but are dimmed and non-invokable. */
+  disabled?: boolean;
+  /** Invoked on Enter or click.  Caller is responsible for closing the palette. */
+  onInvoke: () => void;
+}
+
+export interface CommandPaletteGroup {
+  /** Stable id. */
+  id: string;
+  /** Section heading. */
+  label: string;
+  /** Items in this group, displayed in array order when no query. */
+  commands: readonly CommandPaletteItem[];
+}
+
+export interface TwCommandPaletteProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  groups: readonly CommandPaletteGroup[];
+  /** Placeholder text for the search input. */
+  placeholder?: string;
+  /** Empty-state message when no command matches the query. */
+  emptyMessage?: string;
+  /** className passthrough for the palette card. */
+  className?: string;
+}
+
+interface FlatItem extends CommandPaletteItem {
+  groupId: string;
+  groupLabel: string;
+}
+
+/**
+ * Fuzzy matcher — returns `true` if the needle matches the haystack as
+ * substring OR as a character subsequence.  Cheap, deterministic, and
+ * good enough for the ~100-item palette sizes we expect.
+ */
+function fuzzyMatch(needle: string, haystack: string): boolean {
+  if (needle.length === 0) return true;
+  const lowerNeedle = needle.toLowerCase();
+  const lowerHay = haystack.toLowerCase();
+  if (lowerHay.includes(lowerNeedle)) return true;
+  // Subsequence: each char of needle must appear in haystack in order.
+  let hi = 0;
+  for (const ch of lowerNeedle) {
+    const next = lowerHay.indexOf(ch, hi);
+    if (next === -1) return false;
+    hi = next + 1;
+  }
+  return true;
+}
+
+function itemMatches(item: CommandPaletteItem, query: string): boolean {
+  if (!query) return true;
+  if (fuzzyMatch(query, item.label)) return true;
+  for (const syn of item.synonyms ?? []) {
+    if (fuzzyMatch(query, syn)) return true;
+  }
+  if (item.description && fuzzyMatch(query, item.description)) return true;
+  return false;
+}
+
+export function TwCommandPalette(
+  props: TwCommandPaletteProps,
+): React.ReactElement | null {
+  const { open, onOpenChange, groups } = props;
+  const placeholder = props.placeholder ?? "Type a command or search…";
+  const emptyMessage =
+    props.emptyMessage ?? "No commands match this query.";
+
+  const [query, setQuery] = useState("");
+  const [activeIndex, setActiveIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  const filtered = useMemo(() => {
+    const trimmed = query.trim();
+    const out: CommandPaletteGroup[] = [];
+    for (const group of groups) {
+      const matched = group.commands.filter((cmd) => itemMatches(cmd, trimmed));
+      if (matched.length > 0) out.push({ ...group, commands: matched });
+    }
+    return out;
+  }, [groups, query]);
+
+  const flat: FlatItem[] = useMemo(() => {
+    const out: FlatItem[] = [];
+    for (const group of filtered) {
+      for (const cmd of group.commands) {
+        out.push({ ...cmd, groupId: group.id, groupLabel: group.label });
+      }
+    }
+    return out;
+  }, [filtered]);
+
+  // Reset query + focus when the palette opens / closes.
+  useEffect(() => {
+    if (!open) return;
+    setQuery("");
+    setActiveIndex(0);
+    const handle = setTimeout(() => inputRef.current?.focus(), 0);
+    return () => clearTimeout(handle);
+  }, [open]);
+
+  // Keep activeIndex inside the filtered result range.
+  useEffect(() => {
+    if (activeIndex >= flat.length) setActiveIndex(flat.length > 0 ? 0 : 0);
+  }, [activeIndex, flat.length]);
+
+  const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+
+  const invokeAt = useCallback(
+    (index: number) => {
+      const item = flat[index];
+      if (!item || item.disabled) return;
+      item.onInvoke();
+      close();
+    },
+    [flat, close],
+  );
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        close();
+        return;
+      }
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setActiveIndex((i) => (flat.length === 0 ? 0 : (i + 1) % flat.length));
+        return;
+      }
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setActiveIndex((i) =>
+          flat.length === 0 ? 0 : (i - 1 + flat.length) % flat.length,
+        );
+        return;
+      }
+      if (event.key === "Enter") {
+        event.preventDefault();
+        invokeAt(activeIndex);
+        return;
+      }
+    },
+    [activeIndex, close, flat.length, invokeAt],
+  );
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-[60] flex items-start justify-center pt-[15vh]"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command palette"
+      data-testid="tw-command-palette"
+      onKeyDown={handleKeyDown}
+    >
+      {/* Backdrop */}
+      <button
+        type="button"
+        aria-label="Close command palette"
+        onClick={close}
+        data-testid="tw-command-palette__backdrop"
+        className={[
+          "absolute inset-0 cursor-default",
+          "bg-[var(--color-bg-overlay)] backdrop-blur-sm",
+          "transition-opacity duration-[var(--motion-fast)]",
+        ].join(" ")}
+      />
+
+      {/* Palette card */}
+      <div
+        className={[
+          "relative z-10 w-[min(720px,90vw)] max-h-[70vh]",
+          "flex flex-col overflow-hidden",
+          "rounded-[var(--radius-md)]",
+          "bg-[var(--color-bg-elevated)]",
+          "shadow-[var(--shadow-float)]",
+          "border border-[var(--color-border-subtle)]",
+          props.className,
+        ]
+          .filter(Boolean)
+          .join(" ")}
+        data-testid="tw-command-palette__card"
+      >
+        {/* Search input */}
+        <div className="border-b border-[var(--color-border-subtle)] px-4 py-3">
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => {
+              setQuery(e.target.value);
+              setActiveIndex(0);
+            }}
+            placeholder={placeholder}
+            aria-label="Search commands"
+            data-testid="tw-command-palette__input"
+            className={[
+              "w-full bg-transparent outline-none",
+              "text-sm text-[var(--color-text-primary)]",
+              "placeholder:text-[var(--color-text-tertiary)]",
+            ].join(" ")}
+          />
+        </div>
+
+        {/* Results */}
+        <div
+          className="flex-1 overflow-y-auto py-1"
+          role="listbox"
+          aria-label="Commands"
+          data-testid="tw-command-palette__list"
+        >
+          {flat.length === 0 ? (
+            <div
+              className="px-4 py-6 text-center text-xs text-[var(--color-text-tertiary)]"
+              data-testid="tw-command-palette__empty"
+            >
+              {emptyMessage}
+            </div>
+          ) : (
+            filtered.map((group) => (
+              <div key={group.id}>
+                <div
+                  className={[
+                    "px-4 pt-2 pb-1",
+                    "text-[10px] font-semibold uppercase tracking-[0.12em]",
+                    "text-[var(--color-text-tertiary)]",
+                  ].join(" ")}
+                  data-testid={`tw-command-palette__group-${group.id}`}
+                >
+                  {group.label}
+                </div>
+                {group.commands.map((cmd) => {
+                  const idxInFlat = flat.findIndex(
+                    (fi) => fi.groupId === group.id && fi.id === cmd.id,
+                  );
+                  const isActive = idxInFlat === activeIndex;
+                  return (
+                    <button
+                      key={cmd.id}
+                      type="button"
+                      role="option"
+                      aria-selected={isActive}
+                      aria-disabled={cmd.disabled ? "true" : undefined}
+                      disabled={cmd.disabled}
+                      onMouseEnter={() => setActiveIndex(idxInFlat)}
+                      onClick={() => invokeAt(idxInFlat)}
+                      data-testid={`tw-command-palette__item-${cmd.id}`}
+                      data-active={isActive ? "true" : undefined}
+                      className={[
+                        "flex w-full items-center gap-3 px-4 py-2 text-left",
+                        "text-sm",
+                        "transition-colors duration-[var(--motion-fast)]",
+                        "disabled:opacity-40 disabled:cursor-not-allowed",
+                        isActive
+                          ? "bg-[var(--color-accent-soft)] text-[var(--color-accent-primary)]"
+                          : "text-[var(--color-text-primary)] hover:bg-[var(--color-bg-hover)]",
+                      ].join(" ")}
+                    >
+                      {cmd.icon ? (
+                        <span
+                          aria-hidden="true"
+                          className="inline-flex h-4 w-4 items-center justify-center shrink-0"
+                        >
+                          {cmd.icon}
+                        </span>
+                      ) : (
+                        <span className="inline-flex h-4 w-4 shrink-0" />
+                      )}
+                      <span className="min-w-0 flex-1">
+                        <span className="block truncate">{cmd.label}</span>
+                        {cmd.description ? (
+                          <span className="block truncate text-[11px] text-[var(--color-text-tertiary)]">
+                            {cmd.description}
+                          </span>
+                        ) : null}
+                      </span>
+                      {cmd.shortcut ? (
+                        <kbd
+                          className={[
+                            "inline-flex items-center shrink-0",
+                            "rounded-[var(--radius-sm)] px-1.5 py-0.5 font-sans text-[10px] font-medium",
+                            "border border-[var(--color-border-subtle)]",
+                            "bg-[var(--color-bg-muted)] text-[var(--color-text-tertiary)]",
+                          ].join(" ")}
+                        >
+                          {cmd.shortcut}
+                        </kbd>
+                      ) : null}
+                    </button>
+                  );
+                })}
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Convenience: checks whether a DOM keyboard event matches the Ctrl+K /
+ * Cmd+K palette open combo.  Hosts compose this into their existing
+ * runtime-shortcut-dispatch path without having to duplicate the
+ * platform-key logic.
+ */
+export function isCommandPaletteOpenShortcut(event: KeyboardEvent): boolean {
+  const isK = event.key === "k" || event.key === "K";
+  if (!isK) return false;
+  // Cmd on macOS, Ctrl everywhere else — accept either.
+  return event.metaKey || event.ctrlKey;
+}

package/src/ui-tailwind/chrome/tw-comment-preview.tsx

@@ -0,0 +1,108 @@
+import * as React from "react";
+
+export interface TwCommentPreviewProps {
+  author: {
+    name: string;
+    initials?: string;
+    avatarUrl?: string;
+  };
+  /** ISO timestamp or a pre-formatted relative time string like "5m ago". */
+  timestamp?: string;
+  /** 1–2 line excerpt of the comment body. */
+  excerpt: string;
+  onOpenThread?: () => void;
+  className?: string;
+}
+
+const focusRingClass =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
+
+export function TwCommentPreview(props: TwCommentPreviewProps): React.JSX.Element {
+  const initials =
+    props.author.initials ?? props.author.name.slice(0, 2).toUpperCase();
+
+  const containerClass = [
+    "flex flex-col gap-1.5",
+    "max-w-[min(20rem,calc(100vw-1.5rem))]",
+    "rounded-[var(--radius-lg)]",
+    "border border-[var(--color-border-subtle)]",
+    "bg-[var(--color-bg-canvas)]",
+    "shadow-[var(--shadow-float)]",
+    "px-3 py-3",
+    props.className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div
+      role="region"
+      aria-label="Comment"
+      className={containerClass}
+      data-testid="tw-comment-preview"
+    >
+      <header className="flex items-center gap-2">
+        {/* avatar: 24×24 */}
+        <span
+          className="inline-flex h-6 w-6 items-center justify-center rounded-full bg-[var(--color-bg-muted)] text-[10px] font-semibold text-[var(--color-text-primary)]"
+          aria-hidden="true"
+          data-testid="tw-comment-preview__avatar"
+        >
+          {props.author.avatarUrl ? (
+            <img
+              src={props.author.avatarUrl}
+              alt=""
+              className="h-6 w-6 rounded-full object-cover"
+            />
+          ) : (
+            initials
+          )}
+        </span>
+        <span
+          className="text-[12px] font-semibold text-[var(--color-text-primary)]"
+          data-testid="tw-comment-preview__author"
+        >
+          {props.author.name}
+        </span>
+        {props.timestamp !== undefined && (
+          <span
+            className="text-[11px] text-[var(--color-text-tertiary)]"
+            data-testid="tw-comment-preview__timestamp"
+          >
+            {props.timestamp}
+          </span>
+        )}
+      </header>
+      <p
+        className="text-[13px] text-[var(--color-text-primary)]"
+        style={{
+          overflow: "hidden",
+          display: "-webkit-box",
+          WebkitLineClamp: 2,
+          WebkitBoxOrient: "vertical",
+        }}
+        data-testid="tw-comment-preview__excerpt"
+      >
+        {props.excerpt}
+      </p>
+      {props.onOpenThread !== undefined && (
+        <button
+          type="button"
+          onClick={props.onOpenThread}
+          className={[
+            "mt-1 inline-flex h-7 items-center justify-center",
+            "rounded-[var(--radius-sm)]",
+            "border border-[var(--color-border-default)]",
+            "bg-[var(--color-bg-canvas)]",
+            "px-3 text-[12px] font-medium text-[var(--color-text-primary)]",
+            "hover:bg-[var(--color-bg-hover)]",
+            focusRingClass,
+          ].join(" ")}
+          data-testid="tw-comment-preview__open-thread"
+        >
+          Open thread
+        </button>
+      )}
+    </div>
+  );
+}

package/src/ui-tailwind/chrome/tw-context-menu.tsx

@@ -0,0 +1,227 @@
+/**
+ * TwContextMenu — compact right-click context menu for the Word editor.
+ *
+ * Design system §6.24: Context menus must not duplicate floating local chrome
+ * (selection toolbar, suggestion card, table toolbar). Rows that overlap
+ * visible floating chrome are filtered out.
+ *
+ * Design system §6.25: Shortcut keys are right-aligned via TwShortcutHint.
+ */
+
+import * as React from "react";
+
+import { TwShortcutHint, type ShortcutKey } from "./tw-shortcut-hint";
+
+// ---------------------------------------------------------------------------
+// Dedupe context
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes which pieces of floating chrome are currently visible.
+ * Used to suppress context-menu rows that would duplicate those surfaces.
+ */
+export interface ContextMenuContext {
+  selectionToolbarVisible: boolean;
+  suggestionCardVisible: boolean;
+  commentCardVisible: boolean;
+  tableToolbarVisible: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Menu item model
+// ---------------------------------------------------------------------------
+
+export type ContextMenuGroupId =
+  | "formatting"
+  | "suggestion"
+  | "table"
+  | "clipboard"
+  | "comment"
+  | "misc";
+
+export interface ContextMenuItem {
+  kind: "item";
+  /** Unique identifier for the row. */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Optional icon element rendered left of the label. */
+  icon?: React.ReactNode;
+  /** Shortcut key sequence shown right-aligned via TwShortcutHint. */
+  shortcut?: ShortcutKey[];
+  /**
+   * Group membership — determines which rows are suppressed when the
+   * corresponding floating chrome is visible (§6.24).
+   */
+  group: ContextMenuGroupId;
+  /** Whether the row is disabled (rendered but non-interactive). */
+  disabled?: boolean;
+  onSelect?: () => void;
+}
+
+export interface ContextMenuSeparator {
+  kind: "separator";
+  id: string;
+}
+
+export type ContextMenuEntry = ContextMenuItem | ContextMenuSeparator;
+
+// ---------------------------------------------------------------------------
+// Dedupe helper (pure — no React)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns only the rows that should be visible given the current floating
+ * chrome context. §6.24: "Do not show a richer command set than the local
+ * floating chrome already exposes."
+ */
+export function filterContextMenuEntries(
+  entries: ContextMenuEntry[],
+  ctx: ContextMenuContext,
+): ContextMenuEntry[] {
+  const suppressedGroups = new Set<ContextMenuGroupId>();
+
+  if (ctx.selectionToolbarVisible) {
+    suppressedGroups.add("formatting");
+  }
+  if (ctx.suggestionCardVisible) {
+    suppressedGroups.add("suggestion");
+  }
+  if (ctx.tableToolbarVisible) {
+    suppressedGroups.add("table");
+  }
+
+  const filtered = entries.filter((e) => {
+    if (e.kind === "separator") return true;
+    return !suppressedGroups.has(e.group);
+  });
+
+  // Collapse leading/trailing/consecutive separators
+  return collapseSeparators(filtered);
+}
+
+function collapseSeparators(entries: ContextMenuEntry[]): ContextMenuEntry[] {
+  const out: ContextMenuEntry[] = [];
+  for (const entry of entries) {
+    if (entry.kind === "separator") {
+      // Skip if nothing has been emitted yet or if last emitted was also a separator
+      if (out.length === 0) continue;
+      const last = out[out.length - 1];
+      if (last.kind === "separator") continue;
+      out.push(entry);
+    } else {
+      out.push(entry);
+    }
+  }
+  // Drop trailing separator
+  if (out.length > 0 && out[out.length - 1].kind === "separator") {
+    out.pop();
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export interface TwContextMenuProps {
+  entries: ContextMenuEntry[];
+  context?: Partial<ContextMenuContext>;
+  platform?: "mac" | "win";
+  "data-testid"?: string;
+}
+
+const FULL_CONTEXT: ContextMenuContext = {
+  selectionToolbarVisible: false,
+  suggestionCardVisible: false,
+  commentCardVisible: false,
+  tableToolbarVisible: false,
+};
+
+export function TwContextMenu(props: TwContextMenuProps): React.JSX.Element {
+  const {
+    entries,
+    context,
+    platform,
+    "data-testid": testId = "tw-context-menu",
+  } = props;
+
+  const ctx: ContextMenuContext = { ...FULL_CONTEXT, ...context };
+  const visible = filterContextMenuEntries(entries, ctx);
+
+  return (
+    <div
+      data-testid={testId}
+      role="menu"
+      className={[
+        "flex flex-col",
+        "rounded-[var(--radius-lg)]",
+        "bg-[var(--color-bg-elevated)]",
+        "shadow-[var(--shadow-float)]",
+        "border border-[var(--color-border-subtle)]",
+        "py-1.5",
+        "min-w-[160px]",
+      ].join(" ")}
+    >
+      {visible.map((entry) => {
+        if (entry.kind === "separator") {
+          return (
+            <hr
+              key={entry.id}
+              role="separator"
+              className="my-1 border-[var(--color-border-subtle)]"
+            />
+          );
+        }
+        return (
+          <ContextMenuRow
+            key={entry.id}
+            item={entry}
+            platform={platform}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Row
+// ---------------------------------------------------------------------------
+
+interface ContextMenuRowProps {
+  item: ContextMenuItem;
+  platform?: "mac" | "win";
+}
+
+function ContextMenuRow({ item, platform }: ContextMenuRowProps): React.JSX.Element {
+  const { label, icon, shortcut, disabled, onSelect } = item;
+
+  return (
+    <button
+      role="menuitem"
+      data-testid={`context-menu-item-${item.id}`}
+      disabled={disabled}
+      onClick={disabled ? undefined : onSelect}
+      className={[
+        "flex items-center justify-between h-[30px] w-full px-3",
+        "text-[13px] text-[var(--color-text-primary)] text-left",
+        "hover:bg-[var(--color-bg-hover)]",
+        "disabled:opacity-40 disabled:cursor-not-allowed",
+        "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--color-accent)]",
+      ].join(" ")}
+    >
+      <span className="flex items-center gap-2 min-w-0">
+        {icon && (
+          <span className="shrink-0 w-4 h-4 flex items-center justify-center text-[var(--color-text-secondary)]">
+            {icon}
+          </span>
+        )}
+        <span className="truncate">{label}</span>
+      </span>
+      {shortcut && shortcut.length > 0 && (
+        <TwShortcutHint keys={shortcut} platform={platform} />
+      )}
+    </button>
+  );
+}