@bendyline/docblocks-react

React components for DocBlocks — the complete editor shell (file explorer, workspace picker, app menu, export pipeline) plus the individual components and hooks it's built from. This is the package the DocBlocks web app and desktop renderer both mount.

Installation

npm install @bendyline/docblocks-react react react-dom
npm install --save-dev @types/react @types/react-dom

Peer dependencies: React 18 or 19. TypeScript consumers must install the matching @types/react major (and normally @types/react-dom); the React type peer is optional so JavaScript-only consumers do not need type packages. The DocBlocks core (@bendyline/docblocks) and the Squisq editor packages are regular dependencies and install automatically.

Usage

import { DocBlocksShell } from '@bendyline/docblocks-react';
import '@bendyline/docblocks-react/styles';

function App() {
  return <DocBlocksShell theme="auto" />;
}

The video-export worker uses module chunks. Vite consumers must retain the same worker setting used by the DocBlocks site and desktop renderer:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({ worker: { format: 'es' } });

Formula grids can opt into the full IronCalc engine through the separately built calculation entry point. Publish @ironcalc/wasm/wasm_bg.wasm at a same-origin URL and keep the factory at module scope so the engine remains lazy and reusable:

import { createDocBlocksCalcEngineFactory } from '@bendyline/docblocks-react/calculation';

const calcEngineFactory = createDocBlocksCalcEngineFactory({
  wasmSource: '/ironcalc/wasm_bg.wasm',
});

function App() {
  return <DocBlocksShell calcEngineFactory={calcEngineFactory} />;
}

Components

DocBlocksShell

The canonical DocBlocks experience in one component — file explorer, workspace picker, app menu, the Squisq editor with its Editor / Markdown / Play views, and the export pipeline.

<DocBlocksShell theme="auto" logoUrl="/logo.png" />

• theme — 'light' | 'dark' | 'auto' (auto follows prefers-color-scheme)
• logoUrl — brand mark for the app menu button
• calcEngineFactory — optional lazy calculation backend; use the calculation entry point above to enable IronCalc formulas
• ffmpegWasm — optional same-origin ffmpeg core URLs; supplying them enables the built-in Animated GIF flow on cross-origin-isolated hosts. No first-party surface supplies this. The @ffmpeg/core WebAssembly build is GPL-2.0-or-later, which cannot be reconciled with Apple's App Store terms, so it was removed from every DocBlocks distribution. The prop remains for hosts that bring their own encoder
• showCodeCopyButton — shows Copy controls on ordinary fenced code blocks (default: true; Mermaid fences remain diagrams)
• onCopyCode — optional clipboard adapter for native hosts; browser hosts fall back to navigator.clipboard.writeText

Storage is abstracted behind the byte-authoritative FileSystemProviderV2 contract from @bendyline/docblocks/filesystem: browser-local (IndexedDB), native folders (File System Access API), transient memory workspaces, or the Electron host. Built-in compatibility facades expose it as provider.v2; first-party shell and file-tree operations are v2-first.

FileExplorer / FileTreeNode

File tree browser with inline create (file + folder), rename, and delete. It follows filesystem watch events automatically and re-reads the visible tree when a browser surface resumes. Long names truncate gracefully.

WorkspacePicker

Dropdown for switching between workspaces, creating new ones, and opening local folders, plus the per-workspace settings dialog (rename, download, remove, version-history overrides).

AppMenu

Top-left brand menu with the app-wide Settings dialog (theme preference, global version-history default), optional "Back up all workspaces," a Help group (keyboard shortcuts, documentation), and the About dialog.

ExportToolbarControls / ExportDialog

Consumers that need the export pipeline without the complete shell can use the public, independently built entry point:

import {
  DEFAULT_OPTIONS,
  ExportDialog,
  buildExportFilename,
  runExport,
} from '@bendyline/docblocks-react/export';

The shell overflow also offers Share link with content embedded. It creates a bounded #shared(<base64>) URL containing a compressed, Markdown-only copy and an optional initial Use mode. Opening the URL creates a session-only workspace; generated links warn after 4,096 characters and are capped at 32,768 characters.

The export flow: quick re-export of the last configuration plus the full dialog — format (PDF, Word, PowerPoint, EPUB, HTML, Markdown), visual theme, and page size. Video export is available wherever WebCodecs is, and uses the MIT-licensed mp4-muxer. A host that supplies ffmpegWasm additionally exposes Animated GIF with timing, orientation, captions, looping, and color controls; no first-party surface does. Animated GIF remains available from the CLI and MCP, which use a system FFmpeg binary rather than a distributed one.

Rendered HTML and HTML ZIP exports include Copy controls for ordinary fenced code blocks; Mermaid fences remain diagrams.

Hooks

useDocumentSession(delay?)

React binding for the revisioned DocumentSession. Active-document writes, transitions, conflicts, and close preparation must flow through this session; there is intentionally no independent autosave hook.

useFileTree(provider)

File tree state management over any v2-capable provider — returns the tree, selection, and explicit create/move/remove functions, with a temporary v1 fallback for external providers.

Styles

import '@bendyline/docblocks-react/styles';

One explicit stylesheet import covers the Squisq editor and all DocBlocks components in both themes. Theme fonts are supplied by the host application; this package does not bundle fonts.

Where new UI belongs

Cross-surface UI that lives inside the shell chrome (file tree, workspace picker, app menu, export dialog) belongs here. The VS Code extension is the deliberate exception — its webview mounts Squisq's EditorShell directly because VS Code provides the file explorer, workspace, and theme itself.

License

MIT