@ninesstudios/whiteboard 0.0.4 → 0.0.6

package/README.md

@@ -78,6 +78,13 @@ function App() {
     </div>
   );
 }
+
+// Example: read & replace elements
+// const elements = whiteboardRef.current?.getElements();
+// whiteboardRef.current?.setElements(elements);
+
+// Example: clear all elements
+// whiteboardRef.current?.clearElements();
 ```
 
 ### Programmatic Updates (applyAction)
@@ -129,7 +136,7 @@ function App() {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `onAction` | `(action: object) => void` | `undefined` | Callback fired whenever a state-changing action occurs (e.g., drawing, moving). |
+| `onAction` | `(action: object) => void` | `undefined` | Callback fired for content-changing actions (e.g., add/remove/move elements, text edits). It does not emit high-frequency UI actions like pan/zoom/selection/tool changes. |
 | `isLocked` | `boolean` | `false` | When `true`, disables all editing tools and shows a lock indicator. |
 | `lockText` | `string` | `undefined` | Custom text to display on the lock indicator when `isLocked` is true. |
 | `onLockChange` | `(isLocked: boolean) => void` | `undefined` | Callback fired when the lock state changes. |
@@ -141,8 +148,107 @@ You can access these methods by passing a `ref` to the `Whiteboard` component.
 | Method | Arguments | Description |
 |--------|-----------|-------------|
 | `applyAction` | `(action: object)` | Dispatches an action to the internal Redux store. Useful for applying remote updates. |
+| `getElems` / `getElements` | `()` | Returns the current `elements` array from the internal store. |
+| `setElems` / `setElements` | `(elements: object[])` | Replaces the entire `elements` array in the internal store. |
+| `clearElems` / `clearElements` | `()` | Clears all elements from the internal store. |
 | `canvas` | - | Returns the underlying HTMLCanvasElement. |
 
+### Redux Actions Helper
+
+For convenience (e.g., building your own `applyAction` payloads), the package exports the internal Redux action creators:
+
+```js
+import { whiteboardActions } from 'whiteboard';
+
+// Example: build an action object to send/apply
+const action = whiteboardActions.clearElements();
+// action.type === 'whiteboard/clearElements'
+```
+
+#### All available actions
+
+| Action creator | `action.type` | Payload |
+|---|---|---|
+| `toggleGrid()` | `whiteboard/toggleGrid` | _none_ |
+| `setGridSize(size)` | `whiteboard/setGridSize` | `number` |
+| `setGridColor(color)` | `whiteboard/setGridColor` | `string` |
+| `setSelectedTool(tool)` | `whiteboard/setSelectedTool` | `string` |
+| `setToolProperty({ tool, property, value })` | `whiteboard/setToolProperty` | `{ tool: string, property: string, value: any }` |
+| `addElement(element)` | `whiteboard/addElement` | `Element` (see “addElement payload” below) |
+| `updateElement({ id, updates })` | `whiteboard/updateElement` | `{ id: string, updates: object }` |
+| `removeElement(id)` | `whiteboard/removeElement` | `string` |
+| `setSelectedElement(idOrNull)` | `whiteboard/setSelectedElement` | `string \| null` |
+| `clearElements()` | `whiteboard/clearElements` | _none_ |
+| `setElements(elements)` | `whiteboard/setElements` | `object[]` |
+| `setPan({ x, y })` | `whiteboard/setPan` | `{ x: number, y: number }` |
+| `setZoom(zoom)` | `whiteboard/setZoom` | `number` |
+| `resetViewport()` | `whiteboard/resetViewport` | _none_ |
+| `fitToView({ canvasWidth, canvasHeight, padding? })` | `whiteboard/fitToView` | `{ canvasWidth: number, canvasHeight: number, padding?: number }` |
+| `bringToFront(id)` | `whiteboard/bringToFront` | `string` |
+| `sendToBack(id)` | `whiteboard/sendToBack` | `string` |
+| `setLocked(isLocked)` | `whiteboard/setLocked` | `boolean` |
+| `setWatermarkEnabled(visible)` | `whiteboard/setWatermarkEnabled` | `boolean` |
+| `setWatermarkText(text)` | `whiteboard/setWatermarkText` | `string` |
+
+#### `addElement(element)` payload
+
+`addElement` expects a full element object. Coordinates are **world coordinates** (the board handles pan/zoom internally).
+
+Common fields (all element types):
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Must be unique (commonly `Date.now().toString()`). |
+| `type` | `string` | One of the supported element types below. |
+
+Element schemas by `type`:
+
+- **rectangle / triangle / diamond / hexagon / octagon**
+  - Required: `x: number`, `y: number`, `width: number`, `height: number`
+  - Styling: `strokeColor: string`, `fillColor: string`, `lineWidth: number`
+
+- **circle**
+  - Required: `centerX: number`, `centerY: number`, `radius: number`
+  - Styling: `strokeColor: string`, `fillColor: string`, `lineWidth: number`
+
+- **pencil**
+  - Required: `points: Array<{ x: number, y: number }>`
+  - Styling: `strokeColor: string`, `lineWidth: number`
+
+- **star / heart**
+  - Required: `centerX: number`, `centerY: number`, `size: number`
+  - Styling: `strokeColor: string`, `fillColor: string`, `lineWidth: number`
+
+- **arrow**
+  - Required: `startX: number`, `startY: number`, `endX: number`, `endY: number`
+  - Styling: `strokeColor: string`, `fillColor: string`, `lineWidth: number`
+
+- **text**
+  - Required: `x: number`, `y: number`, `text: string`
+  - Styling: `fontSize: number`, `fontColor: string`
+
+- **image**
+  - Required: `x: number`, `y: number`, `width: number`, `height: number`, `src: string`
+  - Notes: `src` is typically a Data URL (from `FileReader.readAsDataURL`).
+
+Example (rectangle):
+
+```js
+import { whiteboardActions } from 'whiteboard';
+
+const action = whiteboardActions.addElement({
+  id: '1',
+  type: 'rectangle',
+  x: 100,
+  y: 80,
+  width: 200,
+  height: 120,
+  strokeColor: '#000000',
+  fillColor: '#ffffff',
+  lineWidth: 2,
+});
+```
+
 ## License
 
 MIT