### Install and Start Development Server

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Installs project dependencies and starts the development server. Access the dev server at http://localhost:4200.

```bash
npm install
npm run start
```

--------------------------------

### Install and Start Development Server

Source: https://github.com/plait-board/drawnix/blob/develop/README_en.md

Use these npm commands to install project dependencies and start the development server.

```bash
npm install

npm run start
```

--------------------------------

### Complete React Board Example

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

A full example demonstrating how to integrate the Plait Board component into a React application. It shows state management for board elements, configuration options, and a custom toolbar with basic interaction.

```typescript
import React, { useState } from 'react';
import {
  Wrapper,
  Board,
  useBoard,
} from '@plait-board/react-board';
import { PlaitElement, PlaitBoardOptions } from '@plait/core';

function MyBoardApp() {
  const [elements, setElements] = useState<PlaitElement[]>([]);

  const options: PlaitBoardOptions = {
    readonly: false,
    hideScrollbar: false,
    disabledScrollOnNonFocus: false,
  };

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <Wrapper
        value={elements}
        options={options}
        plugins={[]}
        onChange={(data) => {
          setElements(data.children);
          console.log('Board changed:', data);
        }}
      >
        <MyToolbar />
        <Board
          style={{
            width: '100%',
            height: '100%',
          }}
        />
      </Wrapper>
    </div>
  );
}

function MyToolbar() {
  const board = useBoard();

  return (
    <div style={{ padding: '10px', background: '#f0f0f0' }}>
      <button onClick={() => {
        const selection = board.selection;
        console.log('Selected:', selection);
      }}>
        Log Selection
      </button>
    </div>
  );
}

export default MyBoardApp;
```

--------------------------------

### Install Drawnix and Core Packages

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

Install Drawnix along with its core dependencies using npm. Ensure you have `@plait/core` and `@plait/draw` installed.

```bash
npm install @drawnix/drawnix @plait/core @plait/draw @plait/mind
```

--------------------------------

### Example Usage of getShortcutKey

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Demonstrates how to use the `getShortcutKey` function to format keyboard shortcuts for display, adapting to different platforms like Mac and Windows/Linux.

```typescript
import { getShortcutKey } from '@drawnix/drawnix';

const display = getShortcutKey('CtrlOrCmd+S');
// Mac: 'Cmd+S'
// Windows/Linux: 'Ctrl+S'
```

--------------------------------

### Example Board Change Handling

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

Demonstrates how to use the onChange callback to log board change data, including the number of elements, operations, zoom level, and selection.

```typescript
<Wrapper
  value={elements}
  onChange={(data) => {
    console.log('Board changed:');
    console.log('- Elements:', data.children.length);
    console.log('- Operations:', data.operations);
    console.log('- Zoom:', data.viewport.zoom);
    console.log('- Selected:', data.selection);
  }}
>
  <Board />
</Wrapper>
```

--------------------------------

### Create a Drawnix Board

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Initialize a new Drawnix board with state management. This is the basic setup for any Drawnix application.

```typescript
import { Drawnix } from '@drawnix/drawnix';
import { PlaitElement } from '@plait/core';
import { useState } from 'react';
import '@drawnix/drawnix/index.css';

export function App() {
  const [elements, setElements] = useState<PlaitElement[]>([]);

  return (
    <Drawnix
      value={elements}
      onValueChange={setElements}
      style={{ width: '100%', height: '100vh' }}
    />
  );
}
```

--------------------------------

### Setup Event Listeners for Board Interactions

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/constants.md

Sets up event listeners for common board interactions such as copy and pointer down events using predefined event constants.

```typescript
import { EVENT } from '@drawnix/drawnix';

function setupEventListener(board) {
  document.addEventListener(EVENT.COPY, () => {
    // Handle copy
  });
  
  document.addEventListener(EVENT.POINTER_DOWN, () => {
    // Handle pointer down
  });
}
```

--------------------------------

### Example Usage of ValueOf

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/types.md

Demonstrates how to use the ValueOf utility type to get the union of value types from an object.

```typescript
const colors = { red: '#FF0000', green: '#00FF00' };
type ColorValue = ValueOf<typeof colors>; // '#FF0000' | '#00FF00'
```

--------------------------------

### Basic Drawnix Component Setup

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/README.md

Import the Drawnix component and its CSS for basic integration into your React application. Ensure you provide the 'value' and 'onValueChange' props.

```typescript
import { Drawnix } from '@drawnix/drawnix';
import '@drawnix/drawnix/index.css';

<Drawnix value={elements} onValueChange={setElements} />
```

--------------------------------

### Drawnix Component Usage Example

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/drawnix-component.md

Demonstrates how to integrate the Drawnix component into a React application, managing its state for elements and viewport. Ensure the necessary CSS is imported.

```typescript
import React, { useState } from 'react';
import { Drawnix } from '@drawnix/drawnix';
import { PlaitElement, Viewport } from '@plait/core';
import '@drawnix/drawnix/index.css';

export function MyBoard() {
  const [elements, setElements] = useState<PlaitElement[]>([]);
  const [viewport, setViewport] = useState<Viewport>({
    x: 0,
    y: 0,
    zoom: 1,
  });

  return (
    <Drawnix
      value={elements}
      viewport={viewport}
      onChange={(data) => {
        setElements(data.children);
        setViewport(data.viewport);
      }}
      onValueChange={setElements}
      onViewportChange={setViewport}
      tutorial={true}
      style={{ width: '100%', height: '100vh' }}
    />
  );
}
```

--------------------------------

### I18nProvider Usage Example

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/hooks.md

Demonstrates how to wrap your application with I18nProvider to enable internationalization. It sets the default language and allows child components to access translations. The provider persists the selected language to localStorage.

```typescript
import { I18nProvider, Drawnix } from '@drawnix/drawnix';

export function App() {
  return (
    <I18nProvider defaultLanguage="en">
      <Drawnix value={[]} />
    </I18nProvider>
  );
}
```

--------------------------------

### Drawnix Component with Freehand Presets

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/freehand-drawing.md

Example of integrating the Drawnix component for freehand drawing. It initializes with specific freehand presets, including stroke width and color, and sets the active preset.

```typescript
import { Drawnix, useSetPointer, FreehandShape } from '@drawnix/drawnix';
import { PlaitElement } from '@plait/core';
import { useState } from 'react';

export function DrawingApp() {
  const [elements, setElements] = useState<PlaitElement[]>([]);

  return (
    <Drawnix
      value={elements}
      onValueChange={setElements}
      initialToolState={{
        pointer: FreehandShape.feltTipPen,
        freehandPresets: [
          { strokeWidth: 2 },
          { strokeColor: '#FF0000', strokeWidth: 6 },
          { strokeColor: '#00FF00', strokeWidth: 8 },
        ],
        activeFreehandPresetIndex: 0,
      }}
    />
  );
}
```

--------------------------------

### useI18n Hook Usage Example

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/hooks.md

Demonstrates how to use the useI18n hook to get the current language, set a new language, and translate strings within a React component. This snippet includes a language switcher dropdown.

```typescript
import { useI18n } from '@drawnix/drawnix';

function LanguageSwitcher() {
  const { language, setLanguage, t } = useI18n();

  return (
    <div>
      <p>{t('language.switcher')}</p>
      <select value={language} onChange={(e) => setLanguage(e.target.value as any)}>
        <option value="zh">{t('language.chinese')}</option>
        <option value="en">{t('language.english')}</option>
        <option value="ru">{t('language.russian')}</option>
        <option value="ar">{t('language.arabic')}</option>
        <option value="vi">{t('language.vietnamese')}</option>
      </select>
    </div>
  );
}
```

--------------------------------

### Handle File Dialog Cancellation

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/errors.md

When using `fileOpen` or `fileSave`, the promise will reject if the user cancels the file dialog. This example shows how to catch these rejections to provide a smooth user experience.

```typescript
import { fileOpen } from '@drawnix/drawnix';

try {
  const file = await fileOpen({
    extensions: ['drawnix'],
    description: 'Drawnix files',
  });
  // User selected file
} catch (error) {
  // User cancelled dialog or error occurred
  console.log('File dialog cancelled or error:', error);
}
```

--------------------------------

### Drawnix Component Integration

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

Shows how to wrap the Plait Board component within the Drawnix Wrapper component. This setup includes various toolbars and optional components like Tutorial.

```typescript
// Inside Drawnix component
<Wrapper
  value={value}
  viewport={viewport}
  theme={theme}
  options={options}
  plugins={plugins}
  onChange={onChange}
  onSelectionChange={onSelectionChange}
  onViewportChange={onViewportChange}
  onThemeChange={onThemeChange}
  onValueChange={onValueChange}
>
  <Board afterInit={afterInit}>
    {tutorial && <Tutorial />}
  </Board>
  <AppToolbar />
  <CreationToolbar />
  <ZoomToolbar />
  <ThemeToolbar />
  <PopupToolbar />
  {/* ... more toolbars ... */}
</Wrapper>
```

--------------------------------

### useBoard Hook Usage

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

Shows how to import and use the useBoard hook to get the current board instance within a React component. This hook must be called within a Wrapper context.

```typescript
import { useBoard } from '@plait-board/react-board';

function MyToolbar() {
  const board = useBoard();

  const handleDelete = () => {
    const selected = board.selection;
    if (selected) {
      // delete selected elements
    }
  };

  return <button onClick={handleDelete}>Delete</button>;
}
```

--------------------------------

### Configure Initial Drawnix Tool State

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/configuration.md

Set the initial selection for tools like pointer, shapes, arrows, and freehand presets. This prop configures the starting state of drawing tools within the Drawnix component.

```typescript
<Drawnix
  value={elements}
  initialToolState={{
    pointer: 'hand',
    lastShapePointer: 'rectangle',
    lastArrowPointer: 'straight',
    lastFreehandPointer: 'feltTipPen',
    activeFreehandPresetIndex: 0,
    freehandPresets: [
      { strokeWidth: 2 },
      { strokeColor: '#FF0000', strokeWidth: 6 },
      { strokeColor: '#00FF00', strokeWidth: 10 },
    ],
  }}
/>
```

--------------------------------

### i18nInsidePlaitHook Usage Example

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/hooks.md

Shows how to use the i18nInsidePlaitHook to access translation functions and the current language within Plait framework hooks. This hook does not rely on React context.

```typescript
import { i18nInsidePlaitHook } from '@drawnix/drawnix';

function myPlaitPlugin(board: PlaitBoard) {
  const i18n = i18nInsidePlaitHook();
  const message = i18n.t('toolbar.hand');
  console.log(`Current language: ${i18n.language}`);
}
```

--------------------------------

### Build and Test Project

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Commands for building all project packages, running tests, and performing code quality checks.

```bash
npm run build
npm run test
npm run lint
```

--------------------------------

### Get Current Font Color

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Retrieves the text color for a Plait element.

```typescript
function getCurrentFontColor(board: PlaitBoard, element: PlaitElement): string
```

--------------------------------

### Get Current Stroke Color

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Retrieves the stroke color for a Plait element.

```typescript
function getCurrentStrokeColor(board: PlaitBoard, element: PlaitElement): string
```

--------------------------------

### React Board Component Usage

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

Demonstrates how to integrate the Board component within a React application. It shows setting up the Wrapper, passing initialization callbacks, and applying styles and class names.

```typescript
import { Wrapper, Board } from '@plait-board/react-board';
import { PlaitBoard } from '@plait/core';

function MyBoardContainer() {
  const handleInit = (board: PlaitBoard) => {
    console.log('Board initialized:', board.children.length, 'elements');
  };

  return (
    <Wrapper value={[]} options={{}} plugins={[]}>
      <Board
        afterInit={handleInit}
        style={{ width: '100%', height: '100vh' }}
        className="my-board"
      >
        {/* Optional: render toolbars or overlays here */}
      </Board>
    </Wrapper>
  );
}
```

--------------------------------

### Mobile Detection Example

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

Detect if the application is running on a mobile device using the useDrawnix hook. This allows for adaptive UI adjustments.

```typescript
const { appState } = useDrawnix();
if (appState.isMobile) {
  // Adjust UI for touch
}
```

--------------------------------

### Get Current Fill Color

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Retrieves the fill color for a Plait element, considering default values based on the element's type.

```typescript
function getCurrentFill(board: PlaitBoard, element: PlaitElement): string
```

--------------------------------

### Wrapper Component

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

The main integration component that initializes the board and manages state. It accepts various props to configure the board's behavior, appearance, and event handling.

```APIDOC
## Wrapper Component

### Description
The main integration component that initializes the board and manages state. It accepts various props to configure the board's behavior, appearance, and event handling.

### Props
#### Required Props
- **value** (PlaitElement[]) - Array of board elements.
- **children** (ReactNode) - React components to render (typically `<Board />` and toolbars).
- **options** (PlaitBoardOptions) - Board configuration options.
- **plugins** (PlaitPlugin[]) - Plugin stack to apply to board.

#### Optional Props
- **viewport** (Viewport) - Initial viewport state.
- **theme** (PlaitTheme) - Initial theme configuration.
- **onChange** ((data: BoardChangeData) => void) - Fired on any board operation.
- **onSelectionChange** ((selection: Selection | null) => void) - Fired when selection changes.
- **onValueChange** ((value: PlaitElement[]) => void) - Fired when elements change.
- **onViewportChange** ((value: Viewport) => void) - Fired when viewport changes.
- **onThemeChange** ((value: ThemeColorMode) => void) - Fired when theme changes.

### Return Type
React component that manages board state and renders children within board context.

### Example Usage
```typescript
import { Wrapper, Board } from '@plait-board/react-board';
import { PlaitElement } from '@plait/core';
import { useState } from 'react';

export function MyBoard() {
  const [elements, setElements] = useState<PlaitElement[]>([]);

  return (
    <Wrapper
      value={elements}
      options={{
        readonly: false,
        hideScrollbar: false,
        disabledScrollOnNonFocus: false,
      }}
      plugins={[]}
      onChange={(data) => {
        setElements(data.children);
      }}
      onValueChange={setElements}
    >
      <Board />
    </Wrapper>
  );
}
```
```

--------------------------------

### Open Native File Picker with Drawnix

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Use `fileOpen` to launch the browser's native file picker. Specify allowed file extensions and a description for the picker. The `multiple` option determines if a single file or an array of files is returned.

```typescript
import { fileOpen } from '@drawnix/drawnix';

// Single image file
const imageFile = await fileOpen({
  extensions: ['png', 'svg'],
  description: 'Image file',
});

// Multiple files
const files = await fileOpen({
  extensions: ['drawnix'],
  description: 'Drawnix files',
  multiple: true,
});
```

--------------------------------

### Export Board as PNG

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Exports the current board content as a PNG image file for download. The background transparency is determined by the `exportTransparent` setting in `board.appState`.

```typescript
import { saveAsPng } from '@drawnix/drawnix';

const board = /* ... */;
saveAsPng(board);
// Downloads file named: drawnix-{timestamp}.png
```

--------------------------------

### Download Blob as File

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Initiates a file download for a given Blob or MediaSource. The user can specify the desired filename for the downloaded file.

```typescript
function download(blob: Blob | MediaSource, filename: string): void
```

--------------------------------

### React Wrapper Component Usage

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

Demonstrates how to use the Wrapper component to initialize and manage a Plait board within a React application. It shows state management for board elements and configuration options.

```typescript
import { Wrapper, Board } from '@plait-board/react-board';
import { PlaitElement } from '@plait/core';
import { useState } from 'react';

export function MyBoard() {
  const [elements, setElements] = useState<PlaitElement[]>([]);

  return (
    <Wrapper
      value={elements}
      options={{
        readonly: false,
        hideScrollbar: false,
        disabledScrollOnNonFocus: false,
      }}
      plugins={[]}
      onChange={(data) => {
        setElements(data.children);
      }}
      onValueChange={setElements}
    >
      <Board />
    </Wrapper>
  );
}
```

--------------------------------

### fileOpen

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Opens the native file picker dialog for loading files. It supports filtering by specified extensions and can allow for multiple file selections.

```APIDOC
## fileOpen

### Description
Open native file picker dialog for loading files.

### Method
```
function fileOpen<M extends boolean | undefined = false>(opts: {
  extensions?: FILE_EXTENSION[];
  description: string;
  multiple?: M;
}): Promise<M extends false | undefined ? File : File[]>
```

### Parameters
#### Options
- **extensions** (FILE_EXTENSION[]) - Optional - File types to accept
- **description** (string) - Required - Human-readable file type description
- **multiple** (boolean) - Optional - Allow selecting multiple files

### Returns
Single File or File[] depending on `multiple` flag

### Supported Extensions
- `svg`, `png`, `jpg`, `gif`, `webp`, `bmp`, `ico`, `avif`, `jfif`
- `drawnix`, `json`

### Example
```typescript
import { fileOpen } from '@drawnix/drawnix';

// Single image file
const imageFile = await fileOpen({
  extensions: ['png', 'svg'],
  description: 'Image file',
});

// Multiple files
const files = await fileOpen({
  extensions: ['drawnix'],
  description: 'Drawnix files',
  multiple: true,
});
```
```

--------------------------------

### Get Default File Name (TypeScript)

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/configuration.md

Generates a default file name using the current timestamp in milliseconds. This is used when saving files without an explicit name.

```typescript
const getDefaultName = () => {
  const time = new Date().getTime();
  return time.toString();
};
```

--------------------------------

### saveAsPng

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Exports the current board content as a PNG image file, initiating a download.

```APIDOC
## saveAsPng

### Description
Exports board content as PNG image file download.

### Method
```typescript
function saveAsPng(board: PlaitBoard): void
```

### Parameters
#### Path Parameters
- **board** (`PlaitBoard`) - Required - The board instance to export

### Request Example
```typescript
import { saveAsPng } from '@drawnix/drawnix';

const board = /* ... */;
saveAsPng(board);
// Downloads file named: drawnix-{timestamp}.png
```

### Notes
The export uses the `exportTransparent` setting from `board.appState` to determine background transparency.
```

--------------------------------

### Load Board from JSON

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

Use loadFromJSON to load a board state from a JSON file. The loaded data and file handle are returned.

```typescript
import { loadFromJSON } from '@drawnix/drawnix';

const { data, fileHandle } = await loadFromJSON(board);
console.log(data.elements);
```

--------------------------------

### Get Background Color for Theme

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Retrieves the background color appropriate for the current theme of a Plait board. This function is useful for dynamically setting UI element colors.

```typescript
import { getBackgroundColor } from '@drawnix/drawnix';

const board = /* ... */;
const bgColor = getBackgroundColor(board);
// Returns theme-specific background color
```

--------------------------------

### download

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Triggers the download of a Blob or MediaSource as a file with a specified filename.

```APIDOC
## download

### Description
Trigger download of a blob as a file.

### Signature
```typescript
function download(blob: Blob | MediaSource, filename: string): void
```

### Parameters
#### Path Parameters
- **blob** (Blob | MediaSource) - Required - File content to download
- **filename** (string) - Required - Name for the downloaded file
```

--------------------------------

### loadFromJSON

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Opens a file dialog to allow the user to select a saved file and loads the board state from it. It returns the loaded data along with the file handle.

```APIDOC
## loadFromJSON

### Description
Opens a file dialog to load a board state from a saved JSON file. Returns the loaded data and the file handle.

### Method
```
function loadFromJSON(
  board: PlaitBoard
): Promise<{
  data: DrawnixExportedData;
  fileHandle: DrawnixFileHandle;
}> 
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Description |
|-----------|------|-------------| 
| board | `PlaitBoard` | Board instance to load into |

### Response
#### Success Response
- **data** (`DrawnixExportedData`) - The loaded board data.
- **fileHandle** (`DrawnixFileHandle`) - The handle of the loaded file.

### Throws
Error if the file is invalid or not supported.

### Request Example
```typescript
import { loadFromJSON } from '@drawnix/drawnix';

const board = /* ... */;
try {
  const { data, fileHandle } = await loadFromJSON(board);
  console.log('Loaded elements:', data.elements);
} catch (error) {
  console.error('Failed to load file:', error);
}
```
```

--------------------------------

### Manage Language and Translations with useI18n

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

The `useI18n` hook provides functionality for managing the application's language and accessing translations. Use `setLanguage` to switch locales and `t` to get translated strings.

```typescript
const { language, setLanguage, t } = useI18n();

setLanguage('en');            // Switch language
const label = t('toolbar.hand');  // Get translation
```

--------------------------------

### nativeFileSystemSupported

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Checks if the browser supports the native file system access API.

```APIDOC
## nativeFileSystemSupported

### Description
Check if browser supports native file system access.

### Method
```
const nativeFileSystemSupported: boolean
```

### Example
```typescript
import { nativeFileSystemSupported } from '@drawnix/drawnix';

if (!nativeFileSystemSupported) {
  console.log('Browser does not support File System Access API');
}
```
```

--------------------------------

### Load Board State from JSON File

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Use this function to open a file dialog, load a board state from a selected JSON file, and populate the provided `PlaitBoard` instance. Handles potential errors during loading.

```typescript
import { loadFromJSON } from '@drawnix/drawnix';

const board = /* ... */;
try {
  const { data, fileHandle } = await loadFromJSON(board);
  console.log('Loaded elements:', data.elements);
} catch (error) {
  console.error('Failed to load file:', error);
}
```

--------------------------------

### Freehand Drawing Toolbar Controls

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/freehand-drawing.md

Demonstrates a toolbar for controlling the freehand drawing pointer. It uses the `useSetPointer` hook to switch between different freehand tools like pens, brushes, and erasers.

```typescript
function DrawingToolbar() {
  const setPointer = useSetPointer();

  return (
    <div>
      <button onClick={() => setPointer(FreehandShape.feltTipPen)}>
        Felt Tip
      </button>
      <button onClick={() => setPointer(FreehandShape.nibPen)}>
        Nib Pen
      </button>
      <button onClick={() => setPointer(FreehandShape.artisticBrush)}>
        Artistic
      </button>
      <button onClick={() => setPointer(FreehandShape.markerHighlight)}>
        Marker
      </button>
      <button onClick={() => setPointer(FreehandShape.eraser)}>
        Eraser
      </button>
    </div>
  );
}
```

--------------------------------

### buildImage

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Creates an image object with scaled dimensions, maintaining the aspect ratio and constraining the width to a maximum value. It takes an HTMLImageElement, a DataURL, and the maximum width as input.

```APIDOC
## buildImage

### Description
Create image object with scaled dimensions.

### Module
`@drawnix/drawnix`

### Source
`packages/drawnix/src/data/image.ts:21`

### Signature
```typescript
function buildImage(
  image: HTMLImageElement,
  dataURL: DataURL,
  maxWidth: number
): {
  url: DataURL;
  width: number;
  height: number;
}
```

### Behavior
Maintains aspect ratio while constraining to maxWidth.
```

--------------------------------

### Saving Board Data as JSON and PNG

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/README.md

Use the `saveAsJSON` and `saveAsPng` functions to persist the board's state. `saveAsJSON` returns a file handle for the saved JSON file.

```typescript
const { fileHandle } = await saveAsJSON(board);
await saveAsPng(board);
```

--------------------------------

### boardToImage

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Renders the Plait board to an image data URL using default styling options.

```APIDOC
## boardToImage

### Description
Render board to image with default styling options.

### Signature
```typescript
function boardToImage(board: PlaitBoard, options?: ToImageOptions): Promise<string>
```

### Returns
Promise<string> - Data URL for the rendered image
```

--------------------------------

### Check Native File System Support

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

The `nativeFileSystemSupported` boolean indicates whether the current browser environment supports the Native File System Access API. Use this to conditionally enable or disable features that rely on this API.

```typescript
import { nativeFileSystemSupported } from '@drawnix/drawnix';

if (!nativeFileSystemSupported) {
  console.log('Browser does not support File System Access API');
}
```

--------------------------------

### addImage

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Opens a file dialog to allow the user to select an image, which is then inserted into the board.

```APIDOC
## addImage

### Description
Open file dialog and insert image into the board.

### Method
```typescript
function addImage(board: PlaitBoard): Promise<void>
```

### Parameters
#### Path Parameters
- **board** (`PlaitBoard`) - Required - The board instance

### Request Example
```typescript
import { addImage } from '@drawnix/drawnix';

const board = /* ... */;
await addImage(board);
// User selects image file and it's inserted into board
```

### Response
#### Success Response
- Promise that resolves after image insertion completes
```

--------------------------------

### getShortcutKey

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Formats a keyboard shortcut string to match the current platform's conventions.

```APIDOC
## getShortcutKey

### Description
Format keyboard shortcut string for current platform.

On Mac/Apple, converts:
- `CtrlOrCmd` → `Cmd`
- `Alt` → `Option`

On other platforms:
- `CtrlOrCmd` → `Ctrl`

### Signature
```typescript
function getShortcutKey(shortcut: string): string
```

### Example
```typescript
import { getShortcutKey } from '@drawnix/drawnix';

const display = getShortcutKey('CtrlOrCmd+S');
// Mac: 'Cmd+S'
// Windows/Linux: 'Ctrl+S'
```
```

--------------------------------

### DEFAULT_FREEHAND_PRESETS

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/freehand-drawing.md

Provides a set of default drawing presets for freehand drawing, which can be customized and persisted.

```APIDOC
## DEFAULT_FREEHAND_PRESETS

### Description
Default drawing presets provided in the UI.

### Type Definition
```typescript
const DEFAULT_FREEHAND_PRESETS: FreehandDrawOptions[]
```

### Presets
1. Default stroke width (2px) with theme color
2. Red color (6px width)
3. Green color (10px width)

These presets are customizable and persist in tool state.
```

--------------------------------

### EventPointerType

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/types.md

Defines the possible input device types for pointer events, such as mouse, pen, or touch.

```APIDOC
## EventPointerType

### Description
Represents the input device type for a pointer interaction.

### Type Definition
```typescript
type EventPointerType = 'mouse' | 'pen' | 'touch';
```

### Module
`@drawnix/drawnix`
```

--------------------------------

### Import Required Stylesheet

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

Include the main stylesheet for the Plait Board component to ensure proper rendering and styling.

```typescript
import '@plait-board/react-board/index.css';
```

--------------------------------

### Initialize Mobile Detection

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/configuration.md

Detects mobile devices using the 'mobile-detect' library based on the user agent. The result is used to set the application state and apply responsive styling.

```typescript
const md = new MobileDetect(window.navigator.userAgent);
const isMobile = md.mobile() !== null;
```

--------------------------------

### useBoard Hook

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/react-board-integration.md

The useBoard hook provides access to the current Plait Board instance within the component tree. It must be used within the context of a `<Wrapper>` component.

```APIDOC
## useBoard Hook

Access board instance from within component tree.

### Signature

```typescript
function useBoard(): PlaitBoard
```

### Returns

The current board instance. Must be called within `<Wrapper>` context.

### Example

```typescript
import { useBoard } from '@plait-board/react-board';

function MyToolbar() {
  const board = useBoard();

  const handleDelete = () => {
    const selected = board.selection;
    if (selected) {
      // delete selected elements
    }
  };

  return <button onClick={handleDelete}>Delete</button>;
}
```
```

--------------------------------

### Add Image to Board

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

Use addImage to open a file picker and add an image to the board.

```typescript
import { addImage } from '@drawnix/drawnix';

await addImage(board);  // Open file picker
```

--------------------------------

### Save Board as JSON, PNG, or SVG

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

Use saveAsJSON, saveAsPng, or saveAsSvg to save the current board state. saveAsJSON returns a file handle for subsequent saves without a dialog.

```typescript
import { saveAsJSON, saveAsPng, saveAsSvg } from '@drawnix/drawnix';

const { fileHandle } = await saveAsJSON(board);  // Save JSON
await saveAsPng(board);                          // Download PNG
await saveAsSvg(board);                          // Download SVG

// Next time, save without dialog:
await saveJSON(board, fileHandle);
```

--------------------------------

### Build Image with Scaled Dimensions

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Creates an image object with dimensions scaled to fit within a maximum width while maintaining the aspect ratio. It takes the loaded image, its data URL, and the maximum width as input.

```typescript
function buildImage(
  image: HTMLImageElement,
  dataURL: DataURL,
  maxWidth: number
): {
  url: DataURL;
  width: number;
  height: number;
}
```

--------------------------------

### Add Image to Board

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Opens a file dialog allowing the user to select an image, which is then inserted into the board. The function resolves after the image insertion is complete.

```typescript
import { addImage } from '@drawnix/drawnix';

const board = /* ... */;
await addImage(board);
// User selects image file and it's inserted into board
```

--------------------------------

### Import Drawnix Stylesheet

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/configuration.md

Import the main stylesheet to enable full UI styling for components like toolbars and dialogs. This is required for proper rendering.

```typescript
import '@drawnix/drawnix/index.css';
```

--------------------------------

### Render Color Picker with Classic Colors

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/constants.md

Renders a color picker component using the predefined CLASSIC_COLORS. Each color is displayed as a button with its corresponding background color.

```typescript
import { CLASSIC_COLORS } from '@drawnix/drawnix';

function renderColorPicker() {
  return CLASSIC_COLORS.map(({ name, value }) => (
    <button
      key={name}
      style={{ backgroundColor: value }}
      title={name}
    />
  ));
}
```

--------------------------------

### saveAsSvg

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Exports the current board content as an SVG file, initiating a download.

```APIDOC
## saveAsSvg

### Description
Exports board content as an SVG file download.

### Method
```typescript
function saveAsSvg(board: PlaitBoard): Promise<void>
```

### Parameters
#### Path Parameters
- **board** (`PlaitBoard`) - Required - The board instance to export

### Request Example
```typescript
import { saveAsSvg } from '@drawnix/drawnix';

const board = /* ... */;
await saveAsSvg(board);
// Downloads file named: drawnix-{timestamp}.svg
```

### Response
#### Success Response
- Promise that resolves when the SVG file is downloaded
```

--------------------------------

### Render Board to Image

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Renders the current state of a PlaitBoard into an image data URL using default styling. Custom options can be provided to modify the rendering.

```typescript
function boardToImage(board: PlaitBoard, options?: ToImageOptions): Promise<string>
```

--------------------------------

### Drawnix Project Structure

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/README.md

Overview of the Drawnix and React Board project directory structure, indicating the location of main components, hooks, utilities, and other modules.

```text
packages/
  drawnix/
    src/
      drawnix.tsx                    ← Main component
      hooks/use-drawnix.tsx          ← Hooks
      utils/                         ← Utilities
      data/                          ← File operations
      plugins/freehand/             ← Freehand types
      i18n/                         ← Translations
      constants.ts                  ← Constants
  react-board/
    src/
      wrapper.tsx                    ← Wrapper component
      board.tsx                      ← Board component
      hooks/use-board.ts            ← useBoard hook
```

--------------------------------

### Freehand Stroke Width Constants

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/freehand-drawing.md

Constants defining the default, minimum, maximum, and step granularity for freehand drawing stroke width.

```typescript
const DEFAULT_FREEHAND_STROKE_WIDTH = 2;
const MIN_FREEHAND_STROKE_WIDTH = 1;
const MAX_FREEHAND_STROKE_WIDTH = 12;
const FREEHAND_STROKE_WIDTH_STEP = 0.25;
```

--------------------------------

### Default Freehand Presets Array

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/freehand-drawing.md

An array of default freehand drawing options, providing common stroke configurations for UI presets.

```typescript
const DEFAULT_FREEHAND_PRESETS: FreehandDrawOptions[]
```

--------------------------------

### Export Board as SVG

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/utilities.md

Exports the current board content as an SVG file for download. This function initiates a file download prompt for the user.

```typescript
import { saveAsSvg } from '@drawnix/drawnix';

const board = /* ... */;
await saveAsSvg(board);
// Downloads file named: drawnix-{timestamp}.svg
```

--------------------------------

### Handle AbortError Exception

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/errors.md

Demonstrates how to catch and handle an AbortError. This is useful for gracefully managing operations that have been cancelled.

```typescript
import { AbortError } from '@drawnix/drawnix';

try {
  throw new AbortError('File loading was cancelled');
} catch (error) {
  if (error instanceof AbortError) {
    console.log('Operation was aborted:', error.message);
  }
}
```

--------------------------------

### Color Utilities for Opacity and Background

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/QUICK-START.md

Utilize functions like applyOpacityToHex, hexAlphaToOpacity, removeHexAlpha, and getBackgroundColor for color manipulation and theme retrieval.

```typescript
import {
  applyOpacityToHex,
  hexAlphaToOpacity,
  removeHexAlpha,
  getBackgroundColor,
} from '@drawnix/drawnix';

applyOpacityToHex('#FF0000', 50);  // → '#FF000080'
hexAlphaToOpacity('#FF000080');     // → 50
removeHexAlpha('#FF000080');        // → '#FF0000'
getBackgroundColor(board);          // Current theme bg
```

--------------------------------

### Drawnix Utilities API

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/README.md

Documentation for utility functions related to image manipulation, color handling, and element styling.

```APIDOC
## Drawnix Utilities API

### Description
This API reference covers utility functions for common tasks within Drawnix, including image operations, color conversions, and property getters.

### Categories
- **Image**: Functions for saving, exporting, copying images to the clipboard, and adding images to the canvas.
- **Color**: Utilities for opacity conversion, color validation, and accessing theme-specific colors.
- **Property**: Functions to retrieve styling properties of elements.
- **Common**: Utilities for event composition, handling downloads, and managing keyboard shortcuts.
```

--------------------------------

### React Board Components and Hooks

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Provides React components and hooks for integrating the Plait board functionality into a React application.

```APIDOC
## React Board

### Wrapper

#### Description
A wrapper component for the Plait board.

#### Usage
```typescript
import { Wrapper } from '@plait-board/react-board';

<Wrapper wrapperProps={...}>
  {/* ... */}
</Wrapper>
```

#### Props
- **WrapperProps** (type) - Props for the Wrapper component.

### Board

#### Description
The main Plait board component.

#### Usage
```typescript
import { Board } from '@plait-board/react-board';

<Board plaitBoardProps={...} />
```

#### Props
- **PlaitBoardProps** (type) - Props for the Board component.

### useBoard

#### Description
Hook to access the Plait board instance.

#### Usage
```typescript
import { useBoard } from '@plait-board/react-board';

const board = useBoard();
```

### useListRender

#### Description
Hook to access list rendering information.

#### Usage
```typescript
import { useListRender } from '@plait-board/react-board';

const listRender = useListRender();
```
```

--------------------------------

### Data Management

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Functions for saving, loading, and serializing board data in JSON format, as well as file handling utilities.

```APIDOC
## Data Management

### saveAsJSON

#### Description
Saves the board data as a JSON file.

#### Usage
```typescript
import { saveAsJSON } from '@drawnix/drawnix';

const { fileHandle } = await saveAsJSON(board, 'myBoard');
```

### saveJSON

#### Description
Saves the board data to a specific file handle as JSON.

#### Usage
```typescript
import { saveJSON } from '@drawnix/drawnix';

const { fileHandle } = await saveJSON(board, fileHandle, 'myBoard');
```

### loadFromJSON

#### Description
Loads board data from a JSON file.

#### Usage
```typescript
import { loadFromJSON } from '@drawnix/drawnix';

const { data, fileHandle } = await loadFromJSON(board);
```

### serializeAsJSON

#### Description
Serializes the board data into a JSON string.

#### Usage
```typescript
import { serializeAsJSON } from '@drawnix/drawnix';

const jsonString = serializeAsJSON(board);
```

### isValidDrawnixData

#### Description
Validates if the provided data is in a valid Drawnix format.

#### Usage
```typescript
import { isValidDrawnixData } from '@drawnix/drawnix';

const isValid = isValidDrawnixData(data);
```

### fileOpen

#### Description
Opens a file dialog for the user to select files.

#### Usage
```typescript
import { fileOpen } from '@drawnix/drawnix';

const files = await fileOpen({ accept: { 'image/*': ['.png', '.svg'] } });
```

### fileSave

#### Description
Saves a blob to a file using the file system handle.

#### Usage
```typescript
import { fileSave } from '@drawnix/drawnix';

const handle = await fileSave(blob, { fileName: 'myFile.txt' });
```
```

--------------------------------

### Save Board State as New JSON File

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Use this function to initiate a file save dialog and save the current board state to a new JSON file. Provide a custom name to avoid the default timestamp.

```typescript
import { saveAsJSON } from '@drawnix/drawnix';

const board = /* ... */;
const { fileHandle } = await saveAsJSON(board, 'my-diagram');
// Opens save dialog, saves as my-diagram.drawnix
```

--------------------------------

### Color Utilities

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Utilities for manipulating and analyzing colors, including opacity adjustments, hex conversions, and transparency checks.

```APIDOC
## Color Utilities

### applyOpacityToHex

#### Description
Applies a given opacity to a hex color.

#### Usage
```typescript
import { applyOpacityToHex } from '@drawnix/drawnix';

const newColor = applyOpacityToHex('#FF0000', 0.5);
```

### hexAlphaToOpacity

#### Description
Converts a hex color with alpha to its opacity value.

#### Usage
```typescript
import { hexAlphaToOpacity } from '@drawnix/drawnix';

const opacity = hexAlphaToOpacity('#FF000080');
```

### removeHexAlpha

#### Description
Removes the alpha channel from a hex color.

#### Usage
```typescript
import { removeHexAlpha } from '@drawnix/drawnix';

const opaqueColor = removeHexAlpha('#FF000080');
```

### isTransparent

#### Description
Checks if a color is transparent.

#### Usage
```typescript
import { isTransparent } from '@drawnix/drawnix';

const transparent = isTransparent('#00000000');
```

### getBackgroundColor

#### Description
Retrieves the background color of the board.

#### Usage
```typescript
import { getBackgroundColor } from '@drawnix/drawnix';

const bgColor = getBackgroundColor(board);
```
```

--------------------------------

### Add Image with Validation

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/errors.md

This function shows how to validate an image file format before attempting to insert it into the board. It includes error handling for unsupported image types and general insertion errors.

```typescript
async function addImageWithValidation(board, file) {
  try {
    if (!isSupportedImageFile(file)) {
      console.error('Unsupported image format');
      return;
    }
    
    const { insertImage } = await import('@drawnix/drawnix');
    await insertImage(board, file);
    
  } catch (error) {
    console.error('Failed to insert image:', error);
  }
}
```

--------------------------------

### Drawnix Utilities

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/INDEX.md

Utility functions for saving and copying board content in various formats (SVG, PNG), and for adding images to the board.

```APIDOC
## Utilities

### saveAsSvg

#### Description
Saves the current board content as an SVG file.

#### Usage
```typescript
import { saveAsSvg } from '@drawnix/drawnix';

await saveAsSvg(board);
```

### saveAsPng

#### Description
Saves the current board content as a PNG file.

#### Usage
```typescript
import { saveAsPng } from '@drawnix/drawnix';

saveAsPng(board);
```

### copySelectionAsSvg

#### Description
Copies the selected content of the board as an SVG.

#### Usage
```typescript
import { copySelectionAsSvg } from '@drawnix/drawnix';

await copySelectionAsSvg(board);
```

### copySelectionAsPng

#### Description
Copies the selected content of the board as a PNG.

#### Usage
```typescript
import { copySelectionAsPng } from '@drawnix/drawnix';

await copySelectionAsPng(board);
```

### canCopySelectionAs

#### Description
Checks if the selection can be copied in the specified format.

#### Usage
```typescript
import { canCopySelectionAs } from '@drawnix/drawnix';

const canCopy = canCopySelectionAs('svg');
```

### addImage

#### Description
Adds an image to the board.

#### Usage
```typescript
import { addImage } from '@drawnix/drawnix';

await addImage(board);
```
```

--------------------------------

### I18nProvider Configuration (React)

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/configuration.md

Configures the I18nProvider for internationalization. Set the default language to be used if none is found in localStorage. This provider is required for i18n functionality.

```jsx
<I18nProvider defaultLanguage="en">
  {/* children */}
</I18nProvider>
```

--------------------------------

### saveJSON

Source: https://github.com/plait-board/drawnix/blob/develop/_autodocs/api-reference/data-management.md

Saves the board state, with an option to update an existing file handle. If an `existingFileHandle` is provided, it will update that file directly without opening a dialog. If a `name` is provided for a new file, it will be used.

```APIDOC
## saveJSON

### Description
Saves the board state, optionally updating an existing file handle. If no `existingFileHandle` is provided, a file dialog will open to create a new file.

### Method
```
function saveJSON(
  board: PlaitBoard,
  existingFileHandle?: DrawnixFileHandle,
  name?: string
): Promise<{ fileHandle: DrawnixFileHandle }>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| board | `PlaitBoard` | yes | Board instance to serialize |
| existingFileHandle | `DrawnixFileHandle` | no | Previous file handle (skip dialog if provided) |
| name | `string` | no | Filename for new file |

### Response
#### Success Response
- **fileHandle** (`DrawnixFileHandle`) - Handle for the saved file.

### Request Example
```typescript
import { saveJSON } from '@drawnix/drawnix';

// First save
const result1 = await saveJSON(board, null, 'my-diagram');

// Update existing file (no dialog)
const result2 = await saveJSON(board, result1.fileHandle);
// Updates my-diagram.drawnix without prompting
```
```