@scalepad/ui 0.1.0

package/src/components/SlashRichTextEditor/SlashRichTextEditor.tsx

@@ -0,0 +1,538 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import {
+  EditorContent,
+  type Editor,
+  type Range,
+  useEditor,
+  type JSONContent,
+} from '@tiptap/react';
+
+import {
+  resolveFormattingCommands,
+  type FormattingToolbarVariant,
+} from '../RichText/formattingCommands';
+import { getRichTextExtensions } from '../RichText/richTextExtensions';
+import {
+  docsEqual,
+  isDocEmpty,
+  normalizeValue,
+} from '../RichText/richTextHelpers';
+import {
+  installRichTextImageHandlers,
+  useRichTextImageLoader,
+  type RichTextImageEditorConfig,
+} from '../RichText/richTextImageHandlers';
+import * as proseStyles from '../RichText/richTextProse.css';
+import { Text } from '../Typography';
+import { SelectionBubbleMenu } from './SelectionBubbleMenu';
+import { SlashCommandMenu } from './SlashCommandMenu';
+import * as classes from './SlashRichTextEditor.css';
+import { SlashSuggestionExtension } from './SlashSuggestionExtension';
+
+import type { SlashCommand, SlashSuggestionState } from './types';
+
+/**
+ * Imperative handle for callers that need to focus / blur the editor or
+ * inspect the current plain text without re-rendering on every keystroke.
+ */
+export interface SlashRichTextEditorHandle {
+  focus: () => void;
+  blur: () => void;
+  getPlainText: () => string;
+}
+
+export interface SlashRichTextEditorProps {
+  value: JSONContent | null;
+  onChange: (next: JSONContent) => void;
+  /**
+   * Plain-text mirror — fired alongside `onChange` so callers using the doc
+   * for search / validation don't need to re-derive it.
+   */
+  onPlainTextChange?: (text: string) => void;
+  placeholder?: string;
+  autoFocus?: boolean;
+  /** Custom field commands appended below the formatting toolbar. */
+  extraCommands?: SlashCommand[];
+  /** Toggles the built-in formatting toolbar layout. Defaults to 'standard'. */
+  formattingToolbar?: FormattingToolbarVariant;
+  onSubmit?: () => void;
+  onCancel?: () => void;
+  /**
+   * When true, plain `Enter` (no shift, no menu open) submits the form,
+   * matching the legacy `<textarea>` behavior. `Shift+Enter` always inserts
+   * a newline and `Cmd/Ctrl+Enter` always submits regardless of this flag.
+   * Defaults to false so the editor behaves like a normal multi-line input.
+   */
+  submitOnEnter?: boolean;
+  /**
+   * Mirrors the legacy `<textarea>` `maxLength` so consumers can keep their
+   * existing length validation. Compared against `editor.getText()`.
+   */
+  maxLengthPlainText?: number;
+  errorMessage?: string;
+  className?: string;
+  ariaLabel?: string;
+  disabled?: boolean;
+  /**
+   * Visual chrome around the editor surface.
+   *
+   * - `seamless` (default): no border / background / padding so the editor
+   *   inherits whatever container the consumer wraps it in (e.g. the
+   *   green-bordered Active draft card in `ActionItemQuickCreate`).
+   * - `bordered`: opt-in input-style box with focus ring, useful when the
+   *   editor stands on its own.
+   */
+  variant?: 'seamless' | 'bordered';
+  /**
+   * When provided, enables inline image upload via paste / drop. See
+   * {@link RichTextImageEditorConfig} for the full callback surface.
+   */
+  image?: RichTextImageEditorConfig;
+}
+
+/**
+ * Filter the consumer's `extraCommands` by the current slash query.
+ * Matches the legacy `filterSlashFields` contract (case-insensitive
+ * substring on the label).
+ */
+function filterCommandsByQuery(
+  commands: SlashCommand[],
+  query: string,
+): SlashCommand[] {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return commands;
+  return commands.filter(c => c.label.toLowerCase().includes(normalized));
+}
+
+/**
+ * Tiptap-based replacement for the action item / initiative `<textarea>`s.
+ * Renders a single contenteditable surface plus a popup that opens on `/` and
+ * exposes both formatting commands (slim icon toolbar) and consumer-provided
+ * field commands (filterable list). Markdown shortcuts work via StarterKit's
+ * built-in input rules so most users never need to open the menu.
+ */
+export const SlashRichTextEditor = forwardRef<
+  SlashRichTextEditorHandle,
+  SlashRichTextEditorProps
+>(
+  (
+    {
+      value,
+      onChange,
+      onPlainTextChange,
+      placeholder,
+      autoFocus = false,
+      extraCommands = [],
+      formattingToolbar = 'standard',
+      onSubmit,
+      onCancel,
+      submitOnEnter = false,
+      maxLengthPlainText,
+      errorMessage,
+      className,
+      ariaLabel,
+      disabled = false,
+      variant = 'seamless',
+      image,
+    },
+    ref,
+  ) => {
+    const enableImages = Boolean(image);
+    /**
+     * The slash plugin's render lifecycle is non-React, so we mirror the
+     * relevant pieces into React state and re-render the popup whenever the
+     * suggestion plugin tells us the query / range changed.
+     */
+    const [suggestion, setSuggestion] = useState<SlashSuggestionState | null>(
+      null,
+    );
+    const [highlightedIndex, setHighlightedIndex] = useState(0);
+    const [focused, setFocused] = useState(false);
+
+    // Refs let the suggestion plugin (which is created once) reach the latest
+    // commands + highlight state without re-instantiating Tiptap on every render.
+    const suggestionRef = useRef<SlashSuggestionState | null>(suggestion);
+    suggestionRef.current = suggestion;
+
+    const extraCommandsRef = useRef<SlashCommand[]>(extraCommands);
+    extraCommandsRef.current = extraCommands;
+
+    const highlightedRef = useRef(highlightedIndex);
+    highlightedRef.current = highlightedIndex;
+
+    const visibleCommandsRef = useRef<SlashCommand[]>([]);
+
+    const onSubmitRef = useRef(onSubmit);
+    onSubmitRef.current = onSubmit;
+
+    const onCancelRef = useRef(onCancel);
+    onCancelRef.current = onCancel;
+
+    const submitOnEnterRef = useRef(submitOnEnter);
+    submitOnEnterRef.current = submitOnEnter;
+
+    const closeSuggestion = useCallback(() => {
+      setSuggestion(null);
+      setHighlightedIndex(0);
+    }, []);
+
+    const runCommand = useCallback(
+      (cmd: SlashCommand, currentRange: Range, editor: Editor) => {
+        if (cmd.disabled) return;
+        // Drop the `/<query>` token first so the consumer doesn't have to.
+        editor.chain().focus().deleteRange(currentRange).run();
+        cmd.run({ editor, range: currentRange });
+        // Hand control back to suggestion's exit() so its plugin state stays
+        // consistent. Falling through to setSuggestion(null) is a no-op if the
+        // exit handler already cleared us.
+        suggestionRef.current?.exit?.();
+        closeSuggestion();
+      },
+      [closeSuggestion],
+    );
+
+    const toolbarCommands = useMemo(
+      () => resolveFormattingCommands(formattingToolbar),
+      [formattingToolbar],
+    );
+
+    // Stable ref the suggestion plugin can ask for "what's currently visible?"
+    const filterAndCacheVisibleCommands = useCallback((query: string) => {
+      const filtered = filterCommandsByQuery(extraCommandsRef.current, query);
+      visibleCommandsRef.current = filtered;
+      return filtered;
+    }, []);
+
+    // Build the suggestion config once. We avoid passing closures over React
+    // state — the plugin would otherwise capture stale values. Refs +
+    // imperative setters keep the wiring stable across renders.
+    const suggestionOptions = useMemo(
+      () => ({
+        char: '/',
+        allowSpaces: false,
+        allowedPrefixes: [' ', '\n', '\t'],
+        startOfLine: false,
+        items: ({ query }: { query: string }) => {
+          return filterAndCacheVisibleCommands(query).map(c => c.id);
+        },
+        render: () => {
+          let cachedRange: Range | null = null;
+          let cachedExit: () => void = () => {};
+          return {
+            onStart: (props: {
+              query: string;
+              range: Range;
+              command: (item: unknown) => void;
+              clientRect?: (() => DOMRect | null) | null;
+            }) => {
+              cachedRange = props.range;
+              cachedExit = () => {
+                setSuggestion(null);
+                setHighlightedIndex(0);
+              };
+              setHighlightedIndex(0);
+              setSuggestion({
+                query: props.query,
+                range: props.range,
+                exit: cachedExit,
+              });
+            },
+            onUpdate: (props: { query: string; range: Range }) => {
+              cachedRange = props.range;
+              setSuggestion(prev =>
+                prev
+                  ? { ...prev, query: props.query, range: props.range }
+                  : {
+                      query: props.query,
+                      range: props.range,
+                      exit: cachedExit,
+                    },
+              );
+              setHighlightedIndex(0);
+            },
+            onKeyDown: (props: { event: KeyboardEvent }) => {
+              const { event } = props;
+              const visible = visibleCommandsRef.current;
+              if (event.key === 'ArrowDown') {
+                event.preventDefault();
+                setHighlightedIndex(idx =>
+                  visible.length === 0 ? 0 : (idx + 1) % visible.length,
+                );
+                return true;
+              }
+              if (event.key === 'ArrowUp') {
+                event.preventDefault();
+                setHighlightedIndex(idx =>
+                  visible.length === 0
+                    ? 0
+                    : (idx - 1 + visible.length) % visible.length,
+                );
+                return true;
+              }
+              if (event.key === 'Enter') {
+                event.preventDefault();
+                const visibleNow = visibleCommandsRef.current;
+                const target = visibleNow[highlightedRef.current];
+                if (target && cachedRange) {
+                  runCommandFromKeyboardRef.current(target, cachedRange);
+                }
+                return true;
+              }
+              if (event.key === 'Escape') {
+                event.preventDefault();
+                cachedExit();
+                return true;
+              }
+              return false;
+            },
+            onExit: () => {
+              cachedRange = null;
+              setSuggestion(null);
+              setHighlightedIndex(0);
+            },
+          };
+        },
+        command: () => {
+          // No-op: command application happens through `runCommand` when the
+          // user clicks / hits Enter. The suggestion plugin still calls this
+          // when a programmatic command callback is requested.
+        },
+      }),
+      [filterAndCacheVisibleCommands],
+    );
+
+    // Imperative bridge from the suggestion's keyboard handler back to React,
+    // so we don't need to thread the editor through the closure. The ref
+    // wrapper keeps `useMemo` deps stable while still letting us pull the
+    // latest `runCommand` closure on every keystroke.
+    const editorRef = useRef<Editor | null>(null);
+    const runCommandFromKeyboardRef = useRef<
+      (cmd: SlashCommand, currentRange: Range) => void
+    >(() => {});
+    runCommandFromKeyboardRef.current = (
+      cmd: SlashCommand,
+      currentRange: Range,
+    ) => {
+      const editor = editorRef.current;
+      if (!editor) return;
+      runCommand(cmd, currentRange, editor);
+    };
+
+    const imageHandlers = useMemo(
+      () => installRichTextImageHandlers(image),
+      [image],
+    );
+
+    const editor = useEditor(
+      {
+        immediatelyRender: false,
+        editable: !disabled,
+        extensions: [
+          ...getRichTextExtensions({ placeholder, enableImages }),
+          SlashSuggestionExtension.configure({ suggestion: suggestionOptions }),
+        ],
+        content: normalizeValue(value),
+        autofocus: autoFocus ? 'end' : false,
+        editorProps: {
+          attributes: ariaLabel ? { 'aria-label': ariaLabel } : {},
+          ...imageHandlers,
+          handleKeyDown: (_view, event) => {
+            // Suggestion plugin gets first crack — only handle global shortcuts
+            // when the menu is closed.
+            if (suggestionRef.current) return false;
+
+            if (event.key === 'Escape') {
+              if (onCancelRef.current) {
+                event.preventDefault();
+                onCancelRef.current();
+                return true;
+              }
+              return false;
+            }
+
+            if (
+              event.key === 'Enter' &&
+              !event.shiftKey &&
+              (event.metaKey || event.ctrlKey)
+            ) {
+              event.preventDefault();
+              onSubmitRef.current?.();
+              return true;
+            }
+
+            if (
+              submitOnEnterRef.current &&
+              event.key === 'Enter' &&
+              !event.shiftKey &&
+              !event.metaKey &&
+              !event.ctrlKey &&
+              !event.altKey
+            ) {
+              event.preventDefault();
+              onSubmitRef.current?.();
+              return true;
+            }
+
+            return false;
+          },
+        },
+        onUpdate: ({ editor: current }) => {
+          const next = current.getJSON();
+          const plainText = current.getText();
+          if (
+            maxLengthPlainText != null &&
+            plainText.length > maxLengthPlainText
+          ) {
+            // Trim the overflow by deleting the trailing characters in a
+            // single ProseMirror transaction. Doing it this way preserves
+            // every mark / node / link the user had typed up to the limit —
+            // a blanket `setContent` rebuild would flatten the doc back to a
+            // single plain paragraph.
+            //
+            // We compute how many plain-text characters need to drop and
+            // walk that many positions backward from doc end. ProseMirror
+            // positions are 1-based and include node boundaries, but
+            // `delete(from, end)` collapses any non-text positions it
+            // crosses automatically, so the conservative "delete the last
+            // N positions" approach lands the doc at exactly the limit.
+            //
+            // Consumers that care about strict enforcement should also apply
+            // a server-side check.
+            const excess = plainText.length - maxLengthPlainText;
+            const { state } = current;
+            const end = state.doc.content.size;
+            const deleteFrom = Math.max(0, end - excess);
+            current.view.dispatch(state.tr.delete(deleteFrom, end));
+            onChange(current.getJSON());
+            onPlainTextChange?.(current.getText());
+            return;
+          }
+          onChange(next);
+          onPlainTextChange?.(plainText);
+        },
+        onFocus: () => setFocused(true),
+        onBlur: () => setFocused(false),
+      },
+      // Remount only when `disabled` changes (Tiptap doesn't have a runtime
+      // setter for it) or when image support is toggled on/off (since that
+      // changes the schema). The image callbacks themselves are captured
+      // through `imageHandlers` so swapping `image.uploadImage` doesn't
+      // rebuild the editor.
+      [disabled, enableImages],
+    );
+
+    useRichTextImageLoader(editor, image);
+
+    editorRef.current = editor;
+
+    // Keep the editor in sync when the parent replaces the value (e.g. after a
+    // successful submit clears the form).
+    useEffect(() => {
+      if (!editor) return;
+      const next = normalizeValue(value);
+      if (!docsEqual(editor.getJSON(), next)) {
+        editor.commands.setContent(next, { emitUpdate: false });
+      }
+    }, [editor, value]);
+
+    // Update the Placeholder extension at runtime so a changing `placeholder`
+    // prop doesn't have to remount the editor (which would reset selection
+    // and scroll). The extension is added unconditionally by
+    // `getRichTextExtensions`, so the lookup will always find it.
+    useEffect(() => {
+      if (!editor) return;
+      const placeholderExt = editor.extensionManager.extensions.find(
+        ext => ext.name === 'placeholder',
+      );
+      if (!placeholderExt) return;
+      if (placeholderExt.options.placeholder === (placeholder ?? '')) return;
+      placeholderExt.options.placeholder = placeholder ?? '';
+      // Force a redraw so the empty-editor placeholder pseudo updates.
+      editor.view.dispatch(editor.state.tr);
+    }, [editor, placeholder]);
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: () => editor?.commands.focus(),
+        blur: () => editor?.commands.blur(),
+        getPlainText: () => editor?.getText() ?? '',
+      }),
+      [editor],
+    );
+
+    const visibleCommands = useMemo(
+      () => filterCommandsByQuery(extraCommands, suggestion?.query ?? ''),
+      [extraCommands, suggestion?.query],
+    );
+
+    // Mirror the visible list into the ref so the suggestion plugin's keyboard
+    // handler sees the same array React just rendered.
+    useEffect(() => {
+      visibleCommandsRef.current = visibleCommands;
+    }, [visibleCommands]);
+
+    if (!editor) return null;
+
+    const showError = Boolean(errorMessage);
+    const isEmpty = isDocEmpty(editor.getJSON());
+
+    const surfaceClass = [
+      classes.editorSurface,
+      proseStyles.prose,
+      variant === 'bordered' ? classes.editorSurfaceBordered : undefined,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div className={[classes.root, className].filter(Boolean).join(' ')}>
+        <div
+          className={surfaceClass}
+          data-focused={focused ? 'true' : undefined}
+          data-error={showError ? 'true' : undefined}
+          data-disabled={disabled ? 'true' : undefined}
+          data-empty={isEmpty ? 'true' : undefined}
+        >
+          <EditorContent editor={editor} />
+          <SelectionBubbleMenu
+            editor={editor}
+            hidden={Boolean(suggestion) || disabled}
+          />
+          {suggestion ? (
+            <div className={`${classes.menuLayer} ${classes.menuLayerActive}`}>
+              <SlashCommandMenu
+                editor={editor}
+                range={suggestion.range}
+                query={suggestion.query}
+                commands={visibleCommands}
+                toolbarCommands={toolbarCommands}
+                highlightedIndex={highlightedIndex}
+                onHighlightChange={setHighlightedIndex}
+                onSelect={cmd => runCommand(cmd, suggestion.range, editor)}
+                onVisibleCommandsChange={() => {
+                  // No-op: highlight reset is driven by suggestion onUpdate.
+                }}
+                ariaLabel={ariaLabel ? `${ariaLabel} commands` : undefined}
+              />
+            </div>
+          ) : null}
+        </div>
+        {showError ? (
+          <Text variant="caption2" className={classes.errorMessage}>
+            {errorMessage}
+          </Text>
+        ) : null}
+      </div>
+    );
+  },
+);

package/src/components/SlashRichTextEditor/SlashSuggestionExtension.ts

@@ -0,0 +1,48 @@
+import { Extension } from '@tiptap/react';
+import Suggestion, {
+  SuggestionPluginKey,
+  type SuggestionOptions,
+} from '@tiptap/suggestion';
+
+/**
+ * Tiptap extension that wires `@tiptap/suggestion` to the `/` trigger so
+ * `SlashRichTextEditor` can render its own popup. The extension itself stays
+ * thin — the actual `items`, `render`, and `command` callbacks are supplied by
+ * the React component via `configure({ suggestion })`. Splitting the wiring
+ * here keeps the editor file focused on state management and lets unit tests
+ * import the extension in isolation.
+ */
+export interface SlashSuggestionOptions {
+  suggestion: Omit<SuggestionOptions, 'editor'>;
+}
+
+export const SlashSuggestionExtension =
+  Extension.create<SlashSuggestionOptions>({
+    name: 'slashSuggestion',
+    addOptions() {
+      return {
+        suggestion: {
+          char: '/',
+          allowSpaces: false,
+          // Trigger only at start-of-line or after whitespace so `foo/bar`
+          // never opens the menu — matches the legacy `findActiveSlashAnchor`
+          // contract that consumers were already relying on.
+          allowedPrefixes: [' ', '\n', '\t'],
+          startOfLine: false,
+          items: () => [],
+          render: () => ({}),
+          command: () => {},
+        },
+      };
+    },
+    addProseMirrorPlugins() {
+      return [
+        Suggestion({
+          editor: this.editor,
+          ...this.options.suggestion,
+        }),
+      ];
+    },
+  });
+
+export { SuggestionPluginKey };

package/src/components/SlashRichTextEditor/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Slash-specific public surface. The shared toolbar / formatting commands /
+ * extension set live in `../RichText` and are re-exported from the package
+ * root via `RichText`'s barrel — this module only exposes the slash
+ * editor itself plus its slash-specific extension and types.
+ */
+export {
+  SlashRichTextEditor,
+  type SlashRichTextEditorHandle,
+  type SlashRichTextEditorProps,
+} from './SlashRichTextEditor';
+export { SlashSuggestionExtension } from './SlashSuggestionExtension';
+export type { SlashCommand, SlashSuggestionState } from './types';

package/src/components/SlashRichTextEditor/types.ts

@@ -0,0 +1,48 @@
+import type { Editor, Range } from '@tiptap/react';
+import type { LucideIcon } from 'lucide-react';
+
+/**
+ * A single entry in the slash menu's command list (the lower section of
+ * the Option B layout). Formatting commands rendered in the toolbar are
+ * described separately via `FormattingToolbarCommand` (in
+ * `RichText/formattingTypes.ts`) because they don't participate in the
+ * filterable list.
+ */
+export interface SlashCommand {
+  /** Stable id for keyboard nav and React keys. */
+  id: string;
+  /** Display label rendered in the row. */
+  label: string;
+  /** Lucide icon shown to the left of the label. */
+  icon: LucideIcon;
+  /** Short keyboard hint shown on the right (e.g. `C`, `D`). */
+  shortcut?: string;
+  /** Section header label used to bucket the row in the list. */
+  group: string;
+  /** Optional helper text — currently unused but reserved for future UX. */
+  description?: string;
+  /** Greyed out and unselectable if true. */
+  disabled?: boolean;
+  /** Replaces the shortcut chip on disabled rows. */
+  disabledHint?: string;
+  /**
+   * Called when the user selects the row. The component drops the `/<query>`
+   * token before invoking this so consumers don't have to think about the
+   * slash anchor — they just open their flyout / mutate the doc.
+   */
+  run: (ctx: { editor: Editor; range: Range }) => void;
+}
+
+/**
+ * Shape stored in the React state while the slash suggestion is active.
+ * Drives the menu UI (open/close, query, range, command callback).
+ */
+export interface SlashSuggestionState {
+  query: string;
+  range: Range;
+  /**
+   * The exit callback registered by `@tiptap/suggestion`. We invoke this when
+   * the user picks something so the plugin can clean up its internal state.
+   */
+  exit: () => void;
+}