@scalepad/ui 0.1.0

package/src/components/EditableRichText/EditableRichText.tsx

@@ -0,0 +1,324 @@
+/**
+ * EditableRichText
+ *
+ * Inline-editable rich text field. Renders formatted Tiptap content that
+ * the user can click to focus and edit directly. Changes save live, with
+ * keystrokes debounced by `saveDebounceMs` (default 600ms). Focus leaving
+ * the component flushes any pending save immediately.
+ *
+ * Cmd/Ctrl+Z inside the editor triggers Tiptap's history, so users can
+ * revert their own edits within an active editing session. There is no
+ * explicit Save or Cancel button.
+ *
+ * External value prop changes (e.g. from optimistic-update reconciliation
+ * or a refetch) only apply when the editor does not currently have focus,
+ * so in-progress typing is never clobbered.
+ *
+ * When `required` is true and the user deletes all text, an inline error
+ * appears and no save is fired until they type again.
+ *
+ * Built on the canonical `RichText` foundation (shared extensions, shared
+ * `FormattingToolbar`) so a doc authored here renders identically in
+ * `RichTextView` and round-trips through `RichTextEditor` /
+ * `SlashRichTextEditor` without losing marks.
+ *
+ * @example
+ * <EditableRichText
+ *   value={summary}
+ *   ariaLabel="Executive summary"
+ *   label="Executive summary"
+ *   placeholder="Add an executive summary…"
+ *   onSave={next => mutation.mutateAsync({ executiveSummaryJson: JSON.stringify(next) })}
+ * />
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type FocusEvent,
+} from 'react';
+
+import { EditorContent, useEditor, type JSONContent } from '@tiptap/react';
+
+import { Button } from '../Button';
+import { STANDARD_FORMATTING_COMMANDS } from '../RichText/formattingCommands';
+import { FormattingToolbar } from '../RichText/FormattingToolbar';
+import { getRichTextExtensions } from '../RichText/richTextExtensions';
+import {
+  docsEqual,
+  isDocEmpty,
+  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 './EditableRichText.css';
+
+export interface EditableRichTextProps {
+  /** Document to render and edit. `null` is treated as empty. */
+  value: JSONContent | null;
+  /**
+   * Called (debounced) when the user edits. Called again immediately on
+   * blur to flush any pending edit. May return a Promise — a rejection
+   * is surfaced as an inline error with a Retry button.
+   */
+  onSave: (next: JSONContent) => void | Promise<void>;
+  /** Accessible label for the hidden plain-text textarea. Required. */
+  ariaLabel: string;
+  /** Visible-to-screen-reader label for the hidden plain-text textarea. */
+  label: string;
+  /** Shown (muted) over the editor when the document is empty and blurred. */
+  placeholder?: string;
+  /**
+   * When true, blocks saves (with an inline error) while the document is
+   * empty. As soon as the user types, the error clears and saves resume.
+   */
+  required?: boolean;
+  /** Error message shown when `required` fails. */
+  requiredMessage?: string;
+  /** When true, the field cannot be focused or edited. */
+  disabled?: boolean;
+  /** Debounce window for live save, in milliseconds. Defaults to 600. */
+  saveDebounceMs?: number;
+  /**
+   * When provided, enables inline image upload via paste / drop. See
+   * {@link RichTextImageEditorConfig} for the full callback surface and
+   * the rate-limit warning around `autoLoad`.
+   */
+  image?: RichTextImageEditorConfig;
+}
+
+interface PendingSave {
+  value: JSONContent;
+  timeoutId: ReturnType<typeof setTimeout>;
+}
+
+export function EditableRichText({
+  value,
+  onSave,
+  ariaLabel,
+  label,
+  placeholder,
+  required = false,
+  requiredMessage,
+  disabled = false,
+  saveDebounceMs = 600,
+  image,
+}: EditableRichTextProps) {
+  const normalizedValue = useMemo(() => normalizeValue(value), [value]);
+  const enableImages = Boolean(image);
+
+  const [isFocused, setIsFocused] = useState(false);
+  const [requiredError, setRequiredError] = useState<string | null>(null);
+  const [saveError, setSaveError] = useState<string | null>(null);
+
+  // Keep current `onSave`, `required`, and `requiredMessage` in refs so
+  // scheduled save callbacks always see the latest values without forcing
+  // the debounce machinery to reschedule.
+  const onSaveRef = useRef(onSave);
+  const requiredRef = useRef(required);
+  const requiredMessageRef = useRef(requiredMessage);
+  useEffect(() => {
+    onSaveRef.current = onSave;
+    requiredRef.current = required;
+    requiredMessageRef.current = requiredMessage;
+  });
+
+  const pendingRef = useRef<PendingSave | null>(null);
+  const lastSavedRef = useRef<JSONContent>(normalizedValue);
+
+  const commitSave = useCallback((next: JSONContent) => {
+    if (docsEqual(next, lastSavedRef.current)) {
+      return;
+    }
+
+    if (requiredRef.current && isDocEmpty(next)) {
+      setRequiredError(requiredMessageRef.current ?? 'This field is required');
+      return;
+    }
+
+    lastSavedRef.current = next;
+    setSaveError(null);
+
+    Promise.resolve(onSaveRef.current(next)).catch(err => {
+      setSaveError(err instanceof Error ? err.message : 'Unable to save');
+    });
+  }, []);
+
+  const flushPendingSave = useCallback(() => {
+    const pending = pendingRef.current;
+    if (!pending) {
+      return;
+    }
+    clearTimeout(pending.timeoutId);
+    pendingRef.current = null;
+    commitSave(pending.value);
+  }, [commitSave]);
+
+  const scheduleSave = useCallback(
+    (next: JSONContent) => {
+      if (pendingRef.current) {
+        clearTimeout(pendingRef.current.timeoutId);
+      }
+      const timeoutId = setTimeout(() => {
+        const pending = pendingRef.current;
+        pendingRef.current = null;
+        if (pending) {
+          commitSave(pending.value);
+        }
+      }, saveDebounceMs);
+      pendingRef.current = { value: next, timeoutId };
+    },
+    [commitSave, saveDebounceMs],
+  );
+
+  const editor = useEditor(
+    {
+      immediatelyRender: false,
+      editable: !disabled,
+      extensions: getRichTextExtensions({ enableImages }),
+      content: normalizedValue,
+      editorProps: installRichTextImageHandlers(image),
+      onUpdate: ({ editor: cur }) => {
+        const next = cur.getJSON();
+        if (requiredError) {
+          setRequiredError(null);
+        }
+        scheduleSave(next);
+      },
+    },
+    // 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);
+
+  // Flush pending save on unmount.
+  useEffect(() => {
+    return () => {
+      flushPendingSave();
+    };
+  }, [flushPendingSave]);
+
+  // Sync external value changes into the editor, but only when the editor
+  // doesn't have focus — so a mid-typing cache refetch never clobbers the
+  // user's in-progress edits.
+  useEffect(() => {
+    if (!editor) {
+      return;
+    }
+    if (editor.isFocused) {
+      return;
+    }
+    const current = editor.getJSON();
+    if (!docsEqual(current, normalizedValue)) {
+      editor.commands.setContent(normalizedValue, { emitUpdate: false });
+    }
+    lastSavedRef.current = normalizedValue;
+  }, [editor, normalizedValue]);
+
+  const handleContainerBlur = (event: FocusEvent<HTMLDivElement>) => {
+    const nextTarget = event.relatedTarget as Node | null;
+    if (event.currentTarget.contains(nextTarget)) {
+      return;
+    }
+    setIsFocused(false);
+    flushPendingSave();
+  };
+
+  const retry = () => {
+    if (!editor) return;
+    const current = editor.getJSON();
+    // Force a resend even if the document hasn't changed since last save.
+    lastSavedRef.current = { type: 'doc', content: [] };
+    commitSave(current);
+  };
+
+  if (!editor) {
+    return null;
+  }
+
+  const showPlaceholder =
+    placeholder != null && !isFocused && isDocEmpty(value);
+
+  const rootClasses = [
+    styles.root,
+    isFocused && !disabled ? styles.rootFocused : null,
+    disabled ? styles.rootDisabled : null,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div
+      className={rootClasses}
+      onFocusCapture={() => setIsFocused(true)}
+      onBlur={handleContainerBlur}
+      aria-disabled={disabled || undefined}
+    >
+      <textarea
+        aria-label={ariaLabel}
+        className={styles.srOnlyTextarea}
+        value={plainTextFromDoc(normalizedValue)}
+        onChange={(event: ChangeEvent<HTMLTextAreaElement>) => {
+          editor.commands.setContent(
+            richTextDocFromPlainText(event.target.value),
+            { emitUpdate: true },
+          );
+        }}
+        disabled={disabled}
+      />
+
+      {isFocused && !disabled && (
+        <FormattingToolbar
+          editor={editor}
+          commands={STANDARD_FORMATTING_COMMANDS}
+          className={styles.toolbar}
+          ariaLabel={`${label} formatting`}
+        />
+      )}
+
+      <div className={styles.contentWrapper}>
+        <div className={proseStyles.prose}>
+          <EditorContent editor={editor} aria-label={label} />
+        </div>
+        {showPlaceholder && (
+          <Text variant="body1" className={styles.placeholder} aria-hidden>
+            {placeholder}
+          </Text>
+        )}
+      </div>
+
+      {requiredError && (
+        <Text variant="caption1" c="text.danger.default">
+          {requiredError}
+        </Text>
+      )}
+
+      {saveError && (
+        <div className={styles.errorRow}>
+          <Text variant="caption1" c="text.danger.default">
+            {saveError}
+          </Text>
+          <Button type="button" size="xs" variant="outline" onClick={retry}>
+            Retry
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/EditableRichText/index.ts

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

package/src/components/EditableSelect/EditableSelect.css.ts

@@ -0,0 +1,62 @@
+import { style } from '@vanilla-extract/css';
+
+import { tokens } from '../../theme/themeContract.css';
+
+export const root = style({
+  display: 'inline-flex',
+  alignItems: 'center',
+  maxWidth: '100%',
+});
+
+export const displayButton = style({
+  all: 'unset',
+  boxSizing: 'border-box',
+  position: 'relative',
+  display: 'inline-flex',
+  alignItems: 'center',
+  maxWidth: '100%',
+  padding: '2px 22px 2px 6px',
+  margin: '-2px -6px',
+  background: 'transparent',
+  border: '1px solid transparent',
+  borderRadius: 'var(--radius-lg)',
+  cursor: 'text',
+  textAlign: 'left',
+  color: 'inherit',
+  font: 'inherit',
+  selectors: {
+    '&:hover:not(:disabled)': {
+      borderColor: tokens.color.stroke.subduedDefault,
+    },
+    '&:focus-visible:not(:disabled)': {
+      borderColor: tokens.color.stroke.focusDefault,
+    },
+    '&:disabled': {
+      cursor: 'default',
+    },
+  },
+});
+
+export const defaultLabel = style({
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+});
+
+export const pencilIcon = style({
+  position: 'absolute',
+  right: 6,
+  top: '50%',
+  transform: 'translateY(-50%)',
+  opacity: 0,
+  transition: 'opacity 120ms ease',
+  selectors: {
+    [`${displayButton}:hover:not(:disabled) &`]: {
+      opacity: 0.6,
+    },
+    [`${displayButton}:focus-visible:not(:disabled) &`]: {
+      opacity: 0.6,
+    },
+  },
+});

package/src/components/EditableSelect/EditableSelect.tsx

@@ -0,0 +1,224 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type MutableRefObject,
+  type ReactNode,
+  type Ref,
+} from 'react';
+
+import { Pencil } from 'lucide-react';
+
+import { Select } from '../Select';
+import { Text } from '../Typography';
+import * as styles from './EditableSelect.css';
+
+export interface EditableSelectProps {
+  value: string;
+  data: Array<{ value: string; label: string }>;
+  onSave: (value: string) => Promise<void>;
+  placeholder?: string;
+  disabled?: boolean;
+  renderDisplay?: (value: string, label: string) => ReactNode;
+}
+
+function assignRef<T>(ref: Ref<T> | undefined, value: T) {
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+
+  if (ref) {
+    (ref as MutableRefObject<T>).current = value;
+  }
+}
+
+export const EditableSelect = forwardRef<
+  HTMLButtonElement,
+  EditableSelectProps
+>(
+  (
+    {
+      value,
+      data,
+      onSave,
+      placeholder = 'Select',
+      disabled = false,
+      renderDisplay,
+    },
+    ref,
+  ) => {
+    const [isEditing, setIsEditing] = useState(false);
+    const [optimisticValue, setOptimisticValue] = useState<string | null>(null);
+
+    const rootRef = useRef<HTMLDivElement | null>(null);
+    const displayButtonRef = useRef<HTMLButtonElement | null>(null);
+    const selectButtonRef = useRef<HTMLButtonElement | null>(null);
+
+    const currentValue = optimisticValue ?? value;
+    const selectedOption = useMemo(
+      () => data.find(option => option.value === currentValue) ?? null,
+      [currentValue, data],
+    );
+    const selectedLabel = selectedOption?.label ?? currentValue;
+    const displayLabel = selectedLabel || placeholder;
+
+    const setDisplayRef = useCallback(
+      (node: HTMLButtonElement | null) => {
+        displayButtonRef.current = node;
+        if (node) {
+          assignRef(ref, node);
+        }
+      },
+      [ref],
+    );
+
+    const setSelectRef = useCallback(
+      (node: HTMLButtonElement | null) => {
+        selectButtonRef.current = node;
+        if (node) {
+          assignRef(ref, node);
+        }
+      },
+      [ref],
+    );
+
+    const stopEditing = useCallback(() => {
+      setIsEditing(false);
+    }, []);
+
+    const startEditing = useCallback(() => {
+      if (disabled || isEditing) {
+        return;
+      }
+
+      setIsEditing(true);
+    }, [disabled, isEditing]);
+
+    const cancel = useCallback(() => {
+      if (!isEditing) {
+        return;
+      }
+
+      stopEditing();
+    }, [isEditing, stopEditing]);
+
+    const commit = useCallback(
+      (nextValue: string) => {
+        if (nextValue === currentValue) {
+          stopEditing();
+          return;
+        }
+
+        setOptimisticValue(nextValue);
+        stopEditing();
+        Promise.resolve(onSave(nextValue)).catch(() => {
+          setOptimisticValue(null);
+        });
+      },
+      [currentValue, onSave, stopEditing],
+    );
+
+    useEffect(() => {
+      if (optimisticValue === value) {
+        setOptimisticValue(null);
+      }
+    }, [optimisticValue, value]);
+
+    useEffect(() => {
+      if (!isEditing) {
+        return;
+      }
+
+      const timer = window.setTimeout(() => {
+        selectButtonRef.current?.focus();
+        selectButtonRef.current?.click();
+      }, 0);
+
+      return () => window.clearTimeout(timer);
+    }, [isEditing]);
+
+    useEffect(() => {
+      if (!isEditing) {
+        return;
+      }
+
+      const handleMouseDown = (event: MouseEvent) => {
+        const target = event.target as HTMLElement | null;
+        const isWithinComboboxDropdown =
+          target?.closest('[role="listbox"]') != null ||
+          target?.closest('[role="option"]') != null;
+
+        if (isWithinComboboxDropdown) {
+          return;
+        }
+
+        if (!rootRef.current?.contains(target as Node)) {
+          cancel();
+        }
+      };
+
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key === 'Escape') {
+          event.preventDefault();
+          cancel();
+        }
+      };
+
+      document.addEventListener('mousedown', handleMouseDown, true);
+      document.addEventListener('keydown', handleKeyDown, true);
+
+      return () => {
+        document.removeEventListener('mousedown', handleMouseDown, true);
+        document.removeEventListener('keydown', handleKeyDown, true);
+      };
+    }, [cancel, isEditing]);
+
+    return (
+      <div ref={rootRef} className={styles.root}>
+        {isEditing ? (
+          <Select
+            ref={setSelectRef}
+            data={data}
+            value={currentValue}
+            onChange={nextValue => {
+              if (nextValue == null) {
+                cancel();
+                return;
+              }
+
+              commit(nextValue);
+            }}
+            placeholder={placeholder}
+          />
+        ) : (
+          <button
+            ref={setDisplayRef}
+            type="button"
+            onClick={startEditing}
+            disabled={disabled}
+            className={styles.displayButton}
+          >
+            {renderDisplay ? (
+              renderDisplay(currentValue, displayLabel)
+            ) : (
+              <Text
+                variant="body1"
+                c={selectedOption ? undefined : 'text.subdued.default'}
+                className={styles.defaultLabel}
+              >
+                {displayLabel}
+              </Text>
+            )}
+            <Pencil size={14} aria-hidden className={styles.pencilIcon} />
+          </button>
+        )}
+      </div>
+    );
+  },
+);
+
+EditableSelect.displayName = 'EditableSelect';

package/src/components/EditableSelect/index.ts

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