@bendyline/squisq-editor-react 1.3.0 → 1.5.0

package/src/EmojiPicker.tsx

@@ -0,0 +1,332 @@
+/**
+ * EmojiPicker
+ *
+ * Toolbar-anchored popover for inserting emoji. The user picks a
+ * category from a row of tabs along the top, sees a scrollable grid
+ * for that category, and can type into a search box to narrow across
+ * all categories at once. Click → `onSelect(char)` → caller is
+ * responsible for routing the character into the active editor.
+ *
+ * Keeps the data flat and the rendering simple: there's no fuzzy
+ * search, no recently-used persistence, no skin-tone modifiers — just
+ * a fast, predictable picker. We can layer those on later without
+ * changing the public surface.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { CSSProperties } from 'react';
+import { PICKER_CATEGORIES, searchPickerEntries } from './emojiData';
+import type { PickerEntry } from './emojiData';
+
+export interface EmojiPickerProps {
+  /** Whether the picker is visible. */
+  open: boolean;
+  /**
+   * Fired when the user picks an entry. Carries either an emoji glyph
+   * or a FontAwesome icon descriptor — the caller dispatches on
+   * `kind` to insert it into the active editor. The caller is also
+   * responsible for closing the popover.
+   */
+  onSelect: (entry: PickerEntry) => void;
+  /** Fired on Escape, click-outside, or selection so the caller can close. */
+  onClose: () => void;
+  /** Optional anchor element — used for click-outside detection. When the
+   *  popover is rendered inside the same container as the trigger, pointer
+   *  events on the trigger don't fire the outside handler. */
+  anchorRef?: React.RefObject<HTMLElement>;
+  /** Optional CSS class for the popover root. */
+  className?: string;
+  /** Optional inline style for the popover root (e.g. positioning). */
+  style?: CSSProperties;
+  /**
+   * Editor theme — `'light'` or `'dark'`. Drives the picker's color
+   * palette. Required for the picker to render correctly when portaled
+   * outside the editor shell, since CSS custom properties defined on
+   * the shell don't cascade to portal targets. Defaults to `'light'`.
+   */
+  theme?: 'light' | 'dark';
+}
+
+interface PickerPalette {
+  bg: string;
+  border: string;
+  inputBg: string;
+  text: string;
+  textMuted: string;
+  accent: string;
+  accentSoft: string;
+}
+
+const LIGHT_PALETTE: PickerPalette = {
+  bg: '#fff',
+  border: '#d4cdb5',
+  inputBg: '#fff',
+  text: '#1f2937',
+  textMuted: '#8a7a5a',
+  accent: '#8B6914',
+  accentSoft: '#f3eedb',
+};
+
+const DARK_PALETTE: PickerPalette = {
+  bg: '#1f2937',
+  border: '#4b5563',
+  inputBg: '#374151',
+  text: '#e5e7eb',
+  textMuted: '#9ca3af',
+  accent: '#fbbf24',
+  accentSoft: '#374151',
+};
+
+/** Default popover dimensions. The Toolbar reads these to position the
+ *  popover with viewport-aware clamping so it never gets clipped. */
+export const EMOJI_PICKER_WIDTH = 480;
+export const EMOJI_PICKER_MAX_HEIGHT = 560;
+
+function buildPopoverStyle(palette: PickerPalette): CSSProperties {
+  return {
+    position: 'absolute',
+    zIndex: 100,
+    background: palette.bg,
+    border: `1px solid ${palette.border}`,
+    borderRadius: 6,
+    // Dark mode needs a deeper shadow than the light palette uses,
+    // because the popover sits on a dark surface where a soft 15%
+    // shadow effectively disappears.
+    boxShadow:
+      palette === DARK_PALETTE ? '0 8px 32px rgba(0, 0, 0, 0.5)' : '0 6px 24px rgba(0, 0, 0, 0.15)',
+    color: palette.text,
+    width: EMOJI_PICKER_WIDTH,
+    maxWidth: '95vw',
+    maxHeight: EMOJI_PICKER_MAX_HEIGHT,
+    display: 'flex',
+    flexDirection: 'column',
+    overflow: 'hidden',
+  };
+}
+
+export function EmojiPicker({
+  open,
+  onSelect,
+  onClose,
+  anchorRef,
+  className,
+  style,
+  theme = 'light',
+}: EmojiPickerProps) {
+  const palette = theme === 'dark' ? DARK_PALETTE : LIGHT_PALETTE;
+  const [activeCategory, setActiveCategory] = useState<string>(PICKER_CATEGORIES[0].id);
+  const [query, setQuery] = useState('');
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+
+  // Focus the search box when the popover opens; reset query when it
+  // closes so the next open starts fresh.
+  useEffect(() => {
+    if (open) {
+      // Defer so the input is mounted.
+      const t = setTimeout(() => searchInputRef.current?.focus(), 0);
+      return () => clearTimeout(t);
+    }
+    setQuery('');
+    setActiveCategory(PICKER_CATEGORIES[0].id);
+    return undefined;
+  }, [open]);
+
+  // Close on outside click and Escape.
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (e: MouseEvent) => {
+      const target = e.target as Node | null;
+      if (!target) return;
+      if (popoverRef.current?.contains(target)) return;
+      if (anchorRef?.current?.contains(target)) return;
+      onClose();
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('mousedown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open, onClose, anchorRef]);
+
+  const visibleEntries = useMemo<PickerEntry[]>(() => {
+    if (query.trim()) return searchPickerEntries(query);
+    const cat = PICKER_CATEGORIES.find((c) => c.id === activeCategory);
+    return cat ? cat.entries : [];
+  }, [query, activeCategory]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      ref={popoverRef}
+      className={`squisq-emoji-picker ${className ?? ''}`}
+      data-theme={theme}
+      style={{ ...buildPopoverStyle(palette), ...style }}
+      role="dialog"
+      aria-label="Insert emoji"
+      data-testid="emoji-picker"
+    >
+      {/* Search */}
+      <div
+        style={{
+          padding: '8px 10px',
+          borderBottom: `1px solid ${palette.border}`,
+        }}
+      >
+        <input
+          ref={searchInputRef}
+          type="text"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Search emoji & icons…"
+          aria-label="Search emoji & icons"
+          style={{
+            width: '100%',
+            padding: '6px 8px',
+            fontSize: 13,
+            fontFamily: 'inherit',
+            border: `1px solid ${palette.border}`,
+            borderRadius: 4,
+            background: palette.inputBg,
+            color: palette.text,
+            boxSizing: 'border-box',
+          }}
+        />
+      </div>
+
+      {/* Category tabs — hidden when a search is active because the grid
+          collapses across categories.
+
+          Two-row grid layout: with 9 emoji buckets + 3 FA families we'd
+          otherwise need a horizontal scrollbar to fit them all in the
+          480px-wide picker, and the scrollbar visually obscures the
+          tabs themselves. A 6-column grid gives exactly two even rows
+          that always fit without scrolling. */}
+      {!query.trim() && (
+        <div
+          role="tablist"
+          aria-label="Emoji & icon categories"
+          style={{
+            display: 'grid',
+            gridTemplateColumns: 'repeat(6, 1fr)',
+            gap: 2,
+            padding: '4px 6px',
+            borderBottom: `1px solid ${palette.border}`,
+          }}
+        >
+          {PICKER_CATEGORIES.map((cat) => {
+            const active = cat.id === activeCategory;
+            return (
+              <button
+                key={cat.id}
+                type="button"
+                role="tab"
+                aria-selected={active}
+                aria-label={cat.label}
+                title={cat.label}
+                onClick={() => setActiveCategory(cat.id)}
+                style={{
+                  fontSize: 18,
+                  lineHeight: 1,
+                  padding: '6px 0',
+                  cursor: 'pointer',
+                  background: active ? palette.accentSoft : 'transparent',
+                  border: '1px solid transparent',
+                  borderBottom: active ? `2px solid ${palette.accent}` : '2px solid transparent',
+                  borderRadius: 4,
+                  color: palette.text,
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                }}
+              >
+                {cat.tab.kind === 'emoji' ? (
+                  cat.tab.char
+                ) : (
+                  <i className={`fa-${cat.tab.family} fa-${cat.tab.name}`} aria-hidden="true" />
+                )}
+              </button>
+            );
+          })}
+        </div>
+      )}
+
+      {/* Grid — grows to fill the picker. The wrapper's `maxHeight`
+          caps the popover overall (set on the root element above), so
+          the grid scrolls only when the content doesn't fit. With the
+          default sizing (480 wide × 560 tall, 10 columns) the common
+          categories fit without a scrollbar at all. */}
+      <div
+        style={{
+          padding: 6,
+          flex: 1,
+          minHeight: 0,
+          overflowY: 'auto',
+          display: 'grid',
+          gridTemplateColumns: 'repeat(10, 1fr)',
+          gap: 2,
+        }}
+      >
+        {visibleEntries.length === 0 ? (
+          <div
+            style={{
+              gridColumn: '1 / -1',
+              padding: '20px 8px',
+              textAlign: 'center',
+              color: palette.textMuted,
+              fontSize: 13,
+            }}
+          >
+            {query.trim() ? `No matches for "${query.trim()}"` : 'No entries'}
+          </div>
+        ) : (
+          visibleEntries.map((entry, idx) => {
+            const tooltip = entry.kind === 'emoji' ? entry.name : entry.label;
+            const key =
+              entry.kind === 'emoji' ? `e-${entry.char}-${idx}` : `i-${entry.token}-${idx}`;
+            return (
+              <button
+                key={key}
+                type="button"
+                title={tooltip}
+                aria-label={tooltip}
+                data-picker-kind={entry.kind}
+                onClick={() => onSelect(entry)}
+                style={{
+                  fontSize: 22,
+                  lineHeight: 1,
+                  padding: 4,
+                  background: 'transparent',
+                  border: '1px solid transparent',
+                  borderRadius: 4,
+                  cursor: 'pointer',
+                  color: palette.text,
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                }}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.background = palette.accentSoft;
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.background = 'transparent';
+                }}
+              >
+                {entry.kind === 'emoji' ? (
+                  entry.char
+                ) : (
+                  <i className={`fa-${entry.family} fa-${entry.name}`} aria-hidden="true" />
+                )}
+              </button>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+}

package/src/ImageEditor.tsx

@@ -0,0 +1,327 @@
+/**
+ * ImageEditor — top-level shell that wires together the toolbar,
+ * canvas surface, layers panel, and properties panel against an
+ * `ImageEditDoc` persisted in a sidecar `ContentContainer`.
+ *
+ * Hosts pass an already-scoped container (typically built with
+ * `scopeContainer(parent, basename + '_files')`). On first mount, if
+ * the sidecar has no `state.json`, the editor seeds it from
+ * `initialSrc` — the source bytes are copied to `assets/source.<ext>`
+ * so the doc is portable and round-trips through ZIP serialization.
+ *
+ * The export pipeline is `state.json` → SVG → raster blob via
+ * `exportImageEditDoc` from `@bendyline/squisq/imageEdit`.
+ */
+
+import { useCallback, useState } from 'react';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import { exportImageEditDoc, type ImageEditExportFormat } from '@bendyline/squisq/imageEdit';
+import type { SurfaceScheme, Theme } from '@bendyline/squisq/schemas';
+import { CanvasSurface } from './imageEditor/CanvasSurface.js';
+import { ImageVersionHistoryDropdown } from './imageEditor/ImageVersionHistoryDropdown.js';
+import { LayersPanel } from './imageEditor/LayersPanel.js';
+import { PropertiesPanel } from './imageEditor/PropertiesPanel.js';
+import { Toolbar } from './imageEditor/Toolbar.js';
+import { useImageEditor } from './imageEditor/useImageEditor.js';
+import { useImageEditorTokens } from './imageEditor/useImageEditorTokens.js';
+
+export interface ImageEditorProps {
+  /**
+   * Scoped sidecar container for this image — typically
+   * `scopeContainer(parent, basename + '_files')`.
+   */
+  filesContainer: ContentContainer;
+  /**
+   * Source URL used to seed `assets/source.<ext>` and layer 0 the
+   * first time the sidecar is opened. Ignored once `state.json` exists.
+   */
+  initialSrc?: string;
+  /** Override the state filename. Default: `state.json`. */
+  stateFilename?: string;
+  /** Enable version-history snapshots in `.versions/`. Default: `false`. */
+  allowVersioning?: boolean;
+  /** Auto-save idle delay (ms) for version snapshots. Default: `5000`. */
+  versioningAutoSaveIdleMs?: number;
+  /** Called after the user clicks Export and the blob is produced. */
+  onExport?: (blob: Blob, format: ImageEditExportFormat) => void;
+  /**
+   * What the toolbar's Save button does:
+   *  - `'flush'` (default): write `state.json` to the sidecar.
+   *  - `'export'`: rasterize the canvas in `saveFormat` and fire
+   *    {@link onExport} — the same code path the Export menu uses.
+   *    Hosts that want one-click "save and close" semantics use this.
+   */
+  saveBehavior?: 'flush' | 'export';
+  /** Format used when `saveBehavior === 'export'`. Default: `'png'`. */
+  saveFormat?: ImageEditExportFormat;
+  /** Override the Save button label. Default: `'Save'`. */
+  saveLabel?: string;
+  /** Override the Save button tooltip. */
+  saveTitle?: string;
+  /**
+   * Squisq Theme to color the editor chrome (toolbar, panels, controls).
+   * Defaults to `DEFAULT_THEME`. Combined with {@link surface} the same
+   * way `<JsonView>` and `<LinearDocView>` do.
+   */
+  theme?: Theme;
+  /**
+   * Surface scheme — `LIGHT_SURFACE`, `DARK_SURFACE`, an explicit
+   * `SurfaceScheme` object, or `'auto'` to track the user's OS
+   * `prefers-color-scheme`. When omitted, the theme's own background is
+   * used as-is.
+   */
+  surface?: SurfaceScheme | 'auto';
+  /** Optional className for the root element. */
+  className?: string;
+}
+
+export function ImageEditor(props: ImageEditorProps) {
+  const {
+    filesContainer,
+    initialSrc,
+    stateFilename,
+    allowVersioning,
+    versioningAutoSaveIdleMs,
+    onExport,
+    saveBehavior = 'flush',
+    saveFormat = 'png',
+    saveLabel,
+    saveTitle,
+    theme,
+    surface,
+    className,
+  } = props;
+
+  const tokens = useImageEditorTokens(theme, surface);
+
+  const { state, dispatch, flush, resolveAssetUrl, uploadAsset, versioning, ready, error } =
+    useImageEditor({
+      container: filesContainer,
+      initialSrc,
+      stateFilename,
+      allowVersioning,
+      versioningAutoSaveIdleMs,
+    });
+
+  // Bumped after every save/version write so the history popover
+  // re-lists without polling.
+  const [historyRefreshKey, setHistoryRefreshKey] = useState(0);
+
+  const handleExport = useCallback(
+    async (format: ImageEditExportFormat) => {
+      if (!state) return;
+      try {
+        const blob = await exportImageEditDoc(state.doc, filesContainer, { format });
+        if (onExport) {
+          onExport(blob, format);
+        } else {
+          // Default behavior: trigger a browser download.
+          const url = URL.createObjectURL(blob);
+          const a = document.createElement('a');
+          a.href = url;
+          a.download = `image.${format === 'jpeg' ? 'jpg' : format}`;
+          document.body.appendChild(a);
+          a.click();
+          document.body.removeChild(a);
+          URL.revokeObjectURL(url);
+        }
+      } catch (err: unknown) {
+        console.warn(
+          '[squisq-editor] image export failed:',
+          err instanceof Error ? err.message : err,
+        );
+      }
+    },
+    [state, filesContainer, onExport],
+  );
+
+  /**
+   * Save-and-close pipeline. Critical: we must `await flush()` *before*
+   * triggering the export, otherwise the parent modal may close (via the
+   * `onExport` chain) before the debounced state.json write fires —
+   * losing any layer/edit changes since the last debounce. We also save
+   * a version snapshot so the history dropdown captures the moment of
+   * save and the user can revert later.
+   */
+  const handleSaveAndClose = useCallback(async () => {
+    try {
+      await flush();
+      if (versioning) {
+        try {
+          await versioning.saveVersion();
+          setHistoryRefreshKey((k) => k + 1);
+        } catch (err: unknown) {
+          console.warn(
+            '[squisq-editor] image-edit save-version failed:',
+            err instanceof Error ? err.message : err,
+          );
+        }
+      }
+      await handleExport(saveFormat);
+    } catch (err: unknown) {
+      console.warn(
+        '[squisq-editor] image-edit save-and-close failed:',
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }, [flush, versioning, handleExport, saveFormat]);
+
+  /**
+   * Revert `state.json` (and the in-memory editor state) to a prior
+   * snapshot. We delegate to `versioning.revertToVersion` so the
+   * sidecar write happens through the same code path as direct API
+   * use, including a snapshot of the *current* state before overwrite
+   * — that way the user can undo a revert via the same dropdown.
+   */
+  const handleRevertToVersion = useCallback(
+    async (version: import('@bendyline/squisq/versions').Version) => {
+      if (!versioning) return;
+      // Cancel any pending debounced write so it can't clobber the
+      // reverted state.json after we replace it.
+      try {
+        await flush();
+      } catch {
+        /* swallow — best effort */
+      }
+      const result = await versioning.revertToVersion(version);
+      if (!result.reverted) return;
+      const doc = await versioning.readVersion(version);
+      if (doc) {
+        dispatch({ type: 'load', doc });
+        // Bump the history list so the just-saved \"pre-revert\"
+        // snapshot shows up in the dropdown.
+        setHistoryRefreshKey((k) => k + 1);
+      }
+    },
+    [dispatch, flush, versioning],
+  );
+
+  const handleCreateTextAt = useCallback(
+    (x: number, y: number) => {
+      dispatch({
+        type: 'add-layer',
+        layer: {
+          type: 'text',
+          name: 'Text',
+          position: { x: Math.round(x), y: Math.round(y), width: 240, height: 48 },
+          content: {
+            text: 'New text',
+            style: { fontSize: 32, color: '#111111', fontFamily: 'sans-serif' },
+          },
+        },
+      });
+      dispatch({ type: 'set-tool', tool: 'select' });
+    },
+    [dispatch],
+  );
+
+  const handleCreateShapeAt = useCallback(
+    (x: number, y: number) => {
+      dispatch({
+        type: 'add-layer',
+        layer: {
+          type: 'shape',
+          name: 'Rectangle',
+          position: {
+            x: Math.round(x - 60),
+            y: Math.round(y - 40),
+            width: 120,
+            height: 80,
+          },
+          content: {
+            shape: 'rect',
+            fill: '#3399ff',
+            stroke: '#1a4d80',
+            strokeWidth: 2,
+            borderRadius: 8,
+          },
+        },
+      });
+      dispatch({ type: 'set-tool', tool: 'select' });
+    },
+    [dispatch],
+  );
+
+  if (error) {
+    return (
+      <div
+        className={['squisq-image-editor', className].filter(Boolean).join(' ')}
+        style={tokens.style}
+      >
+        <div className="squisq-image-editor-error">
+          Failed to load image editor: {error.message}
+        </div>
+      </div>
+    );
+  }
+
+  if (!ready || !state) {
+    return (
+      <div
+        className={['squisq-image-editor', className].filter(Boolean).join(' ')}
+        style={tokens.style}
+      >
+        <div className="squisq-image-editor-loading">Loading image editor…</div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={['squisq-image-editor', className].filter(Boolean).join(' ')}
+      style={tokens.style}
+      data-testid="image-editor"
+    >
+      <Toolbar
+        doc={state.doc}
+        tool={state.tool}
+        dispatch={dispatch}
+        uploadAsset={uploadAsset}
+        onExport={handleExport}
+        onSave={saveBehavior === 'export' ? handleSaveAndClose : flush}
+        saveLabel={saveLabel ?? (saveBehavior === 'export' ? 'Save and close' : 'Save')}
+        saveTitle={
+          saveTitle ??
+          (saveBehavior === 'export'
+            ? `Rasterize and save as ${saveFormat.toUpperCase()}`
+            : 'Save state.json')
+        }
+        extraTools={
+          versioning ? (
+            <ImageVersionHistoryDropdown
+              versioning={versioning}
+              container={filesContainer}
+              onRevert={handleRevertToVersion}
+              refreshKey={historyRefreshKey}
+            />
+          ) : null
+        }
+      />
+      <div className="squisq-image-editor-body">
+        <div className="squisq-image-editor-center">
+          <CanvasSurface
+            doc={state.doc}
+            selectedLayerId={state.selectedLayerId}
+            tool={state.tool}
+            resolveAssetUrl={resolveAssetUrl}
+            dispatch={dispatch}
+            onCreateTextAt={handleCreateTextAt}
+            onCreateShapeAt={handleCreateShapeAt}
+          />
+        </div>
+        <div className="squisq-image-editor-side">
+          <LayersPanel
+            doc={state.doc}
+            selectedLayerId={state.selectedLayerId}
+            dispatch={dispatch}
+          />
+          <PropertiesPanel
+            doc={state.doc}
+            selectedLayerId={state.selectedLayerId}
+            dispatch={dispatch}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}