JSON Canvas Viewer

https://github.com/hesprs/json-canvas-viewer
Admin
JSON Canvas Viewer is an extensible web-based viewer for JSON Canvas files with interactive pan and...
Tokens:25,560
Snippets:213
Trust Score:6.9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install @json-canvas-viewer/react with npm, pnpm, yarn, or bun

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/react/README.md

Install the React component package using your preferred package manager. Choose one command; all are equivalent.

```bash
npm add @json-canvas-viewer/react

# or
pnpm add @json-canvas-viewer/react

# or
yarn add @json-canvas-viewer/react

# or
bun add @json-canvas-viewer/react
```

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

### Install vite-plugin-json-canvas

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/vite/README.md

Install the plugin with your preferred package manager. The -D flag saves it as a dev dependency.

```bash
npm add vite-plugin-json-canvas -D

# or
pnpm add vite-plugin-json-canvas -D

# or
yarn add vite-plugin-json-canvas -D

# or
bun add vite-plugin-json-canvas -D
```

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

### Install json-canvas-viewer with npm, pnpm, yarn, or bun

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/core/README.md

Install the core package with your preferred package manager. The command shows npm, pnpm, yarn, and bun alternatives.

```bash
npm add json-canvas-viewer

# or
pnpm add json-canvas-viewer

# or
yarn add json-canvas-viewer

# or
bun add json-canvas-viewer
```

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

### Install @json-canvas-viewer/preact with npm, pnpm, yarn, or bun

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/preact/README.md

Install the Preact component package using your preferred package manager. Choose one of the four commands.

```bash
npm add @json-canvas-viewer/preact

# or
pnpm add @json-canvas-viewer/preact

# or
yarn add @json-canvas-viewer/preact

# or
bun add @json-canvas-viewer/preact
```

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

### Full Example - DebugPanel Module

Source: https://github.com/hesprs/json-canvas-viewer/wiki/5-🧑‍💻-Develop-a-Module

Complete example of a DebugPanel module. It injects DataManager and Controller, subscribes to the onRefresh hook, creates a debug panel, uses custom options, and implements cleanup with dispose.

```TypeScript
import { type BaseArgs, type BaseOptions, BaseModule, internal } from 'json-canvas-viewer';
import 'path/to/your/styles.css'; // access the styles

const { DataManager, Controller } = internal;

// for demonstration only, we create a useless option
interface Options extends BaseOptions {
    report?: boolean;
};

interface Augmentation {
    updateDebugPanel: DebugPanel['update'];
}

export default class DebugPanel extends BaseModule<Options, Augmentation> {
	private _debugPanel?: HTMLDivElement;
	private DM: DataManager;

	private get debugPanel() { // getter to handle nullable property
		if (!this._debugPanel) throw new Error("[JSONCanvasViewer] Resource hasn't been set up or has been disposed.");
	    return this._debugPanel;
	}

	constructor(...args: BaseArgs) {
		super(...args);
		this.DM = this.container.get(DataManager); // dependency injection
		this.container.get(Controller).hooks.onRefresh.subscribe(this.update); // subscribe to hooks

		this._debugPanel = document.createElement('div');
		this._debugPanel.className = 'debug-panel';
		const HTMLContainer = this.DM.data.container;
		HTMLContainer.appendChild(this._debugPanel);

		if (this.options.report) console.log('DebugPanel initialized.'); // access custom options
        this.onDispose(this.dispose); // access lifecycle hook
        this.augment({ updateDebugPanel: this.update })
	}

	private update = () => {
		const round = (num: number, dp: number) => {
            const factor = 10 ** digits;
            return Math.round(roundedNum * factor) / factor;
		};
		const data = this.DM.data;
		this.debugPanel.innerHTML = `<p>Scale: ${round(data.scale, 3)}</p><p>Offset: ${round(data.offsetX, 1)}, ${round(data.offsetY, 1)}</p>`;
	};

    // clean up to prevent memory leaks
	private dispose = () => {
		this.debugPanel.remove();
		this._debugPanel = undefined;
	};
}
```

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

### Install @json-canvas-viewer/vue with npm, pnpm, yarn, or bun

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/vue/README.md

Install the Vue component package with your preferred package manager. Choose one of the four commands; they are equivalent alternatives.

```bash
npm add @json-canvas-viewer/vue

# or
pnpm add @json-canvas-viewer/vue

# or
yarn add @json-canvas-viewer/vue

# or
bun add @json-canvas-viewer/vue
```

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

### Client-side canvas parsing with fetchCanvas and parser

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/preact/README.md

Import the parser and fetchCanvas, then fetch the canvas file at runtime. No bundler setup required.

```tsx
import { JSONCanvasViewerComponent, fetchCanvas, parser } from '@json-canvas-viewer/preact';

export async function App() {
  return (
    <JSONCanvasViewerComponent
      canvas={await fetchCanvas('path/to/your.canvas')}
      options={{ parser }}
    />
  );
}
```

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

### Build-time canvas parsing with JSONCanvasViewer

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/core/README.md

Recommended build-time canvas parsing. Requires a bundler (currently Vite only) and the Vite Plugin setup. Imports the canvas file directly and passes it to the viewer.

```typescript
import { JSONCanvasViewer } from 'json-canvas-viewer';
import canvas from 'path/to/your.canvas';

const container = document.getElementById('container') as HTMLElement;
new JSONCanvasViewer({ canvas, container });
```

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

### Client-side canvas parsing with fetchCanvas and parser

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/react/README.md

Import the parser and fetch the canvas file at runtime. No bundler setup required. The component receives the fetched canvas and the parser option.

```tsx
import { JSONCanvasViewerComponent, fetchCanvas, parser } from '@json-canvas-viewer/react';

export async function App() {
  return (
    <JSONCanvasViewerComponent
      canvas={await fetchCanvas('path/to/your.canvas')}
      options={{ parser }}
    />
  );
}
```

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

### Quick Start HTML with JSONCanvasViewer

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/README.md

Minimal HTML page that loads the `chimp` version of JSON Canvas Viewer from unpkg and mounts it on `document.body`. Requires a canvas file (e.g., from the demo.canvas link) and uses `fetchCanvas` to load it; the `parser` is passed to the viewer constructor.

```HTML
<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<title>🐒 Canvas Viewer</title>
	<style>
		body, html {
			margin: 0;
			padding: 0;
			width: 100%;
			height: 100%;
		}
	</style>
</head>
<body></body>
<script type="module">
import { JSONCanvasViewer, parser, fetchCanvas } from 'https://unpkg.com/json-canvas-viewer';
new JSONCanvasViewer({
    container: document.body, // The element to attach the viewer to
    canvas: await fetchCanvas('path/to/your.canvas'), // remember to prepare your canvas
    parser,
});
</script>
</html>
```

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

### Client-side canvas parsing with parser and fetchCanvas

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/core/README.md

Client-side canvas parsing without bundler setup. Imports the parser and fetchCanvas, then fetches the canvas file at runtime.

```typescript
import { parser, fetchCanvas, JSONCanvasViewer } from 'json-canvas-viewer';

const container = document.getElementById('container') as HTMLElement;
new JSONCanvasViewer({
    container,
    parser,
    canvas: await fetchCanvas('path/to/your.canvas'),
});
```

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

### Client-side canvas parsing with fetchCanvas and parser

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/vue/README.md

Use client-side canvas parsing without any bundler setup. Import the parser and fetchCanvas, then pass the fetched canvas and the parser option to the component. Wrap the component in <Suspense>; it is crucial for this to work.

```vue
<script setup>
import { JSONCanvasViewerComponent, fetchCanvas, parser } from '@json-canvas-viewer/vue';
</script>

<template>
  <Suspense>
    <!-- Suspense is crucial -->
    <JSONCanvasViewerComponent
      :canvas="await fetchCanvas('path/to/your.canvas')"
      :options="{ parser }"
    />
  </Suspense>
</template>
```

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

### Build-time canvas parsing with JSONCanvasViewerComponent

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/preact/README.md

Import the Preact component and a canvas file directly. Requires Vite and the Vite plugin setup. Recommended for smaller bundle size and faster load times.

```tsx
import { JSONCanvasViewerComponent } from '@json-canvas-viewer/preact';
import canvas from 'path/to/your.canvas';

export function App() {
  return <JSONCanvasViewerComponent canvas={canvas} />;
}
```

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

### Quick start with chimp version HTML

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/1-🚀-Quick-Start.md

Use the chimp version of JSON Canvas Viewer for fast trials and environments without bundlers or package managers. The single-file bundle includes the markdown parser and canvas loader; you must have a prepared .canvas file. Not recommended for production due to lack of customization and tree-shaking.

```HTML
<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<title>🐒 Canvas Viewer</title>
	<style>
		body,
		html {
			margin: 0;
			padding: 0;
			width: 100%;
			height: 100%;
		}
	</style>
</head>
<body></body>
<script type="module">
    import { JSONCanvasViewer, parser, fetchCanvas, Minimap } from 'https://unpkg.com/json-canvas-viewer';

    new JSONCanvasViewer(
	    {
		    container: document.body, // The element to attach the viewer to
		    canvas: await fetchCanvas('path/to/your.canvas'), // remember to prepare your canvas
            markdownParser: parser,
	    },
	    [Minimap], // The modules to load
    );
</script>
</html>
```

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

### Build-time canvas parsing with Vite plugin

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/react/README.md

Import a canvas file directly and pass it to the component. Requires Vite and the Vite Plugin setup. Recommended for smaller bundle size and faster load times.

```tsx
import { JSONCanvasViewerComponent } from '@json-canvas-viewer/react';
import canvas from 'path/to/your.canvas';

export function App() {
  return <JSONCanvasViewerComponent canvas={canvas} />;
}
```

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

### React/Preact server component with prerenderHtml

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/4-🖇️-Prerendering.md

Minimal example of a server component that uses renderToString to generate HTML and passes it to the JSONCanvasViewerComponent via the prerenderHtml prop. The canvas is imported directly from a file.

```tsx
import { JSONCanvasViewerComponent } from '@json-canvas-viewer/react'; // or '@json-canvas-viewer/preact'
import canvas from 'path/to/your.canvas';

// a server component
export default async function App() {
  const html = await renderToString({ canvas });

  return (
    <main>
      {/* ... your other components */}
      <JSONCanvasViewerComponent prerenderHtml={html} canvas={canvas} />
    </main>
  );
}
```

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

### Dependency Injection - Accessing DataManager with needle-di

Source: https://github.com/hesprs/json-canvas-viewer/wiki/5-🧑‍💻-Develop-a-Module

Shows how to inject the DataManager service into a module using needle-di. The example imports BaseModule, BaseArgs, and internal, then retrieves DataManager from the container in the constructor.

```TypeScript
import { BaseModule, type BaseArgs, internal } from "json-canvas-viewer";

const { DataManager } = internal;

class MyModule extends BaseModule {
    private dataManager: DataManager;
    constructor(...args: BaseArgs) {
        super(...args);
        this.dataManager = this.container.get(DataManager);
    }
}
```

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

### Define custom options for a module

Source: https://github.com/hesprs/json-canvas-viewer/wiki/5-🧑‍💻-Develop-a-Module

Pass a type parameter to BaseModule that extends BaseOptions to ensure type correctness. The example defines an Options interface with optional useAsync and useCache flags, and a MyModule class that extends BaseModule<Options>.

```TypeScript
import { BaseModule, type BaseArgs, type BaseOptions } from "json-canvas-viewer";

interface Options extends BaseOptions {
    useAsync?: boolean;
    useCache?: boolean;
}

class MyModule extends BaseModule<Options> {
    constructor(...args: BaseArgs) {
        super(...args);
    }
}
```

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

### Augment the main instance with methods

Source: https://github.com/hesprs/json-canvas-viewer/wiki/5-🧑‍💻-Develop-a-Module

Inject methods and properties into the main instance by passing an Augmentation type parameter to BaseModule. The example defines an Augmentation interface with a log property, and MyModule calls this.augment({ log: this.log }) in the constructor. Ensure the augmentation matches the type parameter exactly.

```TypeScript
import { BaseModule, type BaseArgs } from "json-canvas-viewer";

interface Augmentation {
    log: MyModule['log'];
}

class MyModule extends BaseModule<{}, Augmentation> {
    constructor(...args: BaseArgs) {
        super(...args);
        this.augment({ log: this.log });
    }

    log(toLog: string) {
        console.log(`[MyModule]: ${toLog}`);
    }
}
```

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

### Constructor Options

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/2-🏗️-Construction-Details.md

The constructor accepts an options object and optional modules. This snippet documents the available options and their types.

```APIDOC
## Constructor Options

### Description
Options for customizing the JSON Canvas Viewer instance.

### Parameters
#### options (object) - Required
- **container** (HTMLElement) - Required - The HTML element to attach the viewer to. Not needed in React/Vue/Preact components.
- **canvas** (JSONCanvas) - Optional - The canvas object. Default: an empty canvas. Can be obtained from `fetchCanvas` export or importing canvas file (Vite only). Elevated to component property in React/Vue/Preact.
- **theme** ('light' | 'dark') - Optional - Choose light or dark theme. Default: 'light'. Elevated to component property in React/Vue/Preact.
- **attachments** (Record<string, string>) - Optional - Remaps attachment file paths to true locations. Keys are original file paths, values are true file paths. Elevated to component property in React/Vue/Preact.
- **parser** ((markdown: string) => string | Promise<string>) - Optional - Markdown parser. Default: identity function. Unnecessary with Vite + vite-plugin-json-canvas. Package exports a parser using Marked.
- **shadowed** (boolean) - Optional - Whether to put viewer in shadow DOM. Default: false.
- **loading** ('normal' | 'lazy' | 'none') - Optional - How to load the canvas. Default: 'normal'. 'none' requires manual `JSONCanvasViewer.load()`. 'lazy' delays until viewport entry.
- **pointeract** (PointeractOptions) - Optional - Options passed to pointeract, the user interaction resolver.
- **colors** (object) - Optional - Customize color palette. Supports HSL, RGB, RGBA, HEX strings. Fields: '0' to '6' for pre-defined colors, plus dots, text, background, 'background-secondary', shadow, border.
- **nodeComponents** (object) - Optional - Render nodes with custom components. Keys: 'text' | 'image' | 'audio' | 'video' | 'link' | 'markdown'. Each value is a function receiving { container, content, node, onBeforeUnmount, onActive, onLoseActive }. In React/Vue/Preact, elevated to component properties/slots.

### TypeScript Interface
```TypeScript
interface Options {
    container: HTMLElement;
    canvas?: JSONCanvas;
    theme?: 'light' | 'dark';
    attachments?: Record<string, string>;
    parser?: (markdown: string) => string | Promise<string>;
    shadowed?: boolean;
    loading?: 'normal' | 'lazy' | 'none';
    pointeract?: PointeractOptions;
    colors?: {
        light?: Colors;
        dark?: Colors;
    };
    nodeComponents?: {
        [Key: 'text' | 'image' | 'audio' | 'video' | 'link' | 'markdown']: (args: {
          container: HTMLDivElement;
          content: string;
          node: JSONCanvasNode;
          onBeforeUnmount: Hook;
          onActive: Hook;
          onLoseActive: Hook;
        }) => void | Promise<void>;
    }
}

interface Colors {
    '0'?: string;
    '1'?: string;
    '2'?: string;
    '3'?: string;
    '4'?: string;
    '5'?: string;
    '6'?: string;
    dots?: string;
    text?: string;
    background?: string;
    'background-secondary'?: string;
    shadow?: string;
    border?: string;
}

type Hook<Args extends GeneralArray = []> = {
  (...args: Args): void;
  subs: Set<(...args: Args) => void>;
  subscribe(callback: (...args: Args) => void): void;
  unsubscribe(callback: (...args: Args) => void): void;
};
```
```

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

### Constructor: JSONCanvasViewer(options, modules?)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Documentation for the JSONCanvasViewer constructor, including all options and their types.

```APIDOC
## Constructor: JSONCanvasViewer(options, modules?)

### Description
Creates a new JSON Canvas Viewer instance. The constructor accepts an options object and an optional modules array. The options object allows customization of the viewer's behavior, appearance, and integration.

### Method
Constructor

### Endpoint
`new JSONCanvasViewer(options, modules?)`

### Parameters
#### options (Object) - Required
- **container** (HTMLElement) - Required - The HTML element to attach the viewer to. Not needed in React/Vue/Preact components.
- **canvas** (JSONCanvas) - Optional - The canvas object. Default: an empty canvas. Can be obtained from `fetchCanvas` export or importing canvas file (Vite only). Elevated to a component property in React/Vue/Preact components.
- **theme** ('light' | 'dark') - Optional - Choose light or dark theme. Default: `light`. Elevated to a component property in React/Vue/Preact components.
- **attachments** (Record<string, string>) - Optional - Remaps attachment file paths to their true locations. Keys are original file paths, values are true file paths. Relative paths are relative to the file where instantiation happens. Elevated to a component property in React/Vue/Preact components.
- **parser** ((markdown: string) => string | Promise<string>) - Optional - The markdown parser. Default: `(markdown) => markdown`. The package exports a parser using Marked.
- **shadowed** (boolean) - Optional - Whether to put the viewer in a shadow DOM. Default: `false`.
- **loading** ('normal' | 'lazy' | 'none') - Optional - How to load the canvas. Default: `normal`. `none` disables loading, `lazy` delays until viewport entry, `normal` loads immediately.
- **pointeract** (PointeractOptions) - Optional - Options passed to `pointeract`, the user interaction resolver.
- **colors** (Object) - Optional - Customize the color palette. Keys `0` to `6` customize pre-defined colors, others customize other parts. Supports HSL, RGB, RGBA, and HEX color strings.
- **nodeComponents** (Object) - Optional - Render nodes with custom components. Keys: `text`, `image`, `audio`, `video`, `link`, `markdown`. Each value is a function receiving `{ container, content, node, onBeforeUnmount, onActive, onLoseActive }`. If defined, default node is not rendered.

#### modules (Array) - Optional
- Not described in detail in the source.

### Request Example
```typescript
const viewer = new JSONCanvasViewer({
  container: document.getElementById('viewer'),
  canvas: myCanvas,
  theme: 'dark',
  attachments: { 'file.md': '/public/file.md' },
  parser: (md) => marked.parse(md),
  shadowed: true,
  loading: 'lazy',
  colors: { '0': '#ff0000', text: '#333' },
  nodeComponents: {
    text: ({ container, content, node }) => { /* custom render */ }
  }
});
```

### Response
#### Success Response
- Returns a `JSONCanvasViewer` instance.

#### Response Example
```typescript
const viewer = new JSONCanvasViewer(options);
```
```

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

### Import DebugPanel module

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/3-🧩-Modules.md

Import the DebugPanel module from 'json-canvas-viewer' to display current scale and coordinates.

```TypeScript
import { DebugPanel } from 'json-canvas-viewer';
```

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

### Import Controls module

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/3-🧩-Modules.md

Import the Controls module from 'json-canvas-viewer' to add zoom and fullscreen controls.

```TypeScript
import { Controls } from 'json-canvas-viewer';
```

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

### toggleFullscreen(option?)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Exits or enters fullscreen mode. If no option is provided, toggles the fullscreen state.

```APIDOC
## toggleFullscreen(option?)

### Description
Exits or enters fullscreen mode. If no option is provided, toggles the fullscreen state.

### Method
toggleFullscreen

### Endpoint
toggleFullscreen(option?: 'enter' | 'exit')

### Parameters
#### Optional Parameters
- **option** ('enter' | 'exit') - Optional - Whether to enter or exit fullscreen. If omitted, toggles the current state.

### Response
No return value.
```

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

### Context7 Query Prompt

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/README.md

Short prompt to ask an agent to query `json-canvas-viewer` on Context7, skipping the longer documentation prompt. Agents may also search Context7 on their own.

```markdown
Query `json-canvas-viewer` on Context7.
```

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

### changeTheme(theme?)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Shifts between dark and light theme. If no theme is provided, toggles the theme.

```APIDOC
## changeTheme(theme?)

### Description
Shifts between dark and light theme. If no theme is provided, toggles the theme.

### Method
changeTheme

### Endpoint
changeTheme(theme?: 'dark' | 'light')

### Parameters
#### Optional Parameters
- **theme** ('dark' | 'light') - Optional - The theme to switch to. If omitted, toggles the current theme.

### Response
No return value.
```

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

### Hook Methods

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Hook methods allow subscribing to viewer lifecycle events. Each hook has subscribe, unsubscribe, and invoke methods.

```APIDOC
## Hook Methods

### Description
Hook methods allow subscribing to viewer lifecycle events. Each hook has subscribe, unsubscribe, and invoke methods.

### Method
Hook

### Endpoint
Various hook methods: onStart, onRestart, onDispose, onRefresh, onResize, onToggleFullscreen, onChangeTheme, onNodeActive, onNodeLosesActive

### Parameters
Each hook can be subscribed to with a callback function. The callback receives arguments depending on the hook.

### Response
No return value.
```

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

### Constructor (React/Preact)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Renders the JSON Canvas Viewer as a React/Preact component with custom node components.

```APIDOC
## Constructor (React/Preact)

### Description
Renders the JSON Canvas Viewer as a React/Preact component with custom node components.

### Method
Component

### Endpoint
<Viewer />

### Parameters
#### Props
- **canvas** (JSONCanvas) - Required - The canvas object to display.
- **text** (function) - Optional - A render prop for custom text nodes. Receives arguments and returns a React/Preact element.

### Request Example
```tsx
import canvas from 'path/to/your.canvas';
import { JSONCanvasViewerComponent as Viewer } from '@json-canvas-viewer/react'; // or '@json-canvas-viewer/preact'

export default function component() {
  return (
    <Viewer
      canvas={canvas}
      text={({/* you can receive arguments here */}) => <p>this is a React/Preact component</p>}
    ></Viewer>
  );
}
```

### Response
Renders the viewer component.
```

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

### Instantiate JSONCanvasViewer in vanilla JS/TS with Minimap

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/1-🚀-Quick-Start.md

Instantiate the viewer in vanilla JavaScript/TypeScript. Pass the container element and canvas data, and include the Minimap module in the modules array. You can instantiate multiple viewers to render multiple canvases.

```TypeScript
import { JSONCanvasViewer, Minimap } from 'json-canvas-viewer';
import canvasData from 'path/to/your.canvas';

new JSONCanvasViewer(
	{
		container: document.body, // The element to attach the viewer to
		canvas: canvasData, // The path to the canvas to load
	},
	[Minimap], // The modules to load
);
```

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

### Equivalent Options type with instances or constructors

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Shows that the Options type accepts either module instances or their constructors, making MyOptions1 and MyOptions2 equivalent. Use this when you need to define options types with modules in a flexible way.

```typescript
import { Minimap, MistouchPreventer } from "json-canvas-viewer";
import type { Options } from "json-canvas-viewer";

type MyOptions1 = Options<[Minimap, MistouchPreventer]>;
type MyOptions2 = Options<[typeof Minimap, typeof MistouchPreventer]>;
```

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

### Build-time canvas parsing with JSONCanvasViewerComponent

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/vue/README.md

Use build-time canvas parsing with a bundler (Vite) and the Vite plugin. Import the canvas file directly and pass it to the component. Wrap the component in <Suspense>; it is crucial for this to work.

```vue
<script setup>
import { JSONCanvasViewerComponent } from '@json-canvas-viewer/vue';
import canvas from 'path/to/your.canvas';
</script>

<template>
  <Suspense>
    <!-- Suspense is crucial -->
    <JSONCanvasViewerComponent :canvas="canvas" />
  </Suspense>
</template>
```

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

### Agent Prompt for json-canvas-viewer

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/README.md

Prompt template for AI agents (OpenCode, ClaudeCode, Cursor, or chat bots) to use `json-canvas-viewer` and decide between the `chimp` and `full` versions. Replace the placeholder with your requirements; the agent reads the linked documentation to help.

```markdown
I'm using `json-canvas-viewer`, a library to view JSON Canvas (from Obsidian) interactively in a browser. Read its documentations, figure out wether to use `chimp` version or `full` version, and help me with my requirements.

**Documentation**:

[Readme](https://github.com/hesprs/json-canvas-viewer/raw/refs/heads/main/README.md)
[Quick Start and React / Vue / Preact/Vite Integration](https://github.com/hesprs/json-canvas-viewer/raw/refs/heads/main/docs/1-%F0%9F%9A%80-Quick-Start.md)
[Construction Details](https://github.com/hesprs/json-canvas-viewer/raw/refs/heads/main/docs/2-%F0%9F%8F%97%EF%B8%8F-Construction-Details.md)
[Modules](https://github.com/hesprs/json-canvas-viewer/raw/refs/heads/main/docs/3-%F0%9F%A7%A9-Modules.md)
[Prerendering](https://github.com/hesprs/json-canvas-viewer/raw/refs/heads/main/docs/4-%F0%9F%96%87%EF%B8%8F-Prerendering.md)
[CSS Styling](https://github.com/hesprs/json-canvas-viewer/raw/refs/heads/main/docs/6-%F0%9F%8E%A8-CSS-Styling.md)

**Requirements**:

<!-- your requirements here -->
```

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

### Import Minimap module

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/3-🧩-Modules.md

Import the Minimap module from 'json-canvas-viewer' to enable the minimap feature.

```TypeScript
import { Minimap } from 'json-canvas-viewer';
```

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

### Constructor (Vanilla TypeScript)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Creates a new JSONCanvasViewer instance with a canvas, container, and optional node components.

```APIDOC
## Constructor (Vanilla TypeScript)

### Description
Creates a new JSONCanvasViewer instance with a canvas, container, and optional node components.

### Method
Constructor

### Endpoint
new Viewer(options)

### Parameters
#### Constructor Options
- **canvas** (JSONCanvas) - Required - The canvas object to display.
- **container** (HTMLElement) - Required - The DOM element to mount the viewer.
- **nodeComponents** (object) - Optional - Custom components for rendering nodes. Keys are node types (e.g., 'text'), values are functions receiving a context object with a `container` property.

### Request Example
```typescript
import canvas from 'path/to/your.canvas';
import { JSONCanvasViewer as Viewer } from 'json-canvas-viewer';

new Viewer({
    canvas,
    container: document.body,
    nodeComponents: {
        text: ({ container }) => {
            const content = document.createElement('div');
            content.textContent = 'this is an HTML element';
            container.appendChild(content);
        }
    }
});
```

### Response
No return value.
```

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

### load(options?)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Loads or reloads a canvas into the viewer. Can be used to load a new canvas on an existing viewer.

```APIDOC
## load(options?)

### Description
Loads or reloads a canvas into the viewer. Can be used to load a new canvas on an existing viewer.

### Method
load

### Endpoint
load(options?: { canvas?: JSONCanvas; attachments?: Record<string, string> })

### Parameters
#### Optional Parameters
- **options** (object) - Optional - Options for loading.
  - **canvas** (JSONCanvas) - Optional - The canvas object to load.
  - **attachments** (Record<string, string>) - Optional - Attachments associated with the canvas.

### Response
No return value.
```

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

### Use JSONCanvasViewer without Vite using fetchCanvas and parser

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/1-🚀-Quick-Start.md

Use the viewer without Vite. If your bundler supports JSON import, import the canvas as a JSON file; otherwise use fetchCanvas() to fetch and parse it. Pass the parser option for client-side parsing.

```TypeScript
import { JSONCanvasViewer, Minimap, fetchCanvas, parser } from 'json-canvas-viewer';

import canvas from 'path/to/your-canvas.json'; // if JSON import is supported
const canvas = await fetchCanvas('path/to/your-canvas.json'); // if JSON import is not supported

new JSONCanvasViewer({
	container: document.body, // The element to attach the viewer to
	canvas,
    parser,
});
```

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

### Constructor (Vue)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Renders the JSON Canvas Viewer as a Vue component with scoped slots for custom node components.

```APIDOC
## Constructor (Vue)

### Description
Renders the JSON Canvas Viewer as a Vue component with scoped slots for custom node components.

### Method
Component

### Endpoint
<Viewer />

### Parameters
#### Props
- **canvas** (JSONCanvas) - Required - The canvas object to display.

#### Slots
- **text** (scoped slot) - Optional - Receives arguments and renders custom content for text nodes.

### Request Example
```vue
<script setup lang="ts">
import canvas from 'path/to/your.canvas';
import { JSONCanvasViewerComponent as Viewer } from '@json-canvas-viewer/vue';
</script>

<template>
  <Suspense>
    <Viewer class="canvas-viewer" :canvas="canvas">
      <template #text="{/* you can receive arguments here */}">
        <p>This is a Vue component</p>
      </template>
    </Viewer>
  </Suspense>
</template>
```

### Response
Renders the viewer component.
```

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

### Dependency Injection - Service Providers List

Source: https://github.com/hesprs/json-canvas-viewer/wiki/5-🧑‍💻-Develop-a-Module

Lists the available service providers that can be injected into a module. These are exported from the 'internal' export of json-canvas-viewer and all framework builds.

```TypeScript
Controller,
DataManager,
InteractionHandler,
Renderer,
OverlayManager,
StyleManager
```

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

### Options interface for JSON Canvas Viewer constructor

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Defines the base Options interface for the JSON Canvas Viewer constructor, along with the Colors and Hook types. The container property is required; all others are optional. The nodeComponents keys are limited to 'text' | 'image' | 'audio' | 'video' | 'link' | 'markdown'.

```TypeScript
interface Options {
    container: HTMLElement;
    canvas?: JSONCanvas;
    theme?: 'light' | 'dark';
    attachments?: Record<string, string>;
    parser?: (markdown: string) => string | Promise<string>;
    shadowed?: boolean;
    loading?: 'normal' | 'lazy' | 'none';
    pointeract?: PointeractOptions;
    colors?: {
        light?: Colors;
        dark?: Colors;
    };
    nodeComponents?: {
        [Key: 'text' | 'image' | 'audio' | 'video' | 'link' | 'markdown']: (args: {
          container: HTMLDivElement;
	        content: string;
	        node: JSONCanvasNode;
	        onBeforeUnmount: Hook;
	        onActive: Hook;
	        onLoseActive: Hook;
        }) => void | Promise<void>;
    }
}

interface Colors {
    '0'?: string;
    '1'?: string;
    '2'?: string;
    '3'?: string;
    '4'?: string;
    '5'?: string;
    '6'?: string;
    dots?: string;
    text?: string;
    background?: string;
    'background-secondary'?: string;
    shadow?: string;
    border?: string;
}

type Hook<Args extends GeneralArray = []> = {
  (...args: Args): void;
  subs: Set<(...args: Args) => void>;
  subscribe(callback: (...args: Args) => void): void;
  unsubscribe(callback: (...args: Args) => void): void;
};
```

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

### Instantiate JSONCanvasViewer in vanilla TypeScript

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Use this snippet to instantiate the JSONCanvasViewer in a vanilla TypeScript environment. It imports a canvas file and the viewer class, then creates a new viewer instance with a custom HTML element for text nodes. The nodeComponents option allows you to override the default rendering for specific node types.

```TypeScript
import canvas from 'path/to/your.canvas';
import { JSONCanvasViewer as Viewer } from 'json-canvas-viewer';

new Viewer({
    canvas,
	container: document.body,
	nodeComponents: {
	    text: ({ container /* you can receive more arguments here */ }) => {
			const content = document.createElement('div');
			content.textContent = 'this is an HTML element';
			container.appendChild(parsedContentWrapper);
		}
	}
});
```

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

### renderToString

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/4-🖇️-Prerendering.md

The renderToString function is an exported async function that renders the canvas content to a string for prerendering. It accepts the same options as the main constructor and returns a promise resolving to the HTML string.

```APIDOC
## renderToString

### Description
Renders the canvas content to a string for prerendering. The returned string can be used as the `innerHTML` of a container element.

### Method
async function

### Endpoint
`renderToString(options)`

### Parameters
#### Options
- **canvas** (JSONCanvas) - Required - The canvas object to render.
- **attachments** (Record<string, string>) - Optional - A map of attachment identifiers to their content.
- **parser** ((markdown: string) => string | Promise<string>) - Optional - A custom markdown parser function.

### Returns
- **Promise<string>** - A promise that resolves to the rendered HTML string.

### Example
```typescript
const html = await renderToString({ canvas });
```
```

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

### renderToString function signature

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/4-🖇️-Prerendering.md

Defines the async renderToString function that takes a canvas and optional attachments and parser, returning a Promise of an HTML string. The options match the main constructor options.

```TypeScript
function renderToString(options: {
  canvas: JSONCanvas,
  attachments?: Record<string, string>,
  parser?: (markdown: string) => string | Promise<string>,
}): Promise<string>;
```

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

### JSONCanvasViewer public interface

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

This interface defines the public API of the JSONCanvasViewer instance. It includes properties for the DI container and options, methods for theme, disposal, loading, panning, zooming, and fullscreen, as well as hook methods for lifecycle events. Use this as a reference when customizing or interacting with the viewer.

```ts
interface JSONCanvasViewer {
  container: HTMLElement;
  options: JSONCanvasViewerOptions;
  changeTheme(theme?: 'dark' | 'light'): void;
  dispose(): void;
  load(options?: { canvas?: JSONCanvas; attachments?: Record<string, string> }): void;
  pan(delta: { x: number; y: number }): void;
  panToCoords(coords: { x: number; y: number }): void;
  refresh(): void;
  resetView(): void;
  toggleFullscreen(option?: 'enter' | 'exit'): void;
  zoom(factor: number): void;
  zoomToScale(scale: number): void;
  onStart: Hook;
  onRestart: Hook;
  onDispose: Hook;
  onRefresh: Hook;
  onResize: Hook<[number, number]>;
  onToggleFullscreen: Hook<['enter' | 'exit']>;
  onChangeTheme: Hook<['light' | 'dark']>;
  onNodeActive: Hook<[JSONCanvasNode]>;
  onNodeLosesActive: Hook<[JSONCanvasNode]>;
}
```

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

### Configure vite-plugin-json-canvas in vite.config

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/packages/vite/README.md

Add the plugin to your Vite configuration. The plugin uses marked as the default parser, which can be customized via marked.use() or by passing a custom parser function to canvas().

```TypeScript
import { defineConfig } from 'vite';
import canvas from 'vite-plugin-json-canvas';

export default defineConfig({
	plugins: [canvas()],
});
```

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

### Import MistouchPreventer module

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/3-🧩-Modules.md

Import the MistouchPreventer module from 'json-canvas-viewer' to prevent accidental canvas panning when scrolling.

```TypeScript
import { MistouchPreventer } from 'json-canvas-viewer';
```

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

### dispose()

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Cleans up and removes the viewer from the DOM.

```APIDOC
## dispose()

### Description
Cleans up and removes the viewer from the DOM.

### Method
dispose

### Endpoint
dispose()

### Parameters
None.

### Response
No return value.
```

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

### Define options type with modules

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Use this to define a type for the options object when you need to pass specific optional modules to the viewer without instantiating it. The type parameter accepts an array of module constructors or instances.

```ts
import { type Options, Minimap, MistouchPreventer } from 'json-canvas-viewer';
type MyOptions = Options<[Minimap, MistouchPreventer]>;
```

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

### Vue isPrerendering prop

Source: https://github.com/hesprs/json-canvas-viewer/wiki/4-🖇️-Prerendering

Vue component prop to enable prerendering.

```APIDOC
## Vue - isPrerendering prop

### Description
The Vue component supports prerendering natively. Set the `isPrerendering` prop to `true` to enable prerendering.

### Props
- **isPrerendering** (boolean) - Optional - When set to `true`, enables prerendering.
```

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

### refresh()

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Triggers a rerender of the viewer.

```APIDOC
## refresh()

### Description
Triggers a rerender of the viewer.

### Method
refresh

### Endpoint
refresh()

### Parameters
None.

### Response
No return value.
```

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

### resetView()

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Adjusts the scale and offsets so that the user can see all canvas content.

```APIDOC
## resetView()

### Description
Adjusts the scale and offsets so that the user can see all canvas content.

### Method
resetView

### Endpoint
resetView()

### Parameters
None.

### Response
No return value.
```

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

### BaseModule boilerplate

Source: https://github.com/hesprs/json-canvas-viewer/wiki/5-🧑‍💻-Develop-a-Module

Minimal boilerplate for a module in json-canvas-viewer. Extend BaseModule and pass constructor arguments to super. Provides access to this.container, this.options, this.onStart, this.onDispose, this.onRestart, and this.augment.

```TypeScript
import { BaseModule, type BaseArgs } from "json-canvas-viewer";

class MyModule extends BaseModule {
    constructor(...args: BaseArgs) {
        super(...args);
    }
}
```

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

### Use JSONCanvasViewerComponent in React/Preact

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Use this snippet to render the JSONCanvasViewer as a React or Preact component. It imports the component from the appropriate package and passes a custom React/Preact component for text nodes via the text prop. The canvas is imported from a local file.

```tsx
import canvas from 'path/to/your.canvas';
import { JSONCanvasViewerComponent as Viewer } from '@json-canvas-viewer/react'; // or '@json-canvas-viewer/preact'

export default function component() {
  return (
    <Viewer
      canvas={canvas}
      text={({/* you can receive arguments here */}) => <p>this is a React/Preact component</p>}
    ></Viewer>
  );
}
```

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

### zoom(factor)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Zooms the canvas by a specified factor.

```APIDOC
## zoom(factor)

### Description
Zooms the canvas by a specified factor.

### Method
zoom

### Endpoint
zoom(factor: number)

### Parameters
#### Required Parameters
- **factor** (number) - Required - The zoom factor.

### Response
No return value.
```

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

### panToCoords(coords)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Pans the canvas to the specified coordinates.

```APIDOC
## panToCoords(coords)

### Description
Pans the canvas to the specified coordinates.

### Method
panToCoords

### Endpoint
panToCoords(coords: { x: number; y: number })

### Parameters
#### Required Parameters
- **coords** (object) - Required - The target coordinates.
  - **x** (number) - Required - X coordinate.
  - **y** (number) - Required - Y coordinate.

### Response
No return value.
```

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

### zoomToScale(scale)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Zooms the canvas to a specified scale.

```APIDOC
## zoomToScale(scale)

### Description
Zooms the canvas to a specified scale.

### Method
zoomToScale

### Endpoint
zoomToScale(scale: number)

### Parameters
#### Required Parameters
- **scale** (number) - Required - The target scale.

### Response
No return value.
```

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

### pan(delta)

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Pans the canvas by the specified delta.

```APIDOC
## pan(delta)

### Description
Pans the canvas by the specified delta.

### Method
pan

### Endpoint
pan(delta: { x: number; y: number })

### Parameters
#### Required Parameters
- **delta** (object) - Required - The pan delta.
  - **x** (number) - Required - Horizontal pan distance.
  - **y** (number) - Required - Vertical pan distance.

### Response
No return value.
```

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

### JSONCanvasViewerComponent prerenderHtml prop

Source: https://github.com/hesprs/json-canvas-viewer/wiki/4-🖇️-Prerendering

React/Preact component prop for prerendering, allowing manual rendering to a string in server components.

```APIDOC
## JSONCanvasViewerComponent (React/Preact) - prerenderHtml prop

### Description
In React/Preact, the component supports a `prerenderHtml` prop that accepts a string for prerendering. This is necessary because React does not support asynchronous rendering.

### Usage Example
```tsx
import { JSONCanvasViewerComponent } from '@json-canvas-viewer/react'; // or '@json-canvas-viewer/preact'
import canvas from 'path/to/your.canvas';

// a server component
export default async function App() {
  const html = await renderToString({ canvas });

  return (
    <main>
      {/* ... your other components */}
      <JSONCanvasViewerComponent prerenderHtml={html} canvas={canvas} />
    </main>
  );
}
```

### Props
- **prerenderHtml** (string) - Required - The pre-rendered HTML string to display.
- **canvas** (JSONCanvas) - Required - The canvas object.
```

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

### Use JSONCanvasViewerComponent in Vue

Source: https://github.com/hesprs/json-canvas-viewer/wiki/2-🏗️-Construction-Details

Use this snippet to render the JSONCanvasViewer as a Vue component. It imports the component from '@json-canvas-viewer/vue' and uses a scoped slot named 'text' to provide a custom Vue component for text nodes. The canvas is imported from a local file and passed via the :canvas prop.

```vue
<script setup lang="ts">
import canvas from 'path/to/your.canvas';
import { JSONCanvasViewerComponent as Viewer } from '@json-canvas-viewer/vue';
</script>

<template>
  <Suspense>
    <Viewer class="canvas-viewer" :canvas="canvas">
      <template #text="{/* you can receive arguments here */}">
        <p>This is a Vue component</p>
      </template>
    </Viewer>
  </Suspense>
</template>
```

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

### Disable markdown parsing in vite-plugin-json-canvas

Source: https://github.com/hesprs/json-canvas-viewer/blob/main/docs/1-🚀-Quick-Start.md

Disable markdown parsing in the Vite plugin by passing an identity function `(md) => md`. The plugin accepts any markdown parser that inputs and outputs a string.

```TypeScript
export default defineConfig({
	plugins: [canvas((md) => md)],
});
```
Tokens:
Raw