@scalepad/ui 0.1.0

package/src/components/RichText/richTextProse.css.ts

@@ -0,0 +1,261 @@
+import { globalStyle, style } from '@vanilla-extract/css';
+
+import { tokens } from '../../theme/themeContract.css';
+
+/**
+ * Shared prose styles for Tiptap / ProseMirror content. Applied by both
+ * `SlashRichTextEditor` (edit mode) and `RichTextView` (read-only mode)
+ * so the writing surface and the rendered view look pixel-identical.
+ *
+ * Tiptap wraps editable content in a `.ProseMirror` element and the
+ * read-only view renders the same HTML directly under the wrapper, so
+ * each rule below targets either path:
+ *
+ *   `${prose} h1` matches both the editor's
+ *   `<div class=prose><div class=ProseMirror><h1>` and the view's
+ *   `<div class=prose><h1>`.
+ */
+export const prose = style({
+  color: tokens.color.text.default,
+  fontSize: '0.875rem',
+  lineHeight: 1.5,
+});
+
+globalStyle(`${prose} [contenteditable="true"]`, {
+  outline: 'none',
+});
+
+globalStyle(`${prose} .ProseMirror`, {
+  outline: 'none',
+});
+
+/* Only the editable surface needs a tall click target — the read-only
+ * `RichTextView` shares the `.ProseMirror` wrapper but should hug its
+ * content so list rows and detail headers don't gain ~4rem of empty
+ * space under short rich-text descriptions. */
+globalStyle(`${prose} .ProseMirror[contenteditable="true"]`, {
+  minHeight: '4rem',
+});
+
+/* ──────────────────────────────────────────────────────────────────
+ * Block-level elements
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} p`, {
+  margin: 0,
+  lineHeight: 1.5,
+});
+
+globalStyle(`${prose} p + p`, {
+  marginTop: tokens.spacing['2xs'],
+});
+
+globalStyle(`${prose} h1, ${prose} h2, ${prose} h3`, {
+  margin: 0,
+  fontWeight: 700,
+  lineHeight: 1.3,
+});
+
+globalStyle(`${prose} h1`, {
+  fontSize: '1.25rem',
+});
+
+globalStyle(`${prose} h2`, {
+  fontSize: '1.125rem',
+});
+
+globalStyle(`${prose} h3`, {
+  fontSize: '1rem',
+});
+
+/* Headings that follow other content get a small top margin so they
+ * read as a new section. Matches the editor's writing rhythm. */
+globalStyle(`${prose} * + h1, ${prose} * + h2, ${prose} * + h3`, {
+  marginTop: tokens.spacing.xs,
+});
+
+/* ──────────────────────────────────────────────────────────────────
+ * Lists — `list-style-type` is required because Mantine's CSS reset
+ * strips it. Bullets/numbers must be explicit so they survive.
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} ul, ${prose} ol`, {
+  margin: 0,
+  paddingLeft: tokens.spacing.lg,
+});
+
+globalStyle(`${prose} ul`, {
+  listStyleType: 'disc',
+});
+
+globalStyle(`${prose} ol`, {
+  listStyleType: 'decimal',
+});
+
+globalStyle(`${prose} li`, {
+  margin: 0,
+  paddingLeft: tokens.spacing['3xs'],
+});
+
+globalStyle(`${prose} li + li`, {
+  marginTop: tokens.spacing['3xs'],
+});
+
+/* Tiptap wraps each list item's content in a `<p>` — collapse that
+ * paragraph's margin so list items don't gain a second baseline. */
+globalStyle(`${prose} li > p`, {
+  margin: 0,
+});
+
+/* Lists adjacent to body content need a touch of breathing room so
+ * the bullets don't bump up against a paragraph above them. */
+globalStyle(
+  `${prose} p + ul, ${prose} p + ol, ${prose} ul + p, ${prose} ol + p`,
+  {
+    marginTop: tokens.spacing['2xs'],
+  },
+);
+
+/* ──────────────────────────────────────────────────────────────────
+ * Blockquote, code, links
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} blockquote`, {
+  margin: 0,
+  paddingLeft: tokens.spacing.sm,
+  borderLeft: `2px solid ${tokens.color.stroke.subduedDefault}`,
+  color: tokens.color.text.subduedStrong,
+});
+
+globalStyle(`${prose} blockquote > p`, {
+  margin: 0,
+});
+
+globalStyle(`${prose} code`, {
+  fontFamily: 'var(--font-family-monospace)',
+  background: tokens.color.background.subduedLight,
+  padding: '0 4px',
+  borderRadius: tokens.radius.xs,
+  fontSize: '0.95em',
+});
+
+globalStyle(`${prose} pre`, {
+  margin: 0,
+  padding: tokens.spacing.sm,
+  borderRadius: tokens.radius.sm,
+  background: tokens.color.background.subduedLight,
+  overflow: 'auto',
+});
+
+globalStyle(`${prose} pre > code`, {
+  background: 'transparent',
+  padding: 0,
+  borderRadius: 0,
+  fontSize: '0.95em',
+});
+
+globalStyle(`${prose} a`, {
+  color: tokens.color.text.primaryDefault,
+  textDecoration: 'underline',
+});
+
+globalStyle(`${prose} hr`, {
+  margin: `${tokens.spacing.sm} 0`,
+  border: 'none',
+  borderTop: `1px solid ${tokens.color.stroke.subduedDefault}`,
+});
+
+/* ──────────────────────────────────────────────────────────────────
+ * Inline marks — these have browser defaults, but Mantine's reset can
+ * normalise them away. Re-state them so bold/italic/underline always
+ * survive the document round-trip.
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} strong, ${prose} b`, {
+  fontWeight: 700,
+});
+
+globalStyle(`${prose} em, ${prose} i`, {
+  fontStyle: 'italic',
+});
+
+globalStyle(`${prose} u`, {
+  textDecoration: 'underline',
+});
+
+globalStyle(`${prose} s, ${prose} del`, {
+  textDecoration: 'line-through',
+});
+
+/* ──────────────────────────────────────────────────────────────────
+ * Placeholder — Tiptap's `@tiptap/extension-placeholder` toggles
+ * `is-editor-empty` on the first child when the doc has no content.
+ * Editor-only behaviour, but lives here so the editor can drop its
+ * own duplicated copy.
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} .ProseMirror p.is-editor-empty:first-child::before`, {
+  content: 'attr(data-placeholder)',
+  color: tokens.color.text.subduedDefault,
+  pointerEvents: 'none',
+  height: 0,
+  float: 'left',
+});
+
+/* ──────────────────────────────────────────────────────────────────
+ * Read-only collapse — when the surface isn't editable (i.e.
+ * `RichTextView`), collapse runs of empty paragraphs so legacy docs
+ * (Beast's plain-text-to-JSON converter emits one `<p></p>` per
+ * `\n\n`) read as the user-intended content rather than as a wall of
+ * whitespace. The editor leaves them alone so the cursor still has a
+ * line to live on while typing.
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} .ProseMirror[contenteditable="false"] p:empty`, {
+  display: 'none',
+});
+
+/* `<p><br></p>` is the other empty-paragraph shape Tiptap can emit
+ * (used as a hard-break placeholder). Drop those too in read-only
+ * mode so the trailing line-height doesn't bloat the layout. */
+globalStyle(
+  `${prose} .ProseMirror[contenteditable="false"] p:has(> br:only-child)`,
+  {
+    display: 'none',
+  },
+);
+
+/* ──────────────────────────────────────────────────────────────────
+ * Image nodes — uploaded images sit in the doc with an empty `src`
+ * and a `data-rich-text-file-id` attribute until the lazy loader
+ * resolves them (see `useRichTextImageLoader`). The states below
+ * keep the placeholder readable while loading and give the layout a
+ * stable footprint so other content doesn't reflow as images come
+ * in.
+ * ────────────────────────────────────────────────────────────────── */
+
+globalStyle(`${prose} img.rich-text-image`, {
+  maxWidth: '100%',
+  height: 'auto',
+  borderRadius: tokens.radius.md,
+});
+
+globalStyle(
+  `${prose} img.rich-text-image[data-rich-text-image-state="loading"], ${prose} img.rich-text-image[data-rich-text-image-state="idle"]`,
+  {
+    minHeight: '4rem',
+    width: '100%',
+    backgroundColor: tokens.color.background.subduedLight,
+    border: `1px dashed ${tokens.color.stroke.subduedDefault}`,
+  },
+);
+
+globalStyle(
+  `${prose} img.rich-text-image[data-rich-text-image-state="error"]`,
+  {
+    minHeight: '4rem',
+    width: '100%',
+    backgroundColor: tokens.color.background.dangerLight,
+    border: `1px dashed ${tokens.color.stroke.dangerDefault}`,
+  },
+);

package/src/components/RichTextEditor/RichTextEditor.css.ts

@@ -0,0 +1,82 @@
+import { globalStyle, style } from '@vanilla-extract/css';
+
+import { tokens } from '../../theme/themeContract.css';
+
+// Prose styles (<p>, <ul>, <ol>, <a>) are in ../RichText/richTextProse.css.ts
+// so they can be shared by RichTextView and EditableRichText.
+
+export const root = style({
+  border: `1px solid ${tokens.color.stroke.default}`,
+  borderRadius: tokens.radius.lg,
+  background: tokens.color.background.input,
+  overflow: 'hidden',
+});
+
+export const toolbar = style({
+  display: 'flex',
+  alignItems: 'center',
+  gap: tokens.spacing.xs,
+  padding: tokens.spacing.sm,
+  borderBottom: `1px solid ${tokens.color.stroke.subduedDefault}`,
+  background: tokens.color.background.subduedUltralight,
+  flexWrap: 'wrap',
+});
+
+export const editor = style({
+  minHeight: '9.5rem',
+  padding: `${tokens.spacing.sm} ${tokens.spacing.md}`,
+  color: tokens.color.text.default,
+});
+
+export const actions = style({
+  display: 'flex',
+  justifyContent: 'space-between',
+  alignItems: 'flex-end',
+  gap: tokens.spacing.sm,
+  padding: tokens.spacing.sm,
+  borderTop: `1px solid ${tokens.color.stroke.subduedDefault}`,
+  background: tokens.color.background.default,
+  flexWrap: 'wrap',
+});
+
+export const actionMeta = style({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: tokens.spacing.xs,
+  minWidth: 0,
+});
+
+export const keyboardHint = style({
+  color: tokens.color.text.subduedDefault,
+});
+
+export const errorRow = style({
+  display: 'flex',
+  alignItems: 'center',
+  gap: tokens.spacing.sm,
+  flexWrap: 'wrap',
+});
+
+export const actionButtons = style({
+  display: 'flex',
+  alignItems: 'center',
+  gap: tokens.spacing.xs,
+});
+
+export const srOnlyTextarea = style({
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+});
+
+// Keep the modal-editor's taller empty-state minimum so single-line edits
+// still present a large, obvious input target.
+globalStyle(`${editor} [contenteditable="true"]`, {
+  minHeight: '7rem',
+});

package/src/components/RichTextEditor/RichTextEditor.tsx

@@ -0,0 +1,204 @@
+import { useEffect, useMemo, type ChangeEvent } from 'react';
+
+import { EditorContent, useEditor, type JSONContent } from '@tiptap/react';
+import { X } from 'lucide-react';
+
+import { Button } from '../Button';
+import { IconButton } from '../IconButton';
+import { STANDARD_FORMATTING_COMMANDS } from '../RichText/formattingCommands';
+import { FormattingToolbar } from '../RichText/FormattingToolbar';
+import { getRichTextExtensions } from '../RichText/richTextExtensions';
+import {
+  docsEqual,
+  normalizeValue,
+  plainTextFromDoc,
+  richTextDocFromPlainText,
+} from '../RichText/richTextHelpers';
+import {
+  installRichTextImageHandlers,
+  useRichTextImageLoader,
+  type RichTextImageEditorConfig,
+} from '../RichText/richTextImageHandlers';
+import * as proseStyles from '../RichText/richTextProse.css';
+import { Text } from '../Typography';
+import * as styles from './RichTextEditor.css';
+
+export interface RichTextEditorProps {
+  value: JSONContent | null;
+  onChange: (value: JSONContent, plainText: string) => void;
+  onSubmit: () => void;
+  onCancel: () => void;
+  label: string;
+  submitLabel?: string;
+  submitDisabled?: boolean;
+  cancelDisabled?: boolean;
+  submitLoading?: boolean;
+  submitError?: string | null;
+  onSubmitErrorRetry?: () => void;
+  submitErrorRetryDisabled?: boolean;
+  disabled?: boolean;
+  /**
+   * When provided, enables inline image upload via paste / drop. Pass
+   * `undefined` (the default) on surfaces where images shouldn't be
+   * allowed — the Image extension is omitted from the schema entirely so
+   * users can't even paste one. See
+   * {@link RichTextImageEditorConfig} for the full callback surface.
+   */
+  image?: RichTextImageEditorConfig;
+}
+
+/**
+ * Form-style rich-text editor with explicit Save / Cancel buttons,
+ * Cmd/Ctrl+Enter submit, Esc cancel, and a built-in submit-error row with
+ * retry. Built on the canonical `RichText` foundation (shared extensions,
+ * shared `FormattingToolbar`) so a doc authored here round-trips through
+ * `RichTextView` without losing marks.
+ */
+export function RichTextEditor({
+  value,
+  onChange,
+  onSubmit,
+  onCancel,
+  label,
+  submitLabel = 'Save',
+  submitDisabled = false,
+  cancelDisabled = false,
+  submitLoading = false,
+  submitError = null,
+  onSubmitErrorRetry,
+  submitErrorRetryDisabled = false,
+  disabled = false,
+  image,
+}: RichTextEditorProps) {
+  const normalizedValue = useMemo(() => normalizeValue(value), [value]);
+  const enableImages = Boolean(image);
+  const editor = useEditor(
+    {
+      immediatelyRender: false,
+      editable: !disabled,
+      extensions: getRichTextExtensions({ enableImages }),
+      content: normalizedValue,
+      editorProps: {
+        handleKeyDown: (_view, event) => {
+          if (event.key === 'Escape') {
+            event.preventDefault();
+            onCancel();
+            return true;
+          }
+
+          if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+            event.preventDefault();
+            if (!submitDisabled) {
+              onSubmit();
+            }
+            return true;
+          }
+
+          return false;
+        },
+        ...installRichTextImageHandlers(image),
+      },
+      onUpdate: ({ editor: currentEditor }) => {
+        onChange(currentEditor.getJSON(), currentEditor.getText());
+      },
+    },
+    // Remount when `disabled` changes (Tiptap doesn't have a runtime
+    // setter for `editable`) or when image-config presence toggles (the
+    // schema gains/loses the Image extension). The image callbacks
+    // themselves are captured at install time, so swapping them without
+    // toggling `enableImages` doesn't rebuild the editor.
+    [disabled, enableImages],
+  );
+
+  useRichTextImageLoader(editor, image);
+
+  useEffect(() => {
+    if (!editor) {
+      return;
+    }
+
+    const current = editor.getJSON();
+    if (!docsEqual(current, normalizedValue)) {
+      editor.commands.setContent(normalizedValue, { emitUpdate: false });
+    }
+  }, [editor, normalizedValue]);
+
+  if (!editor) {
+    return null;
+  }
+
+  return (
+    <div className={styles.root}>
+      <textarea
+        aria-label={label}
+        className={styles.srOnlyTextarea}
+        value={plainTextFromDoc(normalizedValue)}
+        onChange={(event: ChangeEvent<HTMLTextAreaElement>) => {
+          editor.commands.setContent(
+            richTextDocFromPlainText(event.target.value),
+            { emitUpdate: true },
+          );
+        }}
+        disabled={disabled}
+      />
+      <FormattingToolbar
+        editor={editor}
+        commands={STANDARD_FORMATTING_COMMANDS}
+        className={styles.toolbar}
+        ariaLabel={`${label} formatting`}
+      />
+
+      <div className={`${styles.editor} ${proseStyles.prose}`}>
+        <EditorContent editor={editor} />
+      </div>
+
+      <div className={styles.actions}>
+        <div className={styles.actionMeta}>
+          {submitError ? (
+            <div className={styles.errorRow}>
+              <Text variant="caption1" c="text.danger.default">
+                {submitError}
+              </Text>
+              {onSubmitErrorRetry ? (
+                <Button
+                  type="button"
+                  size="xs"
+                  variant="outline"
+                  onClick={onSubmitErrorRetry}
+                  disabled={submitErrorRetryDisabled}
+                >
+                  Retry
+                </Button>
+              ) : null}
+            </div>
+          ) : null}
+          <Text variant="caption1" className={styles.keyboardHint}>
+            Cmd/Ctrl+Enter to submit
+          </Text>
+        </div>
+        <div className={styles.actionButtons}>
+          <IconButton
+            type="button"
+            variant="ghost"
+            size="sm"
+            aria-label="Cancel"
+            onClick={onCancel}
+            disabled={cancelDisabled}
+          >
+            <X size={16} />
+          </IconButton>
+          <Button
+            type="button"
+            variant="primary"
+            size="xs"
+            onClick={onSubmit}
+            disabled={submitDisabled}
+            loading={submitLoading}
+          >
+            {submitLabel}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/RichTextEditor/index.ts

@@ -0,0 +1,2 @@
+export { RichTextEditor } from './RichTextEditor';
+export type { RichTextEditorProps } from './RichTextEditor';

package/src/components/RichTextView/RichTextView.css.ts

@@ -0,0 +1,11 @@
+import { style } from '@vanilla-extract/css';
+
+import { tokens } from '../../theme/themeContract.css';
+
+export const root = style({
+  color: tokens.color.text.default,
+});
+
+export const empty = style({
+  color: tokens.color.text.subduedDefault,
+});

package/src/components/RichTextView/RichTextView.tsx

@@ -0,0 +1,114 @@
+/**
+ * RichTextView
+ *
+ * Read-only renderer for Tiptap / ProseMirror `JSONContent`. Produces the
+ * same prose styling as `RichTextEditor` (via the shared prose class) so
+ * display and edit modes look identical.
+ *
+ * Renders a `placeholder` string in a muted style when the document is
+ * empty (no non-whitespace text). Pass `null` for `value` to render the
+ * placeholder.
+ *
+ * @example
+ * <RichTextView value={doc} placeholder="No summary yet." />
+ */
+
+import { useEffect, useMemo } from 'react';
+
+import { EditorContent, type JSONContent, useEditor } from '@tiptap/react';
+
+import { getRichTextExtensions } from '../RichText/richTextExtensions';
+import {
+  docsEqual,
+  isDocEmpty,
+  normalizeValue,
+} from '../RichText/richTextHelpers';
+import {
+  useRichTextImageLoader,
+  type RichTextImageEditorConfig,
+} from '../RichText/richTextImageHandlers';
+import * as proseStyles from '../RichText/richTextProse.css';
+import { Text } from '../Typography';
+import * as styles from './RichTextView.css';
+
+export interface RichTextViewProps {
+  /** Document to render. `null` is treated as empty. */
+  value: JSONContent | null;
+  /** Text shown (muted) when the document has no visible content. */
+  placeholder?: string;
+  /** Optional className for the outer wrapper. */
+  className?: string;
+  /**
+   * When provided, enables the Image node in the schema so docs that
+   * carry images render faithfully. Pass `loadImage` to resolve
+   * `data-rich-text-file-id`s into real `src`s; pass `autoLoad: false`
+   * (the default) on surfaces that render many viewers at once (e.g.
+   * Assessments) so they don't fan out one request per section. The
+   * returned `loadImages()` handle isn't exposed here — for explicit
+   * lazy-loading from this surface use `EditableRichText` or wrap your
+   * own observer that calls back into a shared loader.
+   */
+  image?: RichTextImageEditorConfig;
+}
+
+export function RichTextView({
+  value,
+  placeholder,
+  className,
+  image,
+}: RichTextViewProps) {
+  const normalizedValue = useMemo(() => normalizeValue(value), [value]);
+  const enableImages = Boolean(image);
+
+  const editor = useEditor(
+    {
+      immediatelyRender: false,
+      editable: false,
+      // `editable: false` flips Link.openOnClick on so anchor clicks navigate
+      // when rendered as a view. Same canonical extension set as every editor
+      // surface — that's what guarantees a doc renders identically here as it
+      // edits in `RichTextEditor`, `EditableRichText`, or `SlashRichTextEditor`.
+      extensions: getRichTextExtensions({ editable: false, enableImages }),
+      content: normalizedValue,
+    },
+    [enableImages],
+  );
+
+  useRichTextImageLoader(editor, image);
+
+  useEffect(() => {
+    if (!editor) {
+      return;
+    }
+
+    const current = editor.getJSON();
+    if (!docsEqual(current, normalizedValue)) {
+      editor.commands.setContent(normalizedValue, { emitUpdate: false });
+    }
+  }, [editor, normalizedValue]);
+
+  if (isDocEmpty(value) && placeholder) {
+    return (
+      <Text
+        variant="body1"
+        className={[styles.empty, className].filter(Boolean).join(' ')}
+      >
+        {placeholder}
+      </Text>
+    );
+  }
+
+  if (!editor) {
+    return null;
+  }
+
+  return (
+    <div
+      className={[styles.root, proseStyles.prose, className]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <EditorContent editor={editor} />
+    </div>
+  );
+}

package/src/components/RichTextView/index.ts

@@ -0,0 +1,2 @@
+export { RichTextView } from './RichTextView';
+export type { RichTextViewProps } from './RichTextView';