@apexpath/canvas-editor

React + Konva canvas editor component library with multi-page workflows, floating toolbars, text effects, role-based access, and optional Unsplash search.

Version: 1.0.1
License: MIT

What's New

• Package identity updated to @apexpath/canvas-editor.
• Public CanvasEditorApp props include branding support (companyName, companyLogo) and navigation callback (onBack).
• designStateId persistence is now deterministic:
  • If initialState is provided, it is loaded and written to local storage for that design key.
  • If initialState is not provided, editor attempts to restore from local storage.
• triggerSave() returns export-safe state and clears local storage cache for that design key.
• Style entry is exported as @apexpath/canvas-editor/styles.

Features

• Text, shape, and image tools
• Text effects (original, shadow, highlight, glitch, echo)
• Multi-page editing (sides and pages modes)
• Multiple printable areas per page
• Object layering and visibility controls
• Role-based access (admin and custom)
• Floating object toolbars
• Optional Unsplash image search
• Dynamic Google Font loading

Installation

npm install @apexpath/canvas-editor

Peer dependencies:

• react ^18 || ^19
• react-dom ^18 || ^19

Required CSS

Import styles once in your app entry:

import '@apexpath/canvas-editor/styles';

Quick Start

import React from 'react';
import { CanvasEditorApp } from '@apexpath/canvas-editor';
import '@apexpath/canvas-editor/styles';

export default function MyDesignScreen() {
  return (
    <CanvasEditorApp
      designStateId="design-001"
      userRole="admin"
      companyName="ApexPath"
      unsplashApiKey={import.meta.env.VITE_UNSPLASH_ACCESS_KEY}
      onChange={(state) => {
        console.log('Changed:', state);
      }}
      onSave={(state) => {
        // Persist to your backend
        console.log('Save payload:', state);
      }}
    />
  );
}

CanvasEditorApp Props

| Prop | Type | Description | | --- | --- | --- | | designStateId | string | Optional key used for localStorage persistence (canvas-editor:design:<id>). | | userRole | 'admin' \| 'custom' | Actual signed-in role for capability control. Defaults to admin. | | unsplashApiKey | string | Enables Unsplash search in graphics/background panels. | | companyName | string | Branding title shown in top bar. Defaults to CanvasPro. | | companyLogo | string | Optional logo URL for top bar branding. | | materialColors | MaterialColorOption[] | Optional palette/material options consumed by left panel. | | initialState | Partial<CanvasState> \| CanvasState | Seed state. Missing fields are normalized with defaults. | | onSave | (state: CanvasState) => void | Called when internal save is triggered. Receives export-safe state. | | onChange | (state: CanvasState) => void | Called on every editor state change. | | onBack | () => void | Optional callback for top bar back action. |

Custom Layout

For full layout control, compose the provider and parts:

import React from 'react';
import {
  CanvasEditorProvider,
  CanvasSurface,
  LeftPanel,
  RightPanel,
} from '@apexpath/canvas-editor';
import '@apexpath/canvas-editor/styles';

export default function CustomEditor() {
  return (
    <CanvasEditorProvider userRole="admin">
      <div style={{ display: 'flex', height: '100vh', width: '100vw' }}>
        <LeftPanel />
        <CanvasSurface />
        <RightPanel />
      </div>
    </CanvasEditorProvider>
  );
}

useCanvasEditor Hook

import React from 'react';
import { useCanvasEditor } from '@apexpath/canvas-editor';

export function AddTextButton() {
  const { dispatch, triggerSave } = useCanvasEditor();

  const addText = () => {
    dispatch({
      type: 'ADD_OBJECT',
      payload: {
        type: 'text',
        name: 'Headline',
        text: 'Hello Canvas',
        x: 100,
        y: 100,
        fontSize: 32,
        fontFamily: 'Poppins',
      },
    });
  };

  return (
    <div>
      <button onClick={addText}>Add Text</button>
      <button onClick={triggerSave}>Save</button>
    </div>
  );
}

Action Types (Reducer)

Common actions:

• SET_USER_ROLE, SET_ROLE
• SET_TOOL, SET_ZOOM, SET_PAN, SET_CANVAS_SIZE
• ADD_OBJECT, UPDATE_OBJECT, DELETE_OBJECTS, DUPLICATE_OBJECTS
• MOVE_OBJECT_UP, MOVE_OBJECT_DOWN, MOVE_OBJECT_TO_FRONT, MOVE_OBJECT_TO_BACK
• SET_PAGE_MODE, ADD_PAGE, DELETE_PAGE, SET_CURRENT_PAGE, SET_SIDE_ENABLED
• SET_BACKGROUND_IMAGE, SET_BACKGROUND_IMAGES_BY_SIDE, SET_BACKGROUND_COLOR
• TOGGLE_EDIT_PRINTABLE_AREA, ADD_PRINTABLE_AREA, DELETE_PRINTABLE_AREA, SET_ACTIVE_PRINTABLE_AREA, UPDATE_PRINTABLE_AREA
• UPDATE_SETTINGS, LOAD_STATE

Public Exports

Main exports from the package root:

• CanvasEditorApp
• CanvasEditorProvider, useCanvasEditor
• Main components: CanvasSurface, LeftPanel, RightPanel, SecondaryPanel, ProductSidePanel
• Floating toolbar components: FloatingObjectToolbar, ShapeToolbar, TextToolbar, IconToolbar, ImageToolbar
• Secondary panels: BackgroundPanel, GraphicsPanel, LayersPanel, MaterialPanel, MorePanel, ObjectsPanel, TextPanel, UploadsPanel
• Font utilities: ensureFontLoaded, isGoogleFontFamily, TEXT_FONT_OPTIONS, GOOGLE_FONT_FAMILIES, SYSTEM_FONT_FAMILIES
• Feature utility: hasFeatureAccess
• Unsplash utilities: setUnsplashApiKey, hasUnsplashApiKey
• Iconify re-exports from @iconify/react

TypeScript Types

The package exports:

• CanvasEditorAppProps
• CanvasState, CanvasObject, Page, PrintableArea
• CanvasAction, CanvasEditorContextType
• Role, ToolType, PageMode
• CanvasSettings, UploadedAsset, FeatureKey

Build and Publish (Maintainers)

npm run build:lib
npm run lint
npm publish --access public

License

MIT