Editor API Reference

ElucimEditor

The main all-in-one editor component.

interface ElucimEditorProps {
  initialDocument?: RenderableDocument | ElucimDocument;
  initialFrame?: number | 'last';
  theme?: ElucimTheme;
  editorTheme?: Record<string, string>;
  onDocumentChange?: (document: ElucimDocument, details: ElucimEditorChangeDetails) => void;
  onCompatibilityWarnings?: (warnings: string[]) => void;
  onBrowseImage?: BrowseImageFn;
  imageResolver?: ImageResolverFn;
  className?: string;
  style?: React.CSSProperties;
}

Prop	Description
initialDocument	Starting document. ElucimDocument is the public authoring path; renderable documents are accepted for compatibility.
initialFrame	Starting frame, or 'last' to open at the final linear frame.
theme	Shared content ElucimTheme; editor chrome is derived from it.
editorTheme	Editor chrome token overrides. Accepts bare names or full CSS variable names.
onDocumentChange	Called after edits with Elucim Document output and compatibility details. Skips initial mount.
onCompatibilityWarnings	Called when document output has warnings such as renamed IDs, pruned timelines, or invalid restored output.
onBrowseImage	Opens a host-provided image picker from image fields.
imageResolver	Resolves opaque image refs in editor preview.
className / style	Root editor container styling.

<ElucimEditor
  initialDocument={doc}
  initialFrame="last"
  theme={contentTheme}
  editorTheme={{ 'color-scheme': 'light', accent: '#2563eb' }}
  onDocumentChange={(nextDoc, details) => {
    save(nextDoc);
    if (details.warnings.length > 0) showWarnings(details.warnings);
  }}
/>

ElucimEditorChangeDetails

interface ElucimEditorChangeDetails {
  changedFormat: boolean;
  warnings: string[];
}

warnings describe compatibility work performed while restoring editor edits to normalized output, such as deleted timeline targets or state-machine states that lost a timeline link.

ElucimEditorLayout

Internal shell layout for advanced composition inside an EditorProvider.

interface ElucimEditorLayoutProps {
  theme?: ElucimTheme;
  editorTheme?: Record<string, string>;
  className?: string;
  style?: React.CSSProperties;
  document?: ElucimDocument;
  onDocumentChange?: (document: ElucimDocument) => void;
}

import { EditorProvider, ElucimEditorLayout, useEditorDocument } from '@elucim/editor';

function CustomSaveButton() {
  const doc = useEditorDocument();
  return <button onClick={() => save(doc)}>Save working document</button>;
}

<EditorProvider initialDocument={doc}>
  <ElucimEditorLayout document={doc} onDocumentChange={setDoc} />
  <CustomSaveButton />
</EditorProvider>;

Use the top-level ElucimEditor unless you specifically need custom panels inside the editor context.

Exported components

Export	Description
ElucimEditor	Main editor component.
ElucimEditorLayout	Docked workspace shell for custom composition.
ElucimCanvas	Canvas with zoom/pan, selection, preview frames, minimap hooks, and overlays.
Toolbar	Create palette and file/history/theme controls.
Inspector	Contextual property panel.
Timeline	Timeline and state-machine motion panel.
FloatingPanel	Generic draggable/resizable panel primitive used by overlays.
SelectionOverlay	Selection boxes, resize handles, and rotation handles.
DotGrid	Zoom-adaptive canvas grid.
Minimap	Canvas overview.
ZoomControls	Zoom buttons and fit controls.
EditorMenuBar	Optional menu bar for host integrations.

Hooks

useEditorState()

Returns the editor context object:

function useEditorState(): {
  state: EditorState;
  dispatch: React.Dispatch<EditorAction>;
};

const { state, dispatch } = useEditorState();

dispatch({ type: 'SELECT', ids: ['title'] });
dispatch({ type: 'UNDO' });

useEditorDocument()

Returns the current editor working document.

function useEditorDocument(): RenderableDocument;

useEditorSelection()

Returns selected element IDs.

function useEditorSelection(): string[];

Other hooks

Hook	Description
useViewport()	Zoom/pan state and helpers.
useDrag()	Move, resize, and rotate interactions.
useMarquee()	Marquee selection.
useMeasuredBounds()	DOM-based element bounds measurement.

State types

interface EditorState {
  document: RenderableDocument;
  selectedIds: string[];
  viewport: { x: number; y: number; zoom: number };
  past: RenderableDocument[];
  future: RenderableDocument[];
  currentFrame: number;
  isPlaying: boolean;
  activeTool: EditorTool;
  isPanning: boolean;
  toolbarPosition: { x: number; y: number };
  inspectorPosition: { x: number; y: number } | null;
  inspectorPinned: boolean;
  toolbarCollapsed: boolean;
  themeOverrides: Record<string, string>;
}

type EditorTool = 'select' | 'rect' | 'circle' | 'line' | 'arrow' | 'text' | 'latex';

CANVAS_ID is the sentinel used when the canvas root is selected:

import { CANVAS_ID } from '@elucim/editor';

const canvasSelected = selectedIds.includes(CANVAS_ID);

Editor actions

The reducer supports selection, document replacement, element editing, grouping, ordering, arrangement, viewport, frame playback, panel state, theme overrides, and history:

Action	Payload
SELECT, SELECT_ADD, SELECT_TOGGLE, DESELECT_ALL	Selection updates
SET_DOCUMENT	Replace the working document
UPDATE_ELEMENT, UPDATE_CANVAS	Property updates
ADD_ELEMENT, DELETE_ELEMENTS, DUPLICATE_ELEMENTS	Element CRUD
MOVE_ELEMENT, RESIZE_ELEMENT, ROTATE_ELEMENT	Canvas transforms
GROUP_ELEMENTS, UNGROUP	Grouping
RENAME_ELEMENT, REORDER_ELEMENT	Identity and Object ordering
BRING_FORWARD, SEND_BACKWARD, BRING_TO_FRONT, SEND_TO_BACK	Sibling order
ALIGN_ELEMENTS, DISTRIBUTE_ELEMENTS	Multi-selection layout
SET_VIEWPORT, ZOOM_TO_FIT	Viewport controls
SET_FRAME, SET_PLAYING	Playback
SET_TOOL, SET_PANNING	Interaction mode
SET_EDITOR_THEME	Runtime chrome token overrides
UNDO, REDO	History

The reducer still contains legacy wrapper compatibility actions for old editor working documents, but normalized public authoring should use timelines and state machines.

Keyboard and mouse shortcuts

Interaction	Behavior
Delete / Backspace	Delete selected elements
Ctrl+Z	Undo
Ctrl+Y / Ctrl+Shift+Z	Redo
Ctrl+A	Select all
Ctrl+D	Duplicate
Ctrl+C / Ctrl+V	Copy / paste
Ctrl+G / Ctrl+Shift+G	Group / ungroup
Ctrl+] / Ctrl+[	Bring forward / send backward
Ctrl+Shift+] / Ctrl+Shift+[	Bring to front / send to back
Arrow keys	Nudge by 1px
Shift+Arrow keys	Nudge by 10px
Ctrl+= / Ctrl+-	Zoom in / out
Ctrl+0 / Ctrl+1	Fit / 100% zoom
Space + drag	Pan
Middle-click drag	Pan
Right-click	Context menu
Alt+drag element	Duplicate, then drag copy
Shift+drag resize handle	Constrained resize

Image APIs

interface BrowseImageResult {
  src?: string;
  ref?: string;
  displayName?: string;
  width?: number;
  height?: number;
  alt?: string;
}

type BrowseImageFn = () => Promise<BrowseImageResult | null>;
type ImageResolverFn = (ref: string) => string | Promise<string>;

Exports:

ImagePickerProvider
useImagePicker
ImageResolverProvider
useImageResolver

See Image Assets.

Theme APIs

function v(token: string, scheme?: 'light' | 'dark'): string;
function buildThemeVars(overrides?: Record<string, string>): React.CSSProperties;
function deriveEditorTheme(contentTheme: ElucimTheme, colorScheme: 'light' | 'dark'): Record<string, string>;
function makeRotateCursor(color?: string): string;

const EDITOR_TOKENS: Record<string, string>;
const EDITOR_TOKENS_LIGHT: Record<string, string>;
const ROTATE_CURSOR: string;

See Editor Theming.

Utilities

Import/export

function exportToJson(document: RenderableDocument, options?: { pretty?: boolean }): string;
function importFromJson(json: string): { document: RenderableDocument | null; errors: string[] };
function downloadAsJson(document: RenderableDocument, filename?: string): void;

importFromJson() accepts Elucim Document JSON, validates it, and migrates it into the editor working document shape. Host apps should persist onDocumentChange output when they need normalized document JSON.

Bounds and snapping

function getElementBounds(element: object):
  { x: number; y: number; width: number; height: number } | null;

function mergeBounds(boxes: Array<{ x: number; y: number; width: number; height: number }>):
  { x: number; y: number; width: number; height: number };

function isPointInBounds(
  point: { x: number; y: number },
  bounds: { x: number; y: number; width: number; height: number }
): boolean;

function computeSnap(value: number, gridSize: number): number;

Templates

const ELEMENT_TEMPLATES: ElementTemplate[];
function getTemplatesByCategory(): Record<string, ElementTemplate[]>;
const CATEGORY_LABELS: Record<string, string>;

Template categories are presentation, shape, line, text, math, and data.