@scalepad/ui 0.1.0

package/src/components/RichText/RichTextInline.tsx

@@ -0,0 +1,318 @@
+/**
+ * RichTextInline
+ *
+ * Single-line preview renderer for Tiptap / ProseMirror `JSONContent`.
+ * Walks the doc, flattens its block structure into an array of "logical
+ * lines" (one per paragraph / heading / list item / blockquote / code
+ * block), drops empty lines, and joins the non-empty ones with a single
+ * subtle dot separator. Inline marks (`<strong>`, `<em>`, `<code>`,
+ * `<u>`, `<s>`, `<a>`) are preserved so a bold word in the editor stays
+ * bold in the row preview.
+ *
+ * Use this for cell-style previews. For full multi-line rendering, use
+ * `RichTextView`.
+ */
+import { Fragment, type ReactNode } from 'react';
+
+import * as classes from './RichTextInline.css';
+
+import type { JSONContent } from '@tiptap/react';
+
+export interface RichTextInlineProps {
+  value: JSONContent | null;
+  /** Placeholder rendered when the doc is empty. */
+  placeholder?: string;
+  className?: string;
+}
+
+interface MarkSpec {
+  type: string;
+  attrs?: Record<string, unknown>;
+}
+
+/**
+ * One flattened logical line of the doc. The renderer walks the JSON
+ * tree, emits a `Segment` per visible block, and finally joins them
+ * with a single separator. Each segment also carries its raw text so
+ * we can quickly drop blocks whose visible text is empty/whitespace
+ * (Tiptap loves empty paragraphs from accidental Enter presses).
+ */
+interface Segment {
+  key: string;
+  rawText: string;
+  /** Optional decoration wrapper — heading weight, list bullet, blockquote italic. */
+  prefix?: ReactNode;
+  wrapper?: 'heading1' | 'heading2' | 'blockquote' | 'codeBlock' | null;
+  inline: ReactNode;
+}
+
+/**
+ * Wrap a leaf text node in the React equivalents of its ProseMirror marks
+ * (e.g. `<strong>` for `bold`, `<a>` for `link`). Marks are nested in
+ * declaration order so the outermost wrapper is the first mark; that
+ * matches how Tiptap serializes them and keeps anchor / inline-code
+ * styling deterministic.
+ */
+function renderMarkedText(
+  text: string,
+  marks: MarkSpec[] | undefined,
+): ReactNode {
+  if (!marks || marks.length === 0) return text;
+  return marks.reduceRight<ReactNode>((child, mark) => {
+    switch (mark.type) {
+      case 'bold':
+        return <strong>{child}</strong>;
+      case 'italic':
+        return <em>{child}</em>;
+      case 'code':
+        return <code className={classes.code}>{child}</code>;
+      case 'underline':
+        return <u>{child}</u>;
+      case 'strike':
+        return <s>{child}</s>;
+      case 'link': {
+        const href =
+          (mark.attrs &&
+            typeof mark.attrs.href === 'string' &&
+            mark.attrs.href) ||
+          undefined;
+        return (
+          <a
+            className={classes.link}
+            href={href}
+            target="_blank"
+            rel="noreferrer noopener"
+          >
+            {child}
+          </a>
+        );
+      }
+      default:
+        return child;
+    }
+  }, text);
+}
+
+interface InlineResult {
+  nodes: ReactNode[];
+  text: string;
+}
+
+/**
+ * Walk the inline children of a block (text + hardBreak only) and
+ * produce both the rendered React nodes and the raw text. Anything
+ * that isn't an inline leaf is ignored — block-level descendants are
+ * picked up by the outer flattener and become their own segments.
+ */
+function renderInline(
+  nodes: JSONContent[] | undefined,
+  keyPrefix: string,
+): InlineResult {
+  if (!nodes || nodes.length === 0) return { nodes: [], text: '' };
+
+  const out: ReactNode[] = [];
+  let text = '';
+
+  nodes.forEach((node, idx) => {
+    const key = `${keyPrefix}-${idx}`;
+    switch (node.type) {
+      case 'text': {
+        const value = node.text ?? '';
+        text += value;
+        out.push(
+          <Fragment key={key}>
+            {renderMarkedText(value, node.marks as MarkSpec[] | undefined)}
+          </Fragment>,
+        );
+        break;
+      }
+      case 'hardBreak':
+        text += ' ';
+        out.push(<Fragment key={key}> </Fragment>);
+        break;
+      default:
+        // Block-level descendant; surface its inline text so the
+        // wrapper paragraph stays non-empty for filtering, but let
+        // the outer walker handle the block itself.
+        if (Array.isArray(node.content)) {
+          const child = renderInline(node.content, key);
+          text += child.text;
+          out.push(<Fragment key={key}>{child.nodes}</Fragment>);
+        }
+        break;
+    }
+  });
+
+  return { nodes: out, text };
+}
+
+/**
+ * Recursively flatten the doc into an ordered array of inline
+ * segments. Each call appends to `acc` so callers can capture
+ * structure (heading vs list item vs paragraph) without having to
+ * thread separators through the tree.
+ */
+function collectSegments(
+  nodes: JSONContent[] | undefined,
+  acc: Segment[],
+  keyPrefix: string,
+  context: { listMarker?: string } = {},
+): void {
+  if (!nodes || nodes.length === 0) return;
+
+  nodes.forEach((node, idx) => {
+    const key = `${keyPrefix}-${idx}-${node.type}`;
+
+    switch (node.type) {
+      case 'paragraph': {
+        const inline = renderInline(node.content, key);
+        acc.push({
+          key,
+          rawText: inline.text,
+          inline: inline.nodes,
+          prefix: context.listMarker ? (
+            <span className={classes.bullet}>{context.listMarker}</span>
+          ) : undefined,
+          wrapper: null,
+        });
+        break;
+      }
+
+      case 'heading': {
+        const level = (node.attrs?.level as number | undefined) ?? 1;
+        const inline = renderInline(node.content, key);
+        acc.push({
+          key,
+          rawText: inline.text,
+          inline: inline.nodes,
+          wrapper: level === 1 ? 'heading1' : 'heading2',
+          prefix: context.listMarker ? (
+            <span className={classes.bullet}>{context.listMarker}</span>
+          ) : undefined,
+        });
+        break;
+      }
+
+      case 'blockquote': {
+        // A blockquote can contain either inline-only content (the common
+        // case: `<blockquote><p>quote</p></blockquote>`) or block-level
+        // children (lists, nested blockquotes, code blocks). When all the
+        // children flatten to inline content, emit a single quoted segment
+        // for the whole quote. When there are block-level children, defer
+        // entirely to the recursive walker so we don't double-count.
+        const children = node.content ?? [];
+        const hasBlockLevelChild = children.some(
+          child =>
+            child.type !== 'paragraph' &&
+            child.type !== 'text' &&
+            child.type !== 'hardBreak',
+        );
+
+        if (!hasBlockLevelChild) {
+          const inline = renderInline(node.content, key);
+          acc.push({
+            key,
+            rawText: inline.text,
+            inline: inline.nodes,
+            wrapper: 'blockquote',
+          });
+        } else {
+          children.forEach((child, childIdx) => {
+            collectSegments([child], acc, `${key}-${childIdx}`);
+          });
+        }
+        break;
+      }
+
+      case 'codeBlock': {
+        const inline = renderInline(node.content, key);
+        acc.push({
+          key,
+          rawText: inline.text,
+          inline: inline.nodes,
+          wrapper: 'codeBlock',
+        });
+        break;
+      }
+
+      case 'bulletList':
+      case 'orderedList': {
+        const items = node.content ?? [];
+        const isOrdered = node.type === 'orderedList';
+        items.forEach((item, itemIdx) => {
+          const marker = isOrdered ? `${itemIdx + 1}.` : '•';
+          collectSegments(item.content, acc, `${key}-i${itemIdx}`, {
+            listMarker: marker,
+          });
+        });
+        break;
+      }
+
+      case 'listItem':
+        collectSegments(node.content, acc, key, context);
+        break;
+
+      default:
+        if (Array.isArray(node.content) && node.content.length > 0) {
+          collectSegments(node.content, acc, key, context);
+        }
+        break;
+    }
+  });
+}
+
+function isWhitespace(s: string): boolean {
+  return s.replace(/\s+/g, '').length === 0;
+}
+
+function renderSegmentBody(seg: Segment): ReactNode {
+  switch (seg.wrapper) {
+    case 'heading1':
+      return <span className={classes.headingStrong}>{seg.inline}</span>;
+    case 'heading2':
+      return <span className={classes.headingMedium}>{seg.inline}</span>;
+    case 'blockquote':
+      return <em className={classes.blockquote}>{seg.inline}</em>;
+    case 'codeBlock':
+      return <code className={classes.code}>{seg.inline}</code>;
+    default:
+      return seg.inline;
+  }
+}
+
+export function RichTextInline({
+  value,
+  placeholder,
+  className,
+}: RichTextInlineProps) {
+  const segments: Segment[] = [];
+  if (value?.content) {
+    collectSegments(value.content, segments, 'root');
+  }
+  const visible = segments.filter(seg => !isWhitespace(seg.rawText));
+
+  if (visible.length === 0) {
+    if (!placeholder) return null;
+    return (
+      <span className={[classes.empty, className].filter(Boolean).join(' ')}>
+        {placeholder}
+      </span>
+    );
+  }
+
+  return (
+    <span className={[classes.root, className].filter(Boolean).join(' ')}>
+      {visible.map((seg, idx) => (
+        <Fragment key={seg.key}>
+          {idx > 0 ? (
+            <span className={classes.separator} aria-hidden>
+              ·
+            </span>
+          ) : null}
+          {seg.prefix}
+          {renderSegmentBody(seg)}
+        </Fragment>
+      ))}
+    </span>
+  );
+}

package/src/components/RichText/formattingCommands.ts

@@ -0,0 +1,181 @@
+import {
+  Bold,
+  Heading1,
+  Heading2,
+  Heading3,
+  Italic,
+  Link2,
+  List,
+  ListOrdered,
+  TextQuote,
+  Underline as UnderlineIcon,
+} from 'lucide-react';
+
+import type { FormattingToolbarCommand } from './formattingTypes';
+
+import type { ChainedCommands, Editor } from '@tiptap/react';
+
+type FormattingRunArgs = Parameters<FormattingToolbarCommand['run']>[0];
+
+/**
+ * Most formatting commands share the same shape: focus the editor, drop the
+ * slash trigger range when invoked from the slash menu, apply one chained
+ * mutation, and dispatch. Centralising it here keeps the command list small
+ * and removes the copy/paste risk of forgetting `.focus()` or the range
+ * delete on a new command.
+ */
+function runWithChain(
+  apply: (chain: ChainedCommands, editor: Editor) => ChainedCommands,
+) {
+  return ({ editor, range }: FormattingRunArgs) => {
+    const chain = editor.chain().focus();
+    if (range) chain.deleteRange(range);
+    apply(chain, editor).run();
+  };
+}
+
+/**
+ * Toggles a heading at the requested level. Tiptap's `toggleHeading` returns
+ * to a paragraph if the same level is already active, which matches the
+ * Notion-style "press H2 again to demote" expectation.
+ */
+function toggleHeading(level: 1 | 2 | 3) {
+  return runWithChain(chain => chain.toggleHeading({ level }));
+}
+
+/**
+ * Lightweight prompt-driven URL flow. Replace with a dedicated dialog when
+ * the design team ships one; until then this matches the historical
+ * `<RichTextToolbar>` link UX.
+ */
+function promptForLink({ editor, range }: FormattingRunArgs) {
+  const chain = editor.chain().focus();
+  if (range) chain.deleteRange(range);
+  chain.run();
+
+  const previousUrl = editor.getAttributes('link').href as string | undefined;
+  // eslint-disable-next-line no-alert -- interim until a dedicated link dialog ships.
+  const nextUrl = window.prompt('Enter a URL', previousUrl ?? '');
+  if (nextUrl == null) return;
+  if (nextUrl.trim() === '') {
+    editor.chain().focus().unsetLink().run();
+    return;
+  }
+  editor.chain().focus().setLink({ href: nextUrl.trim() }).run();
+}
+
+/**
+ * Default toolbar layout — 9 buttons split into block (H1-H3, bullet,
+ * numbered, blockquote) and inline (bold, italic, underline, link) groups.
+ * Order matters: `<FormattingToolbar>` reads it left-to-right and inserts a
+ * vertical divider whenever `group` changes.
+ */
+export const STANDARD_FORMATTING_COMMANDS: FormattingToolbarCommand[] = [
+  {
+    id: 'h1',
+    icon: Heading1,
+    label: 'Heading 1',
+    markdown: '#',
+    group: 'block',
+    isActive: editor => editor.isActive('heading', { level: 1 }),
+    run: toggleHeading(1),
+  },
+  {
+    id: 'h2',
+    icon: Heading2,
+    label: 'Heading 2',
+    markdown: '##',
+    group: 'block',
+    isActive: editor => editor.isActive('heading', { level: 2 }),
+    run: toggleHeading(2),
+  },
+  {
+    id: 'h3',
+    icon: Heading3,
+    label: 'Heading 3',
+    markdown: '###',
+    group: 'block',
+    isActive: editor => editor.isActive('heading', { level: 3 }),
+    run: toggleHeading(3),
+  },
+  {
+    id: 'bulletList',
+    icon: List,
+    label: 'Bulleted list',
+    markdown: '-',
+    group: 'block',
+    isActive: editor => editor.isActive('bulletList'),
+    run: runWithChain(chain => chain.toggleBulletList()),
+  },
+  {
+    id: 'orderedList',
+    icon: ListOrdered,
+    label: 'Numbered list',
+    markdown: '1.',
+    group: 'block',
+    isActive: editor => editor.isActive('orderedList'),
+    run: runWithChain(chain => chain.toggleOrderedList()),
+  },
+  {
+    id: 'blockquote',
+    icon: TextQuote,
+    label: 'Blockquote',
+    markdown: '>',
+    group: 'block',
+    isActive: editor => editor.isActive('blockquote'),
+    run: runWithChain(chain => chain.toggleBlockquote()),
+  },
+  {
+    id: 'bold',
+    icon: Bold,
+    label: 'Bold',
+    markdown: '⌘B',
+    group: 'inline',
+    isActive: editor => editor.isActive('bold'),
+    run: runWithChain(chain => chain.toggleBold()),
+  },
+  {
+    id: 'italic',
+    icon: Italic,
+    label: 'Italic',
+    markdown: '⌘I',
+    group: 'inline',
+    isActive: editor => editor.isActive('italic'),
+    run: runWithChain(chain => chain.toggleItalic()),
+  },
+  {
+    id: 'underline',
+    icon: UnderlineIcon,
+    label: 'Underline',
+    markdown: '⌘U',
+    group: 'inline',
+    isActive: editor => editor.isActive('underline'),
+    run: runWithChain(chain => chain.toggleUnderline()),
+  },
+  {
+    id: 'link',
+    icon: Link2,
+    label: 'Link',
+    markdown: '⌘K',
+    group: 'inline',
+    isActive: editor => editor.isActive('link'),
+    run: promptForLink,
+  },
+];
+
+/**
+ * Shorter set used when a consumer wants block-level affordances only (e.g.
+ * a comment composer where inline marks would feel out of place).
+ */
+export const BLOCKS_ONLY_FORMATTING_COMMANDS: FormattingToolbarCommand[] =
+  STANDARD_FORMATTING_COMMANDS.filter(c => c.group === 'block');
+
+export type FormattingToolbarVariant = 'standard' | 'blocksOnly' | 'none';
+
+export function resolveFormattingCommands(
+  variant: FormattingToolbarVariant,
+): FormattingToolbarCommand[] {
+  if (variant === 'none') return [];
+  if (variant === 'blocksOnly') return BLOCKS_ONLY_FORMATTING_COMMANDS;
+  return STANDARD_FORMATTING_COMMANDS;
+}

package/src/components/RichText/formattingTypes.ts

@@ -0,0 +1,34 @@
+import type { Editor, Range } from '@tiptap/react';
+import type { LucideIcon } from 'lucide-react';
+
+/**
+ * A single button in the canonical `FormattingToolbar`. The toolbar is
+ * shared by every rich-text surface in `@scalepad/ui`, so consumers
+ * configure their toolbar by passing an array of these descriptors —
+ * never by re-implementing the buttons themselves.
+ */
+export interface FormattingToolbarCommand {
+  id: string;
+  /** Lucide icon for the 26x26 button. */
+  icon: LucideIcon;
+  /** Used as `aria-label` and tooltip header. */
+  label: string;
+  /**
+   * Markdown shortcut shown in the tooltip pill (e.g. `##` for H2). When set,
+   * the same string is rendered to make the markdown path discoverable.
+   */
+  markdown?: string;
+  /** Visual group — used to break the toolbar into segments with dividers. */
+  group: 'block' | 'inline';
+  /**
+   * Returns true when the editor reports the matching node/mark as active so
+   * the button can render a "pressed" appearance.
+   */
+  isActive: (editor: Editor) => boolean;
+  /**
+   * Applies the formatting. Receives the editor and an optional range from a
+   * suggestion plugin so e.g. the slash token can be removed before the
+   * formatting is applied.
+   */
+  run: (ctx: { editor: Editor; range?: Range }) => void;
+}

package/src/components/RichText/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared rich-text foundation. Every editor + viewer in `@scalepad/ui`
+ * (RichTextEditor, SlashRichTextEditor, EditableRichText, RichTextView,
+ * RichTextInline) consumes this module so they all speak the same
+ * extension set, render the same toolbar, and share the same prose
+ * styling. Anything that's mode-specific (slash plugin, save/cancel
+ * chrome, debounced autosave) lives in the per-editor folder.
+ */
+export {
+  docsEqual,
+  isDocEmpty,
+  normalizeValue,
+  plainTextFromDoc,
+  richTextDocFromPlainText,
+} from './richTextHelpers';
+export {
+  getRichTextExtensions,
+  RICH_TEXT_FILE_ID_ATTRIBUTE,
+  RICH_TEXT_IMAGE_CLASS,
+  type GetRichTextExtensionsOptions,
+} from './richTextExtensions';
+export {
+  FormattingToolbar,
+  type FormattingToolbarProps,
+} from './FormattingToolbar';
+export {
+  STANDARD_FORMATTING_COMMANDS,
+  BLOCKS_ONLY_FORMATTING_COMMANDS,
+  resolveFormattingCommands,
+  type FormattingToolbarVariant,
+} from './formattingCommands';
+export type { FormattingToolbarCommand } from './formattingTypes';
+export {
+  DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES,
+  useRichTextImageUploader,
+} from './richTextImage';
+export type {
+  RichTextImageLoaderConfig,
+  RichTextImageLoaderHandle,
+  RichTextImageUploadConfig,
+  RichTextImageUploadError,
+  RichTextImageUploadResponse,
+  RichTextImageUploadResult,
+} from './richTextImage';
+export {
+  installRichTextImageHandlers,
+  useRichTextImageLoader,
+  type RichTextImageEditorConfig,
+} from './richTextImageHandlers';

package/src/components/RichText/richTextExtensions.ts

@@ -0,0 +1,111 @@
+import Image from '@tiptap/extension-image';
+import Link from '@tiptap/extension-link';
+import Placeholder from '@tiptap/extension-placeholder';
+import Underline from '@tiptap/extension-underline';
+import StarterKit from '@tiptap/starter-kit';
+
+import type { Extensions } from '@tiptap/react';
+
+/** Custom attribute that carries the consumer's stable file identifier on
+ * uploaded image nodes. We keep `src` empty on insert and resolve it lazily
+ * via {@link useRichTextImageLoader} so the editor doc itself only stores
+ * the file id, not the binary payload. */
+export const RICH_TEXT_FILE_ID_ATTRIBUTE = 'data-rich-text-file-id';
+
+/** Class applied to inserted image nodes so the loader hook can find them
+ * and so CSS can target loading / error states. */
+export const RICH_TEXT_IMAGE_CLASS = 'rich-text-image';
+
+export interface GetRichTextExtensionsOptions {
+  /** Placeholder text rendered when the document is empty. */
+  placeholder?: string;
+  /**
+   * When true (default), `Link.openOnClick` is false so users can place the
+   * caret inside a link without navigating away. View-mode callers (e.g.
+   * `RichTextView`) pass `false` so links are clickable on the rendered page.
+   */
+  editable?: boolean;
+  /**
+   * Heading levels enabled. Defaults to `[1, 2, 3]` to match the toolbar
+   * (H1/H2/H3 buttons) and the markdown shortcuts (`#`, `##`, `###`).
+   */
+  headingLevels?: Array<1 | 2 | 3 | 4 | 5 | 6>;
+  /**
+   * When true, the editor's schema includes an `image` node so docs
+   * authored elsewhere with images render correctly and uploads can be
+   * inserted at runtime. Defaults to `false` because most consumers don't
+   * need images and shipping the extension would otherwise bloat docs.
+   *
+   * Consumers that turn this on should also pass an `image` config to the
+   * editor component so paste / drop / toolbar flows can upload to their
+   * backend. The schema is shared regardless so a doc with images stays
+   * faithful when round-tripping through a read-only viewer.
+   */
+  enableImages?: boolean;
+}
+
+/**
+ * Returns the canonical Tiptap extension set used by every rich-text surface
+ * in `@scalepad/ui`. Centralising the configuration here is what guarantees
+ * that a doc typed in `SlashRichTextEditor` round-trips losslessly through
+ * `RichTextEditor`, `EditableRichText`, and `RichTextView` — they all share
+ * the same nodes, marks, and input rules.
+ *
+ * Editors that need additional behaviour (e.g. `SlashRichTextEditor`'s
+ * slash-suggestion plugin) append their extras after the result of this
+ * function rather than re-defining the base extensions inline.
+ */
+export function getRichTextExtensions({
+  placeholder,
+  editable = true,
+  headingLevels = [1, 2, 3],
+  enableImages = false,
+}: GetRichTextExtensionsOptions = {}): Extensions {
+  const extensions: Extensions = [
+    StarterKit.configure({
+      heading: { levels: headingLevels },
+    }),
+    Underline,
+    Link.configure({
+      openOnClick: !editable,
+      autolink: true,
+      HTMLAttributes: {
+        rel: 'noreferrer noopener',
+        target: '_blank',
+      },
+    }),
+    Placeholder.configure({
+      placeholder: placeholder ?? '',
+      emptyEditorClass: 'is-editor-empty',
+    }),
+  ];
+
+  if (enableImages) {
+    extensions.push(
+      Image.extend({
+        addAttributes() {
+          return {
+            ...this.parent?.(),
+            'data-rich-text-file-id': {
+              default: null,
+              parseHTML: element =>
+                element.getAttribute(RICH_TEXT_FILE_ID_ATTRIBUTE),
+              renderHTML: attrs => {
+                const fileId = attrs[RICH_TEXT_FILE_ID_ATTRIBUTE];
+                return fileId ? { [RICH_TEXT_FILE_ID_ATTRIBUTE]: fileId } : {};
+              },
+            },
+          };
+        },
+      }).configure({
+        inline: false,
+        allowBase64: true,
+        HTMLAttributes: {
+          class: RICH_TEXT_IMAGE_CLASS,
+        },
+      }),
+    );
+  }
+
+  return extensions;
+}