@bendyline/squisq-editor-react 1.5.2 → 1.6.0

package/src/customThemes/CustomThemeContext.tsx

@@ -0,0 +1,179 @@
+/**
+ * CustomThemeContext — exposes the merged set of doc-level + library custom
+ * themes to the rest of the editor (chiefly ThemePicker and CustomThemeDialog).
+ *
+ * The theme analog of CustomTemplateContext. The host wraps the editor in a
+ * provider, supplying:
+ *   - `docThemes`: the list currently sourced from the active doc's
+ *     frontmatter (read from `Doc.customThemes`).
+ *   - `onDocThemesChange`: a callback the host uses to persist a change back
+ *     into the doc (e.g. by updating the markdown source).
+ *
+ * Library themes come from `localStorage` via `customThemeLibrary.ts` and are
+ * managed entirely within the context — the host doesn't see them.
+ *
+ * `applyTheme(theme)` is the bridge between the two pools: when a user picks a
+ * library theme, we copy its definition into the doc's `customThemes` (if it
+ * isn't already there) so the doc remains self-sufficient for SSR / export.
+ * Selecting it as the active theme (writing `squisq-theme: <id>`) is a
+ * separate step the caller performs; this just ensures the doc-scoped resolve
+ * has the definition — exactly as `applyTemplate` seeds `Doc.customTemplates`.
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import type { Theme } from '@bendyline/squisq/schemas';
+import {
+  listLibraryThemes,
+  saveLibraryTheme as saveLibraryThemeRaw,
+  deleteLibraryTheme as deleteLibraryThemeRaw,
+} from './customThemeLibrary';
+
+export interface CustomThemeContextValue {
+  /** Themes inlined into the current doc's frontmatter. */
+  docThemes: Theme[];
+  /** Themes the user has saved to their browser-local library. */
+  libraryThemes: Theme[];
+  /**
+   * Convenience: the union of doc + library, with library entries skipped
+   * when a doc theme of the same id already exists. Used by the picker so a
+   * single "Custom" section covers both sources without duplicates.
+   */
+  allThemes: Theme[];
+
+  /**
+   * Persist a theme into the current doc. Replaces any existing entry with
+   * the same `id`. Triggers the host's `onDocThemesChange` so the doc's
+   * frontmatter ends up updated.
+   */
+  upsertDocTheme: (theme: Theme) => void;
+  /** Persist a theme into the user's library (replaces by id). */
+  upsertLibraryTheme: (theme: Theme) => void;
+  /** Remove a doc-level theme by id. */
+  removeDocTheme: (id: string) => void;
+  /** Remove a library theme by id. */
+  removeLibraryTheme: (id: string) => void;
+  /**
+   * Apply a theme to the current doc. If the theme is already in the doc,
+   * this is a no-op. If it's only in the library, it's copied into the doc
+   * so SSR / export work. Returns the resolved definition so callers can
+   * also write the `squisq-theme` selection.
+   */
+  applyTheme: (theme: Theme) => Theme;
+}
+
+const CustomThemeContext = createContext<CustomThemeContextValue | null>(null);
+
+export interface CustomThemeProviderProps {
+  /** The current doc's custom themes (from `Doc.customThemes`). */
+  docThemes: Theme[];
+  /**
+   * Callback the host uses to persist a new doc-theme list back into the doc
+   * (e.g. by writing the encoded payload into the markdown's
+   * `squisq-custom-themes` frontmatter key).
+   */
+  onDocThemesChange: (next: Theme[]) => void;
+  children: ReactNode;
+}
+
+export function CustomThemeProvider({
+  docThemes,
+  onDocThemesChange,
+  children,
+}: CustomThemeProviderProps) {
+  const [libraryThemes, setLibraryThemes] = useState<Theme[]>(() => listLibraryThemes());
+
+  // Re-read the library when this provider mounts so cross-tab edits (or
+  // initial first-paint quirks) are picked up. We don't subscribe to
+  // localStorage events in v1 — opening the picker re-renders and re-reads,
+  // which is enough for the single-tab common case.
+  useEffect(() => {
+    setLibraryThemes(listLibraryThemes());
+  }, []);
+
+  const upsertDocTheme = useCallback(
+    (theme: Theme) => {
+      const existingIdx = docThemes.findIndex((t) => t.id === theme.id);
+      const next =
+        existingIdx >= 0
+          ? docThemes.map((t, i) => (i === existingIdx ? theme : t))
+          : [...docThemes, theme];
+      onDocThemesChange(next);
+    },
+    [docThemes, onDocThemesChange],
+  );
+
+  const removeDocTheme = useCallback(
+    (id: string) => {
+      const next = docThemes.filter((t) => t.id !== id);
+      if (next.length !== docThemes.length) onDocThemesChange(next);
+    },
+    [docThemes, onDocThemesChange],
+  );
+
+  const upsertLibraryTheme = useCallback((theme: Theme) => {
+    setLibraryThemes(saveLibraryThemeRaw(theme));
+  }, []);
+
+  const removeLibraryTheme = useCallback((id: string) => {
+    setLibraryThemes(deleteLibraryThemeRaw(id));
+  }, []);
+
+  const applyTheme = useCallback(
+    (theme: Theme) => {
+      // If the doc already has this theme (matching id), leave both alone —
+      // the existing entry might be a customized copy.
+      const inDoc = docThemes.find((t) => t.id === theme.id);
+      if (!inDoc) upsertDocTheme(theme);
+      return inDoc ?? theme;
+    },
+    [docThemes, upsertDocTheme],
+  );
+
+  const allThemes = useMemo(() => {
+    const seen = new Set(docThemes.map((t) => t.id));
+    return [...docThemes, ...libraryThemes.filter((t) => !seen.has(t.id))];
+  }, [docThemes, libraryThemes]);
+
+  const value = useMemo<CustomThemeContextValue>(
+    () => ({
+      docThemes,
+      libraryThemes,
+      allThemes,
+      upsertDocTheme,
+      upsertLibraryTheme,
+      removeDocTheme,
+      removeLibraryTheme,
+      applyTheme,
+    }),
+    [
+      docThemes,
+      libraryThemes,
+      allThemes,
+      upsertDocTheme,
+      upsertLibraryTheme,
+      removeDocTheme,
+      removeLibraryTheme,
+      applyTheme,
+    ],
+  );
+
+  return <CustomThemeContext.Provider value={value}>{children}</CustomThemeContext.Provider>;
+}
+
+/**
+ * Hook returning the current context. Returns null when no provider is
+ * mounted — callers can degrade to "no custom themes" rather than throwing,
+ * since the feature is optional.
+ */
+// eslint-disable-next-line react-refresh/only-export-components -- hook is co-located with its provider by design, mirroring CustomTemplateContext
+export function useCustomThemes(): CustomThemeContextValue | null {
+  return useContext(CustomThemeContext);
+}

package/src/customThemes/CustomThemeDialog.tsx

@@ -0,0 +1,286 @@
+/**
+ * CustomThemeDialog
+ *
+ * Docked, **non-modal** theme designer pane — the theme analog of
+ * `TemplateDesigner`. Because applying theme properties (colors, fonts, …) is
+ * WYSIWYG, the designer docks into the editor's content row (below the
+ * toolbars, to the right of the preview) rather than covering the canvas with
+ * a modal; the preview shrinks to make room, so it stays fully visible and
+ * interactive while the user edits. `onChange` fires the compiled theme on
+ * every edit so the host can preview it via `PreviewSettingsProvider`'s
+ * `themeOverride`; the doc is only mutated on Save.
+ *
+ * The user picks a base theme to inherit render style / layout from, edits seed
+ * colors (primary / secondary / tertiary), an add/remove list of accent colors,
+ * fonts and style presets, and saves to the document or the browser-local
+ * library (`saveTarget: 'doc' | 'library'`).
+ *
+ * Rendered as a plain flex-item pane (a fixed-width, full-height column) — the
+ * host (`ThemeDesignerDock` inside `EditorShell`'s content row) places it as a
+ * sibling of the preview so the flexbox reflows the preview narrower.
+ *
+ * The editing model (draft + `compileDraft`) and the form rows are shared with
+ * the lighter `ThemeCustomizerPanel` popover via `themeDraft` + `themeControls`.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { Theme, ThemeSeedColors } from '@bendyline/squisq/schemas';
+import { resolveTheme } from '@bendyline/squisq/schemas';
+import { ThemePicker } from '../ThemePicker';
+import {
+  type Draft,
+  type AccentInput,
+  themeToDraft,
+  compileDraft,
+  accentsFromTheme,
+  BORDER_RADIUS_PRESETS,
+  ANIMATION_SPEED_PRESETS,
+  TEXT_SHADOW_PRESETS,
+  CONTRAST_PRESETS,
+  IMAGE_TREATMENT_PRESETS,
+  type BorderRadiusPreset,
+  type AnimationSpeedPreset,
+  type TextShadowPreset,
+  type ContrastPreset,
+  type ImageTreatmentPreset,
+} from './themeDraft';
+import { Section, SeedColorRow, FontPicker, PresetRow, AccentEditor } from './themeControls';
+
+/** Where a saved theme lands — mirrors `DesignerSaveTarget` for templates. */
+export type ThemeSaveTarget = 'doc' | 'library';
+
+export interface CustomThemeDialogProps {
+  /** Theme being edited, or null to author a new one. */
+  value: Theme | null;
+  /** Fired on every edit with the compiled theme (host previews via themeOverride). */
+  onChange?: (theme: Theme) => void;
+  /** Fired when the user saves, with the chosen target. */
+  onSave: (theme: Theme, target: ThemeSaveTarget) => void;
+  /** Dismiss (Cancel / Esc / close button). */
+  onClose: () => void;
+}
+
+function initialDraft(value: Theme | null): Draft {
+  const d = themeToDraft(value);
+  // Re-opening an existing custom theme: treat its accents as authored so a
+  // seed-only edit doesn't silently drop them back to the base's schemes.
+  if (value) d.accentsEdited = true;
+  return d;
+}
+
+export function CustomThemeDialog({ value, onChange, onSave, onClose }: CustomThemeDialogProps) {
+  const [draft, setDraft] = useState<Draft>(() => initialDraft(value));
+
+  const nameRef = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    nameRef.current?.focus();
+    nameRef.current?.select();
+  }, []);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [onClose]);
+
+  const compile = useCallback(
+    (d: Draft): Theme => {
+      const base = d.baseId ? resolveTheme(d.baseId) : undefined;
+      return compileDraft(d, { existingId: value?.id, base });
+    },
+    [value?.id],
+  );
+
+  const updateDraft = useCallback(
+    (patch: Partial<Draft> | ((d: Draft) => Draft)) => {
+      setDraft((prev) => {
+        const next = typeof patch === 'function' ? patch(prev) : { ...prev, ...patch };
+        try {
+          onChange?.(compile(next));
+        } catch {
+          // Invalid intermediate state (e.g. bad hex mid-typing) — skip preview.
+        }
+        return next;
+      });
+    },
+    [onChange, compile],
+  );
+
+  const updateSeed = useCallback(
+    (key: keyof ThemeSeedColors, hex: string) =>
+      updateDraft((d) => ({ ...d, seeds: { ...d.seeds, [key]: hex } })),
+    [updateDraft],
+  );
+
+  const handleSave = useCallback(
+    (target: ThemeSaveTarget) => {
+      try {
+        onSave(compile(draft), target);
+      } catch {
+        // A compile failure here means the draft is invalid; leave the dialog open.
+      }
+    },
+    [draft, onSave, compile],
+  );
+
+  // Accents show the base's schemes until the user edits them (then the draft's
+  // own list wins). Editing any accent flips `accentsEdited` so the compiled
+  // theme replaces `colorSchemes` wholesale.
+  const base = useMemo(() => (draft.baseId ? resolveTheme(draft.baseId) : null), [draft.baseId]);
+  const displayAccents: AccentInput[] = draft.accentsEdited
+    ? draft.accents
+    : accentsFromTheme(base);
+  const onAccentsChange = useCallback(
+    (next: AccentInput[]) => updateDraft({ accents: next, accentsEdited: true }),
+    [updateDraft],
+  );
+
+  return (
+    <div className="squisq-custom-theme-pane" role="dialog" aria-label="Design custom theme">
+      <div className="squisq-doc-settings-header">
+        <h2 className="squisq-doc-settings-title">
+          {value ? 'Edit custom theme' : 'New custom theme'}
+        </h2>
+        <button
+          type="button"
+          className="squisq-doc-settings-close"
+          onClick={onClose}
+          aria-label="Close"
+        >
+          &times;
+        </button>
+      </div>
+
+      <div className="squisq-doc-settings-body squisq-theme-customizer-body squisq-custom-theme-pane-body">
+        <Section title="Name">
+          <input
+            ref={nameRef}
+            type="text"
+            className="squisq-theme-customizer-input"
+            value={draft.name}
+            onChange={(e) => updateDraft({ name: e.target.value })}
+            aria-label="Theme name"
+          />
+        </Section>
+
+        <Section title="Base theme" hint="Inherit render style, motion, and layout from a base.">
+          <ThemePicker
+            value={draft.baseId ?? ''}
+            onChange={(id) => updateDraft({ baseId: id || undefined })}
+            includeDefault
+            variant="full"
+            ariaLabel="Base theme"
+          />
+        </Section>
+
+        <Section
+          title="Colors"
+          hint="Primary, secondary, and tertiary (accent). The rest is derived."
+        >
+          <SeedColorRow
+            label="Primary"
+            value={draft.seeds.primary}
+            onChange={(v) => updateSeed('primary', v)}
+          />
+          <SeedColorRow
+            label="Secondary"
+            value={draft.seeds.secondary ?? ''}
+            onChange={(v) => updateSeed('secondary', v)}
+          />
+          <SeedColorRow
+            label="Tertiary"
+            value={draft.seeds.accent ?? ''}
+            onChange={(v) => updateSeed('accent', v)}
+          />
+          <SeedColorRow
+            label="Background"
+            value={draft.seeds.background ?? ''}
+            onChange={(v) => updateSeed('background', v)}
+          />
+          <SeedColorRow
+            label="Text"
+            value={draft.seeds.text ?? ''}
+            onChange={(v) => updateSeed('text', v)}
+          />
+        </Section>
+
+        <Section title="Accents" hint="Per-block accent colors. Add as many as you like.">
+          <AccentEditor accents={displayAccents} onChange={onAccentsChange} />
+        </Section>
+
+        <Section title="Typography">
+          <FontPicker
+            label="Heading"
+            value={draft.titleFont}
+            onChange={(next) => updateDraft({ titleFont: next })}
+          />
+          <FontPicker
+            label="Body"
+            value={draft.bodyFont}
+            onChange={(next) => updateDraft({ bodyFont: next })}
+          />
+        </Section>
+
+        <Section title="Style">
+          <PresetRow
+            label="Border radius"
+            value={draft.borderRadius}
+            options={Object.keys(BORDER_RADIUS_PRESETS) as BorderRadiusPreset[]}
+            onChange={(v) => updateDraft({ borderRadius: v })}
+          />
+          <PresetRow
+            label="Animation"
+            value={draft.animationSpeed}
+            options={Object.keys(ANIMATION_SPEED_PRESETS) as AnimationSpeedPreset[]}
+            onChange={(v) => updateDraft({ animationSpeed: v })}
+          />
+          <PresetRow
+            label="Text shadow"
+            value={draft.textShadow}
+            options={Object.keys(TEXT_SHADOW_PRESETS) as TextShadowPreset[]}
+            onChange={(v) => updateDraft({ textShadow: v })}
+          />
+          <PresetRow
+            label="Contrast"
+            value={draft.contrast}
+            options={CONTRAST_PRESETS as readonly ContrastPreset[]}
+            onChange={(v) => updateDraft({ contrast: v })}
+          />
+          <PresetRow
+            label="Image grade"
+            value={draft.imageTreatment}
+            options={IMAGE_TREATMENT_PRESETS as readonly ImageTreatmentPreset[]}
+            onChange={(v) => updateDraft({ imageTreatment: v })}
+          />
+        </Section>
+      </div>
+
+      <div className="squisq-doc-settings-footer squisq-custom-theme-pane-footer">
+        <button
+          type="button"
+          className="squisq-doc-settings-btn squisq-doc-settings-btn--secondary"
+          onClick={onClose}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="squisq-doc-settings-btn squisq-doc-settings-btn--secondary"
+          onClick={() => handleSave('library')}
+          title="Save to your browser-local library so other docs can use it"
+        >
+          Save to library
+        </button>
+        <button
+          type="button"
+          className="squisq-doc-settings-btn squisq-doc-settings-btn--primary"
+          onClick={() => handleSave('doc')}
+        >
+          Save to document
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/customThemes/__tests__/CustomThemeContext.test.tsx

@@ -0,0 +1,64 @@
+/**
+ * CustomThemeContext — dual-catalog (doc + library) behavior, mirroring the
+ * custom-templates context: merged `allThemes`, doc/library upserts, and
+ * `applyTheme` copying a library theme into the doc for self-sufficiency.
+ */
+
+// @vitest-environment jsdom
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { CustomThemeProvider, useCustomThemes } from '../CustomThemeContext';
+import { clearThemeLibrary, saveLibraryTheme } from '../customThemeLibrary';
+import { compileTheme } from '@bendyline/squisq/schemas';
+import type { Theme } from '@bendyline/squisq/schemas';
+
+const t = (id: string, name = id): Theme =>
+  compileTheme({ id, name, seedColors: { primary: '#3182ce' } });
+
+function makeWrapper(docThemes: Theme[], onDocThemesChange = vi.fn()) {
+  return ({ children }: { children: ReactNode }) => (
+    <CustomThemeProvider docThemes={docThemes} onDocThemesChange={onDocThemesChange}>
+      {children}
+    </CustomThemeProvider>
+  );
+}
+
+describe('CustomThemeContext', () => {
+  beforeEach(() => clearThemeLibrary());
+
+  it('allThemes merges doc + library, doc wins on id clash', () => {
+    saveLibraryTheme(t('lib', 'Library'));
+    saveLibraryTheme(t('shared', 'Library Shared'));
+    const { result } = renderHook(() => useCustomThemes(), {
+      wrapper: makeWrapper([t('shared', 'Doc Shared')]),
+    });
+    expect(result.current!.allThemes.map((x) => x.id).sort()).toEqual(['lib', 'shared']);
+    expect(result.current!.allThemes.find((x) => x.id === 'shared')!.name).toBe('Doc Shared');
+  });
+
+  it('upsertDocTheme calls onDocThemesChange with the appended list', () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useCustomThemes(), { wrapper: makeWrapper([], onChange) });
+    act(() => result.current!.upsertDocTheme(t('a')));
+    expect(onChange).toHaveBeenCalledWith([expect.objectContaining({ id: 'a' })]);
+  });
+
+  it('applyTheme copies a library theme into the doc', () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useCustomThemes(), { wrapper: makeWrapper([], onChange) });
+    act(() => result.current!.applyTheme(t('lib')));
+    expect(onChange).toHaveBeenCalledWith([expect.objectContaining({ id: 'lib' })]);
+  });
+
+  it('applyTheme is a no-op when the theme is already in the doc', () => {
+    const onChange = vi.fn();
+    const inDoc = t('a');
+    const { result } = renderHook(() => useCustomThemes(), {
+      wrapper: makeWrapper([inDoc], onChange),
+    });
+    act(() => result.current!.applyTheme(inDoc));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

package/src/customThemes/__tests__/CustomThemeDialog.test.tsx

@@ -0,0 +1,47 @@
+/**
+ * CustomThemeDialog — the designer modal. Verifies live-preview `onChange`,
+ * the two save targets, and that adding an accent yields `colorSchemes`.
+ */
+
+// @vitest-environment jsdom
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { CustomThemeDialog } from '../CustomThemeDialog';
+
+describe('CustomThemeDialog', () => {
+  it('edits the name, previews live, and saves a compiled theme to the document', () => {
+    const onSave = vi.fn();
+    const onChange = vi.fn();
+    render(
+      <CustomThemeDialog value={null} onChange={onChange} onSave={onSave} onClose={() => {}} />,
+    );
+
+    fireEvent.change(screen.getByLabelText('Theme name'), { target: { value: 'Brandy' } });
+    expect(onChange).toHaveBeenCalled(); // live preview fired
+
+    fireEvent.click(screen.getByText('Save to document'));
+    expect(onSave).toHaveBeenCalledTimes(1);
+    const [theme, target] = onSave.mock.calls[0];
+    expect(target).toBe('doc');
+    expect(theme.name).toBe('Brandy');
+    expect(theme.schemaVersion).toBe('1');
+    expect(theme.id).toMatch(/^custom-/);
+  });
+
+  it('saves to the library via the library button', () => {
+    const onSave = vi.fn();
+    render(<CustomThemeDialog value={null} onSave={onSave} onClose={() => {}} />);
+    fireEvent.click(screen.getByText('Save to library'));
+    expect(onSave.mock.calls[0][1]).toBe('library');
+  });
+
+  it('adding an accent produces colorSchemes in the compiled theme', () => {
+    const onSave = vi.fn();
+    render(<CustomThemeDialog value={null} onSave={onSave} onClose={() => {}} />);
+    fireEvent.click(screen.getByText('+ Add accent'));
+    fireEvent.click(screen.getByText('Save to document'));
+    const theme = onSave.mock.calls[0][0];
+    expect(Object.keys(theme.colorSchemes).length).toBeGreaterThan(0);
+  });
+});

package/src/customThemes/__tests__/customThemeLibrary.test.ts

@@ -0,0 +1,51 @@
+/**
+ * customThemeLibrary — localStorage-backed library of user-defined themes.
+ * The theme analog of customTemplates' library test. Uses jsdom's localStorage.
+ */
+
+// @vitest-environment jsdom
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  listLibraryThemes,
+  saveLibraryTheme,
+  deleteLibraryTheme,
+  clearThemeLibrary,
+} from '../customThemeLibrary';
+import { compileTheme } from '@bendyline/squisq/schemas';
+import type { Theme } from '@bendyline/squisq/schemas';
+
+function theme(id: string, name = id): Theme {
+  return compileTheme({ id, name, seedColors: { primary: '#3182ce' } });
+}
+
+describe('customThemeLibrary', () => {
+  beforeEach(() => clearThemeLibrary());
+
+  it('save → list round-trips, sorted by name', () => {
+    saveLibraryTheme(theme('b', 'Beta'));
+    saveLibraryTheme(theme('a', 'Alpha'));
+    expect(listLibraryThemes().map((t) => t.name)).toEqual(['Alpha', 'Beta']);
+  });
+
+  it('save replaces by id', () => {
+    saveLibraryTheme(theme('a', 'Alpha'));
+    saveLibraryTheme(theme('a', 'Alpha 2'));
+    const list = listLibraryThemes();
+    expect(list).toHaveLength(1);
+    expect(list[0].name).toBe('Alpha 2');
+  });
+
+  it('delete removes by id', () => {
+    saveLibraryTheme(theme('a'));
+    saveLibraryTheme(theme('b'));
+    deleteLibraryTheme('a');
+    expect(listLibraryThemes().map((t) => t.id)).toEqual(['b']);
+  });
+
+  it('clear empties the library', () => {
+    saveLibraryTheme(theme('a'));
+    clearThemeLibrary();
+    expect(listLibraryThemes()).toEqual([]);
+  });
+});