@bendyline/squisq-editor-react 2.2.0 → 2.3.0

package/dist/image-editor/index.d.ts

@@ -0,0 +1,223 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { ImageEditExportFormat, ImageEditVersionManager } from '@bendyline/squisq/imageEdit';
+import { Theme, SurfaceScheme, ImageEditDoc, ImageEditLayer } from '@bendyline/squisq/schemas';
+import { ResourcePolicy } from '@bendyline/squisq/markdown';
+
+/**
+ * ImageViewer
+ *
+ * Read-only image viewer used when EditorShell runs in `image` file mode
+ * (PNG/JPEG/etc.). Renders a centered image that fits its container with
+ * a small overlay toolbar for fit / 100% / zoom in / zoom out, and a
+ * status row showing intrinsic dimensions and current zoom.
+ *
+ * Lifecycle of the `src` URL is the caller's responsibility — when fed a
+ * blob URL, the host should `URL.revokeObjectURL` on unmount or src change.
+ *
+ * Future image-editing actions (rotate, flip, crop) will slot in alongside
+ * the existing zoom controls.
+ */
+interface ImageViewerProps {
+    /** Image source — typically a blob: URL the host owns and revokes. */
+    src: string;
+    /** Alt text for accessibility. Defaults to empty string (decorative). */
+    alt?: string;
+    /** Additional class name on the outer container. */
+    className?: string;
+    /** Color theme for the chrome around the image. */
+    theme?: 'light' | 'dark';
+}
+declare function ImageViewer({ src, alt, className, theme }: ImageViewerProps): react_jsx_runtime.JSX.Element;
+
+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;
+}
+declare function ImageEditor(props: ImageEditorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure state + reducer for the `<ImageEditor>` component.
+ *
+ * Kept React-free so it's easy to unit-test in isolation. The actual
+ * React hook that wires this to a {@link ContentContainer} (and the
+ * version manager) lives in `useImageEditor.ts`.
+ */
+
+type DOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * Layer payload accepted by the `add-layer` action — the `id` field is
+ * optional and will be assigned by the underlying `addLayer` helper if
+ * the caller doesn't supply one.
+ */
+type ImageEditLayerInput = ImageEditLayer | (DOmit<ImageEditLayer, 'id'> & {
+    id?: string;
+});
+/** The currently active interaction tool. */
+type ImageEditorTool = 'select' | 'text' | 'shape' | 'image' | 'crop' | 'zoom-rect';
+/** A pixel-space rectangle in canvas coordinates. */
+interface CanvasRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ImageEditorState {
+    /** The persisted document. */
+    doc: ImageEditDoc;
+    /** Selected layer id, or `null` when nothing is selected. */
+    selectedLayerId: string | null;
+    /** Active tool. */
+    tool: ImageEditorTool;
+    /**
+     * The shape kind the shape tool will drop next (a drawing palette kind,
+     * e.g. `'rectangle'`, `'diamond'`, `'arrow-right'`). Set when the user
+     * picks from the shape palette; defaults to `'rectangle'`.
+     */
+    shapeKind: string;
+    /**
+     * Dirty flag — true when the in-memory doc has unsaved changes
+     * relative to the last `markClean()` call. The hook uses this to
+     * debounce writes back to `state.json`.
+     */
+    dirty: boolean;
+}
+type ImageEditorAction = {
+    type: 'load';
+    doc: ImageEditDoc;
+} | {
+    type: 'mark-clean';
+} | {
+    type: 'set-tool';
+    tool: ImageEditorTool;
+} | {
+    type: 'set-shape-kind';
+    kind: string;
+} | {
+    type: 'select';
+    layerId: string | null;
+} | {
+    type: 'set-canvas';
+    canvas: ImageEditDoc['canvas'];
+} | {
+    type: 'add-layer';
+    layer: ImageEditLayerInput;
+    select?: boolean;
+} | {
+    type: 'remove-layer';
+    layerId: string;
+} | {
+    type: 'update-layer';
+    layerId: string;
+    patch: Partial<ImageEditLayer>;
+} | {
+    type: 'reorder-layer';
+    layerId: string;
+    toIndex: number;
+} | {
+    type: 'crop';
+    rect: CanvasRect;
+};
+/** Build the initial state from a freshly-loaded doc. */
+declare function initialImageEditorState(doc: ImageEditDoc): ImageEditorState;
+declare function imageEditorReducer(state: ImageEditorState, action: ImageEditorAction): ImageEditorState;
+
+/**
+ * React hook that bundles the image-editor reducer with sidecar
+ * persistence, versioning, and an object-URL cache for asset bytes.
+ *
+ * Hosts pass an already-scoped {@link ContentContainer} (typically built
+ * with `scopeContainer(parent, basename + '_files')`); the hook never
+ * looks above that root.
+ */
+
+interface UseImageEditorOptions {
+    /** Sidecar container for the image being edited. */
+    container: ContentContainer;
+    /**
+     * Initial source image URL — used to seed layer 0 when the sidecar has
+     * no `state.json` yet. Bytes are fetched and copied into
+     * `assets/source.<ext>` so the doc is portable.
+     */
+    initialSrc?: string;
+    /** Policy and byte/time limits for fetching `initialSrc`. */
+    resourcePolicy?: ResourcePolicy;
+    /** Override the state filename. Defaults to `state.json`. */
+    stateFilename?: string;
+    /** Enable version history. Default: `false`. */
+    allowVersioning?: boolean;
+    /** Auto-save idle delay (ms). `0` disables. Default: `5000`. */
+    versioningAutoSaveIdleMs?: number;
+    /** Debounced write delay for state.json (ms). Default: `500`. */
+    persistDebounceMs?: number;
+}
+interface UseImageEditorReturn {
+    /** Current reducer state (or `null` while still loading the initial doc). */
+    state: ImageEditorState | null;
+    /** Dispatch a reducer action. No-op while loading. */
+    dispatch: (action: ImageEditorAction) => void;
+    /** Manually trigger a synchronous write of `state.json`. */
+    flush: () => Promise<void>;
+    /** Resolve an asset path inside the sidecar to a blob URL (cached). */
+    resolveAssetUrl: (path: string) => Promise<string>;
+    /**
+     * Write a new asset (raster image) into `assets/` and return the
+     * sidecar-relative path. The caller is then expected to push a layer
+     * referencing that path.
+     */
+    uploadAsset: (file: Blob, suggestedName?: string) => Promise<string>;
+    /** Versioning handle. `null` when `allowVersioning` is false or no container. */
+    versioning: ImageEditVersionManager | null;
+    /** True after the initial load completes (either an existing doc or seeded). */
+    ready: boolean;
+    /** Last load / persistence error, if any. */
+    error: Error | null;
+}
+declare function useImageEditor(options: UseImageEditorOptions): UseImageEditorReturn;
+
+export { type CanvasRect, ImageEditor, type ImageEditorAction, type ImageEditorProps, type ImageEditorState, type ImageEditorTool, ImageViewer, type ImageViewerProps, type UseImageEditorOptions, type UseImageEditorReturn, imageEditorReducer, initialImageEditorState, useImageEditor };

package/dist/image-editor/index.js

@@ -0,0 +1,15 @@
+import {
+  ImageEditor,
+  ImageViewer,
+  imageEditorReducer,
+  initialImageEditorState,
+  useImageEditor
+} from "../chunk-V44VP242.js";
+import "../chunk-GS7QWYFT.js";
+export {
+  ImageEditor,
+  ImageViewer,
+  imageEditorReducer,
+  initialImageEditorState,
+  useImageEditor
+};