@archireport/react-native-drawing 0.2.0

package/README.md

@@ -0,0 +1,181 @@
+# @archireport/react-native-drawing
+
+Image annotation and drawing library for React Native, built on top of [@shopify/react-native-skia](https://shopify.github.io/react-native-skia/).
+
+## Features
+
+- **Freehand drawing** — Smooth brush strokes with configurable width and color
+- **Geometric shapes** — Lines, arrows, rectangles, circles
+- **Measurements** — Dimension annotations with text, unit and multiple display styles
+- **Text annotations** — Repositionable text blocks with optional background
+- **Selection & editing** — Move, resize and delete existing objects
+- **Undo** — Full undo stack
+- **Normalized coordinates** — All coordinates stored in `[0, 1]` range for resolution-independent persistence
+- **Serialization** — Import/export drawing objects as JSON
+- **Image export** — Export the annotated image as `Uint8Array` or Base64 string
+- **Customizable UI** — Override toolbar and color palette via render props
+
+## Installation
+
+```sh
+npm install @archireport/react-native-drawing
+```
+
+### Peer dependencies
+
+The following must be installed in your project:
+
+```sh
+npm install @shopify/react-native-skia react-native-gesture-handler react-native-reanimated
+```
+
+| Peer dependency                | Minimum version |
+| ------------------------------ | --------------- |
+| `@shopify/react-native-skia`   | `>=0.1.221`     |
+| `react`                        | `>=18.0.0`      |
+| `react-native`                 | `>=0.72.0`      |
+| `react-native-gesture-handler` | `>=2.14.0`      |
+| `react-native-reanimated`      | `>=3.6.0`       |
+
+> On iOS, run `cd ios && pod install` after installing.
+
+## Quick start
+
+```tsx
+import React, { useRef } from "react";
+import { View, Button } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import {
+  DrawingEditor,
+  type DrawingEditorRef,
+} from "@archireport/react-native-drawing";
+
+export default function App() {
+  const editorRef = useRef<DrawingEditorRef>(null);
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <DrawingEditor
+        ref={editorRef}
+        imageSource="https://example.com/photo.jpg"
+        onSave={({ image, objects }) => {
+          // image: Uint8Array of the annotated PNG
+          // objects: DrawingObject[] for persistence
+        }}
+      />
+    </GestureHandlerRootView>
+  );
+}
+```
+
+## Props
+
+### `DrawingEditorProps`
+
+| Prop                 | Type                                               | Description                                        |
+| -------------------- | -------------------------------------------------- | -------------------------------------------------- |
+| `imageSource`        | `string \| number`                                 | URI string or `require()` for the background image |
+| `initialObjects`     | `DrawingObject[]`                                  | Pre-existing objects to restore on the canvas      |
+| `onSave`             | `(result: { image, objects, canvasSize }) => void` | Called when the user saves                         |
+| `onDismiss`          | `() => void`                                       | Called when the user dismisses the editor          |
+| `style`              | `ViewStyle`                                        | Custom style for the root container                |
+| `renderToolbar`      | `(props: ToolbarRenderProps) => ReactNode`         | Override the default toolbar                       |
+| `renderColorPalette` | `(props: ColorPaletteRenderProps) => ReactNode`    | Override the default color palette                 |
+
+### `DrawingEditorRef`
+
+Access imperative methods via a ref:
+
+| Method                | Description                           |
+| --------------------- | ------------------------------------- |
+| `undo()`              | Undo the last action                  |
+| `setTool(tool)`       | Switch the active tool                |
+| `exportImage()`       | Returns `Promise<Uint8Array \| null>` |
+| `exportImageBase64()` | Returns `Promise<string \| null>`     |
+| `getObjects()`        | Returns the current `DrawingObject[]` |
+| `clearAll()`          | Remove all objects from the canvas    |
+
+## Tools
+
+| Tool        | Key         | Description                                |
+| ----------- | ----------- | ------------------------------------------ |
+| Selection   | `move`      | Select, move, resize and delete objects    |
+| Freehand    | `freehand`  | Free drawing with smooth strokes           |
+| Line        | `line`      | Straight line between two points           |
+| Arrow       | `arrow`     | Arrow from point A to B                    |
+| Rectangle   | `rectangle` | Rectangle defined by two corners           |
+| Circle      | `circle`    | Ellipse inscribed in a bounding box        |
+| Measurement | `measure`   | Dimension line with editable text and unit |
+| Text        | `text`      | Text annotation block                      |
+
+## Object types
+
+All objects use **normalized coordinates** (`0`–`1`) so drawings are resolution-independent.
+
+```ts
+type DrawingObject =
+  | FreehandObject // { type: "freehand", points: Point[], ... }
+  | LineObject // { type: "line", from, to, ... }
+  | ArrowObject // { type: "arrow", from, to, ... }
+  | RectangleObject // { type: "rectangle", from, to, backgroundColor?, ... }
+  | CircleObject // { type: "circle", from, to, backgroundColor?, ... }
+  | MeasureObject // { type: "measure", from, to, text, unit, measureStyle, ... }
+  | TextObject; // { type: "text", position, width, height, value, ... }
+```
+
+Every object carries `id`, `color` and `lineWidth`.
+
+## Serialization
+
+```ts
+import {
+  serializeObjects,
+  deserializeObjects,
+} from "@archireport/react-native-drawing";
+
+// Save
+const json = serializeObjects(editor.getObjects());
+
+// Restore
+const objects = deserializeObjects(json);
+```
+
+## Color palette
+
+Six preset colors are included and can be imported:
+
+```ts
+import {
+  PRESET_COLORS,
+  DEFAULT_STROKE_COLOR,
+} from "@archireport/react-native-drawing";
+// Red, Blue, Green, Orange, Dark, White
+```
+
+## Architecture
+
+- Single Skia `<Canvas>` renders all drawing objects
+- Touch pipeline: `GestureDetector` → Reanimated SharedValues (UI thread) → `runOnJS` on gesture end → Zustand store commit
+- State management via [Zustand](https://github.com/pmndrs/zustand) v5
+
+## Development
+
+```sh
+# Install dependencies
+npm install
+
+# Type-check
+npm run typescript
+
+# Build the library (commonjs + ESM + types)
+npm run prepare
+
+# Run the example app
+cd example
+npm install --legacy-peer-deps
+npx react-native run-ios
+```
+
+## License
+
+Private — ArchireportTeam