@bendyline/squisq-editor-react 1.5.2 → 1.6.0

package/src/customThemes/customThemeLibrary.ts

@@ -0,0 +1,97 @@
+/**
+ * Browser-local library of user-defined custom themes.
+ *
+ * The theme analog of `customTemplates/library.ts`. Library themes live in
+ * `localStorage` under `THEME_LIBRARY_STORAGE_KEY`. They're a cross-doc
+ * convenience — a personal collection the user reuses across documents — but
+ * they're NOT used by the SSR / export pipeline. When a user applies a library
+ * theme to a doc, `applyTheme` (in CustomThemeContext) copies the definition
+ * into the doc's `customThemes` so the doc remains self-sufficient (the
+ * markdown file ships with everything it needs), exactly as applying a library
+ * template copies it into `Doc.customTemplates`.
+ *
+ * Safe to import in SSR / Node — gracefully no-ops when `localStorage` is
+ * unavailable.
+ */
+
+import type { Theme } from '@bendyline/squisq/schemas';
+
+export const THEME_LIBRARY_STORAGE_KEY = 'squisq:custom-theme-library';
+
+interface LibraryPayload {
+  /** Schema version for forward-compatibility. */
+  version: 1;
+  themes: Theme[];
+}
+
+function safeStorage(): Storage | null {
+  try {
+    return typeof globalThis !== 'undefined' && globalThis.localStorage
+      ? globalThis.localStorage
+      : null;
+  } catch {
+    // Some browsers throw on localStorage access in private mode.
+    return null;
+  }
+}
+
+function readPayload(): LibraryPayload {
+  const storage = safeStorage();
+  if (!storage) return { version: 1, themes: [] };
+  const raw = storage.getItem(THEME_LIBRARY_STORAGE_KEY);
+  if (!raw) return { version: 1, themes: [] };
+  try {
+    const parsed = JSON.parse(raw) as Partial<LibraryPayload>;
+    if (parsed && Array.isArray(parsed.themes)) {
+      return { version: 1, themes: parsed.themes };
+    }
+  } catch {
+    // Corrupt payload — drop it.
+  }
+  return { version: 1, themes: [] };
+}
+
+function writePayload(payload: LibraryPayload): void {
+  const storage = safeStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(THEME_LIBRARY_STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Quota exceeded or storage disabled — best-effort write.
+  }
+}
+
+/** Return every theme currently in the user's library, sorted by name. */
+export function listLibraryThemes(): Theme[] {
+  const { themes } = readPayload();
+  return themes.slice().sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Insert or replace a library theme (matched by `id`). Returns the persisted
+ * list so callers can update their state without re-reading.
+ */
+export function saveLibraryTheme(theme: Theme): Theme[] {
+  const payload = readPayload();
+  const idx = payload.themes.findIndex((t) => t.id === theme.id);
+  if (idx >= 0) {
+    payload.themes[idx] = theme;
+  } else {
+    payload.themes.push(theme);
+  }
+  writePayload(payload);
+  return payload.themes.slice().sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Remove a library theme by id. Returns the updated list. */
+export function deleteLibraryTheme(id: string): Theme[] {
+  const payload = readPayload();
+  payload.themes = payload.themes.filter((t) => t.id !== id);
+  writePayload(payload);
+  return payload.themes.slice().sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Wipe the entire theme library — useful for tests and "reset" affordances. */
+export function clearThemeLibrary(): void {
+  writePayload({ version: 1, themes: [] });
+}

package/src/customThemes/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Public exports for the custom-theme designer + runtime — the theme analog
+ * of `customTemplates/index.ts`.
+ *
+ *   - `<CustomThemeProvider>` wraps the editor so the picker and dialog can
+ *     read/write doc + library theme lists.
+ *   - `<CustomThemeDialog>` is the modal designer opened from the ThemePicker's
+ *     "+ Create custom theme" affordance.
+ *   - the `*LibraryTheme` helpers back the browser-local theme library.
+ */
+
+export {
+  CustomThemeProvider,
+  useCustomThemes,
+  type CustomThemeContextValue,
+  type CustomThemeProviderProps,
+} from './CustomThemeContext';
+export {
+  listLibraryThemes,
+  saveLibraryTheme,
+  deleteLibraryTheme,
+  clearThemeLibrary,
+  THEME_LIBRARY_STORAGE_KEY,
+} from './customThemeLibrary';
+export { useDocCustomThemes, type DocCustomThemes } from './useDocCustomThemes';
+export {
+  CustomThemeDialog,
+  type CustomThemeDialogProps,
+  type ThemeSaveTarget,
+} from './CustomThemeDialog';
+export { compileDraft, themeToDraft, type Draft } from './themeDraft';

package/src/customThemes/themeControls.tsx

@@ -0,0 +1,229 @@
+/**
+ * themeControls — presentational form rows shared by the ThemeCustomizerPanel
+ * popover and the CustomThemeDialog. Pure/controlled; they carry the existing
+ * `squisq-theme-customizer-*` classes so both surfaces style identically.
+ */
+
+import { AVAILABLE_FONT_STACKS, isHex } from '@bendyline/squisq/schemas';
+import {
+  type CustomFontInput,
+  type FallbackOption,
+  type AccentInput,
+  FALLBACK_OPTIONS,
+  nextAccent,
+} from './themeDraft';
+
+export function Section({
+  title,
+  hint,
+  children,
+}: {
+  title: string;
+  hint?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="squisq-theme-customizer-section">
+      <div className="squisq-theme-customizer-section-title">{title}</div>
+      {hint && <div className="squisq-theme-customizer-section-hint">{hint}</div>}
+      <div className="squisq-theme-customizer-section-body">{children}</div>
+    </div>
+  );
+}
+
+export function SeedColorRow({
+  label,
+  value,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  onChange: (hex: string) => void;
+}) {
+  const safeValue = isHex(value) ? value : '#000000';
+  return (
+    <label className="squisq-theme-customizer-row">
+      <span className="squisq-theme-customizer-row-label">{label}</span>
+      <input
+        type="color"
+        className="squisq-theme-customizer-color"
+        value={safeValue}
+        onChange={(e) => onChange(e.target.value)}
+      />
+      <input
+        type="text"
+        className="squisq-theme-customizer-input squisq-theme-customizer-input--hex"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        spellCheck={false}
+        aria-label={`${label} hex value`}
+      />
+    </label>
+  );
+}
+
+export function FontPicker({
+  label,
+  value,
+  onChange,
+}: {
+  label: string;
+  value: CustomFontInput;
+  onChange: (next: CustomFontInput) => void;
+}) {
+  // Render the closed <select> (and each option) in the font it names, so the
+  // dropdown doubles as a live font preview. Faces are provided by the host
+  // (the site links `/fonts/fonts.css`; the same fonts the player renders
+  // with) — no external font fetch here. Unloaded faces fall back gracefully.
+  const selectedFamily =
+    value.kind === 'curated'
+      ? AVAILABLE_FONT_STACKS.find((s) => s.id === value.stackId)?.family
+      : undefined;
+
+  return (
+    <div className="squisq-theme-customizer-row squisq-theme-customizer-row--font">
+      <span className="squisq-theme-customizer-row-label">{label}</span>
+      <select
+        className="squisq-theme-customizer-input"
+        style={selectedFamily ? { fontFamily: selectedFamily } : undefined}
+        value={value.kind === 'custom' ? '__custom__' : (value.stackId ?? '')}
+        onChange={(e) => {
+          const v = e.target.value;
+          if (v === '__custom__') {
+            onChange({
+              kind: 'custom',
+              customName: value.customName ?? '',
+              customFallback: value.customFallback ?? 'sans-serif',
+            });
+          } else {
+            onChange({ kind: 'curated', stackId: v });
+          }
+        }}
+        aria-label={`${label} font`}
+      >
+        {AVAILABLE_FONT_STACKS.map((stack) => (
+          <option key={stack.id} value={stack.id} style={{ fontFamily: stack.family }}>
+            {stack.label}
+          </option>
+        ))}
+        <option value="__custom__">Custom…</option>
+      </select>
+      {value.kind === 'custom' && (
+        <>
+          <input
+            type="text"
+            className="squisq-theme-customizer-input"
+            placeholder="Font name"
+            value={value.customName ?? ''}
+            onChange={(e) => onChange({ ...value, customName: e.target.value })}
+            aria-label={`${label} custom font name`}
+          />
+          <select
+            className="squisq-theme-customizer-input"
+            value={value.customFallback ?? 'sans-serif'}
+            onChange={(e) =>
+              onChange({ ...value, customFallback: e.target.value as FallbackOption })
+            }
+            aria-label={`${label} custom font fallback`}
+          >
+            {FALLBACK_OPTIONS.map((opt) => (
+              <option key={opt} value={opt}>
+                {opt}
+              </option>
+            ))}
+          </select>
+        </>
+      )}
+    </div>
+  );
+}
+
+export function PresetRow<T extends string>({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string;
+  value: T;
+  options: readonly T[];
+  onChange: (v: T) => void;
+}) {
+  return (
+    <label className="squisq-theme-customizer-row">
+      <span className="squisq-theme-customizer-row-label">{label}</span>
+      <select
+        className="squisq-theme-customizer-input"
+        value={value}
+        onChange={(e) => onChange(e.target.value as T)}
+        aria-label={label}
+      >
+        {options.map((o) => (
+          <option key={o} value={o}>
+            {o}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}
+
+/**
+ * AccentEditor — the "N accent colors" list. Add / edit / remove accent
+ * colors; each maps to a per-block color scheme in the compiled theme.
+ */
+export function AccentEditor({
+  accents,
+  onChange,
+}: {
+  accents: AccentInput[];
+  onChange: (next: AccentInput[]) => void;
+}) {
+  const setColor = (idx: number, color: string) =>
+    onChange(accents.map((a, i) => (i === idx ? { ...a, color } : a)));
+  const remove = (idx: number) => onChange(accents.filter((_, i) => i !== idx));
+  const add = () => onChange([...accents, nextAccent(accents)]);
+
+  return (
+    <div className="squisq-theme-customizer-accents">
+      {accents.map((a, idx) => (
+        <div
+          key={a.key}
+          className="squisq-theme-customizer-row squisq-theme-customizer-row--accent"
+        >
+          <input
+            type="color"
+            className="squisq-theme-customizer-color"
+            value={isHex(a.color) ? a.color : '#000000'}
+            onChange={(e) => setColor(idx, e.target.value)}
+            aria-label={`Accent ${idx + 1}`}
+          />
+          <input
+            type="text"
+            className="squisq-theme-customizer-input squisq-theme-customizer-input--hex"
+            value={a.color}
+            onChange={(e) => setColor(idx, e.target.value)}
+            spellCheck={false}
+            aria-label={`Accent ${idx + 1} hex value`}
+          />
+          <button
+            type="button"
+            className="squisq-theme-customizer-accent-remove"
+            onClick={() => remove(idx)}
+            aria-label={`Remove accent ${idx + 1}`}
+            title="Remove accent"
+          >
+            ×
+          </button>
+        </div>
+      ))}
+      <button
+        type="button"
+        className="squisq-theme-customizer-button squisq-theme-customizer-accent-add"
+        onClick={add}
+      >
+        + Add accent
+      </button>
+    </div>
+  );
+}

package/src/customThemes/themeDraft.ts

@@ -0,0 +1,272 @@
+/**
+ * themeDraft — the editable subset of the Theme schema, shared by the
+ * ThemeCustomizerPanel popover and the CustomThemeDialog.
+ *
+ * A `Draft` mirrors the handful of fields a user actually edits (name, seed
+ * colors, N accents, fonts, style presets, and a base theme to inherit from).
+ * `compileDraft` turns it into a full validated `Theme` via `compileTheme`;
+ * everything the draft doesn't mention inherits from the chosen base (or the
+ * compiler's neutral STARTER_THEME when no base is picked).
+ */
+
+import type {
+  Theme,
+  FontFamily,
+  ThemeSeedColors,
+  ThemeColorScheme,
+} from '@bendyline/squisq/schemas';
+import { compileTheme, deriveScale, isHex } from '@bendyline/squisq/schemas';
+
+// ── Preset → schema-value tables ────────────────────────────────────
+
+export const BORDER_RADIUS_PRESETS = {
+  sharp: 0,
+  soft: 6,
+  rounded: 16,
+} as const;
+export type BorderRadiusPreset = keyof typeof BORDER_RADIUS_PRESETS;
+
+export const ANIMATION_SPEED_PRESETS = {
+  static: 0,
+  subtle: 1.4,
+  normal: 1.0,
+  expressive: 0.7,
+} as const;
+export type AnimationSpeedPreset = keyof typeof ANIMATION_SPEED_PRESETS;
+
+export const TEXT_SHADOW_PRESETS = {
+  off: false,
+  on: true,
+} as const;
+export type TextShadowPreset = keyof typeof TEXT_SHADOW_PRESETS;
+
+export const CONTRAST_PRESETS = ['subtle', 'balanced', 'high'] as const;
+export type ContrastPreset = (typeof CONTRAST_PRESETS)[number];
+
+export const IMAGE_TREATMENT_PRESETS = ['none', 'mono', 'duotone', 'warm', 'cool'] as const;
+export type ImageTreatmentPreset = (typeof IMAGE_TREATMENT_PRESETS)[number];
+
+export const FALLBACK_OPTIONS = ['sans-serif', 'serif', 'monospace', 'system-ui'] as const;
+export type FallbackOption = (typeof FALLBACK_OPTIONS)[number];
+
+// ── Draft state — reflects the editable subset of the schema ────────
+
+export interface CustomFontInput {
+  kind: 'curated' | 'custom';
+  stackId?: string;
+  customName?: string;
+  customFallback?: FallbackOption;
+}
+
+/** One editable accent: a color plus the colorScheme key it maps to. */
+export interface AccentInput {
+  key: string;
+  color: string;
+}
+
+export interface Draft {
+  name: string;
+  /** Id of the base theme this draft inherits render style / layout from. */
+  baseId?: string;
+  seeds: ThemeSeedColors;
+  /** The "N accents" — each becomes a `colorSchemes` entry. */
+  accents: AccentInput[];
+  /** True once the user has touched the accent list; gates wholesale replace. */
+  accentsEdited: boolean;
+  titleFont: CustomFontInput;
+  bodyFont: CustomFontInput;
+  borderRadius: BorderRadiusPreset;
+  animationSpeed: AnimationSpeedPreset;
+  textShadow: TextShadowPreset;
+  contrast: ContrastPreset;
+  imageTreatment: ImageTreatmentPreset;
+}
+
+export const DEFAULT_DRAFT: Draft = {
+  name: 'My Theme',
+  seeds: {
+    primary: '#3182ce',
+    secondary: '#4a5568',
+    accent: '#63b3ed',
+    background: '#1a202c',
+    text: '#f7fafc',
+  },
+  accents: [],
+  accentsEdited: false,
+  titleFont: { kind: 'curated', stackId: 'system-serif' },
+  bodyFont: { kind: 'curated', stackId: 'system-sans' },
+  borderRadius: 'soft',
+  animationSpeed: 'normal',
+  textShadow: 'on',
+  contrast: 'balanced',
+  imageTreatment: 'none',
+};
+
+function findRadiusPreset(value: number | undefined): BorderRadiusPreset {
+  if (value === undefined) return 'soft';
+  let best: BorderRadiusPreset = 'soft';
+  let bestDist = Infinity;
+  (Object.entries(BORDER_RADIUS_PRESETS) as [BorderRadiusPreset, number][]).forEach(([k, v]) => {
+    const d = Math.abs(v - value);
+    if (d < bestDist) {
+      best = k;
+      bestDist = d;
+    }
+  });
+  return best;
+}
+
+function findAnimationPreset(value: number | undefined): AnimationSpeedPreset {
+  if (value === undefined || value === 0) return value === 0 ? 'static' : 'normal';
+  let best: AnimationSpeedPreset = 'normal';
+  let bestDist = Infinity;
+  (Object.entries(ANIMATION_SPEED_PRESETS) as [AnimationSpeedPreset, number][]).forEach(
+    ([k, v]) => {
+      if (v === 0) return; // 'static' handled above
+      const d = Math.abs(v - value);
+      if (d < bestDist) {
+        best = k;
+        bestDist = d;
+      }
+    },
+  );
+  return best;
+}
+
+function fontFamilyToInput(f: FontFamily | undefined, fallbackStackId: string): CustomFontInput {
+  if (!f) return { kind: 'curated', stackId: fallbackStackId };
+  if ('stackId' in f) return { kind: 'curated', stackId: f.stackId };
+  if ('custom' in f)
+    return {
+      kind: 'custom',
+      customName: f.custom.name,
+      customFallback: f.custom.fallback,
+    };
+  return { kind: 'curated', stackId: fallbackStackId };
+}
+
+function inputToFontFamily(input: CustomFontInput): FontFamily {
+  if (input.kind === 'curated') {
+    return { stackId: input.stackId ?? 'system-sans' };
+  }
+  return {
+    custom: {
+      name: input.customName ?? 'Sans',
+      fallback: input.customFallback ?? 'sans-serif',
+    },
+  };
+}
+
+/** Read a theme's per-block color schemes back into the editable accent list. */
+export function accentsFromTheme(theme: Theme | null): AccentInput[] {
+  if (!theme) return [];
+  return Object.entries(theme.colorSchemes).map(([key, scheme]) => ({ key, color: scheme.accent }));
+}
+
+/**
+ * Expand one accent color into a full `{bg, text, accent}` color scheme via
+ * the OKLCh scale — dark saturated bg, light readable text, the picked accent.
+ * Falls back to a neutral scheme when the input isn't a valid hex.
+ */
+export function schemeFromAccent(accent: string): ThemeColorScheme {
+  if (!isHex(accent)) return { bg: '#1a202c', text: '#e2e8f0', accent: '#63b3ed' };
+  const scale = deriveScale(accent, 0.3);
+  return { bg: scale.darker2, text: scale.lighter2, accent: scale.base };
+}
+
+export function themeToDraft(theme: Theme | null): Draft {
+  if (!theme) return { ...DEFAULT_DRAFT };
+  const seeds: ThemeSeedColors = theme.seedColors ?? {
+    primary: theme.colors.primary,
+    secondary: theme.colors.secondary,
+    accent: theme.colors.highlight,
+    background: theme.colors.background,
+    text: theme.colors.text,
+  };
+  return {
+    name: theme.name,
+    baseId: theme.basedOn,
+    seeds: {
+      primary: seeds.primary,
+      secondary: seeds.secondary,
+      accent: seeds.accent,
+      background: seeds.background,
+      text: seeds.text,
+    },
+    accents: accentsFromTheme(theme),
+    // Populated for display, but NOT treated as authored by default: with
+    // `accentsEdited` false the compiled theme inherits the base's color
+    // schemes verbatim. The dialog flips this true when the user actually
+    // edits an accent (or when re-opening an existing custom theme, so its
+    // own accents survive a re-save). The popover panel never edits accents,
+    // so it always inherits — preserving its prior behavior.
+    accentsEdited: false,
+    titleFont: fontFamilyToInput(theme.typography.titleFont, 'system-serif'),
+    bodyFont: fontFamilyToInput(theme.typography.bodyFont, 'system-sans'),
+    borderRadius: findRadiusPreset(theme.style.borderRadius),
+    animationSpeed: findAnimationPreset(theme.style.animationSpeed),
+    textShadow: theme.style.textShadow === false ? 'off' : 'on',
+    contrast: 'balanced',
+    imageTreatment: theme.style.imageTreatment?.type ?? 'none',
+  };
+}
+
+export function slugify(s: string): string {
+  return (
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'custom'
+  );
+}
+
+export interface CompileDraftOptions {
+  /** Existing id to preserve across edits (keeps `squisq-theme` selection stable). */
+  existingId?: string;
+  /** Base theme to inherit render style / color schemes / typography from. */
+  base?: Theme;
+}
+
+/**
+ * Compile a `Draft` into a full validated `Theme`. Colors derive from the seed
+ * colors; the accent list (when edited) replaces `colorSchemes` wholesale; and
+ * everything else inherits from `opts.base` (or the neutral STARTER_THEME).
+ */
+export function compileDraft(draft: Draft, opts: CompileDraftOptions = {}): Theme {
+  const existingId = opts.existingId;
+  const id =
+    existingId && existingId.startsWith('custom-') ? existingId : `custom-${slugify(draft.name)}`;
+
+  const colorSchemes =
+    draft.accentsEdited && draft.accents.length > 0
+      ? Object.fromEntries(draft.accents.map((a) => [a.key, schemeFromAccent(a.color)]))
+      : undefined;
+
+  return compileTheme(
+    {
+      id,
+      name: draft.name,
+      seedColors: draft.seeds,
+      typography: {
+        titleFont: inputToFontFamily(draft.titleFont),
+        bodyFont: inputToFontFamily(draft.bodyFont),
+      },
+      style: {
+        borderRadius: BORDER_RADIUS_PRESETS[draft.borderRadius],
+        animationSpeed: ANIMATION_SPEED_PRESETS[draft.animationSpeed],
+        textShadow: TEXT_SHADOW_PRESETS[draft.textShadow],
+        ...(draft.imageTreatment !== 'none'
+          ? { imageTreatment: { type: draft.imageTreatment, strength: 0.5 } }
+          : {}),
+      },
+      ...(colorSchemes ? { colorSchemes } : {}),
+    },
+    { contrast: draft.contrast, base: opts.base },
+  );
+}
+
+/** Add a fresh accent slot with a sensible starting color. */
+export function nextAccent(accents: AccentInput[]): AccentInput {
+  const n = accents.length + 1;
+  return { key: `accent${n}`, color: '#63b3ed' };
+}

package/src/customThemes/useDocCustomThemes.ts

@@ -0,0 +1,49 @@
+/**
+ * useDocCustomThemes — read + persist the active doc's custom themes (the
+ * list inlined into the doc's frontmatter under `squisq-custom-themes`).
+ *
+ * The theme analog of `useDocCustomTemplates`. Both the CustomThemeProvider
+ * and any manager surface need the same two things: the current
+ * `Doc.customThemes` array and a way to write a new list back into the
+ * markdown source. Centralizing the frontmatter encoding here keeps call
+ * sites from drifting.
+ */
+
+import { useCallback, useMemo } from 'react';
+import type { Theme } from '@bendyline/squisq/schemas';
+import {
+  FRONTMATTER_CUSTOM_THEMES_KEY,
+  writeCustomThemesToFrontmatter,
+} from '@bendyline/squisq/doc';
+import { setFrontmatterValues } from '@bendyline/squisq/markdown';
+import { useEditorContext } from '../EditorContext';
+
+export interface DocCustomThemes {
+  /** Custom themes inlined in the active doc's frontmatter. */
+  docThemes: Theme[];
+  /**
+   * Persist a new custom-themes list back into the markdown source's
+   * frontmatter so the doc round-trips through save/load. The whole list is
+   * encoded as a single compact JSON string per the flat YAML frontmatter
+   * parser's constraint.
+   */
+  onDocThemesChange: (next: Theme[]) => void;
+}
+
+export function useDocCustomThemes(): DocCustomThemes {
+  const { doc, markdownSource, setMarkdownSource } = useEditorContext();
+  // Memoized so identity is stable across renders that don't touch
+  // frontmatter — keeps the CustomThemeProvider value stable.
+  const docThemes = useMemo<Theme[]>(() => doc?.customThemes ?? [], [doc?.customThemes]);
+  const onDocThemesChange = useCallback(
+    (next: Theme[]) => {
+      const payload = writeCustomThemesToFrontmatter(next);
+      const updated = setFrontmatterValues(markdownSource, {
+        [FRONTMATTER_CUSTOM_THEMES_KEY]: payload ?? null,
+      });
+      if (updated !== markdownSource) setMarkdownSource(updated);
+    },
+    [markdownSource, setMarkdownSource],
+  );
+  return { docThemes, onDocThemesChange };
+}