@wix/ricos 11.21.3 → 11.22.0

package/dist/docs/api-docs-reference.cjs

@@ -1,7 +1,7 @@
 'use strict';
 exports.apiDocsSections = {
   "intro": "# @wix/ricos\n\nRicos is the Rich Content solution for Wix — used both internally and in headless environments. It provides three core building blocks that can be used together or independently:\n\n- **RicosEditor** — a full-featured WYSIWYG editor with an extensible plugin system\n- **RicosViewer** — a read-only renderer for displaying rich content\n- **RicosDocument** — the content data model (JSON) that flows between editor and viewer.\n\n<svg viewBox=\"0 0 620 260\" xmlns=\"http://www.w3.org/2000/svg\" style=\"max-width:620px;margin:24px auto;display:block\">\n  <style>\n    .box { fill: #f8fafc; stroke: #94a3b8; stroke-width: 2; rx: 12; }\n    .ellipse { fill: #f8fafc; stroke: #94a3b8; stroke-width: 2; }\n    .label { font-family: ui-monospace, monospace; font-size: 18px; fill: #1e293b; text-anchor: middle; dominant-baseline: central; }\n    .arrow { fill: none; stroke: #94a3b8; stroke-width: 1.5; marker-end: url(#arrowhead); }\n  </style>\n  <defs><marker id=\"arrowhead\" markerWidth=\"8\" markerHeight=\"6\" refX=\"8\" refY=\"3\" orient=\"auto\"><polygon points=\"0 0, 8 3, 0 6\" fill=\"#94a3b8\"/></marker></defs>\n  <rect class=\"box\" x=\"20\" y=\"120\" width=\"200\" height=\"100\"/>\n  <text class=\"label\" x=\"120\" y=\"170\">RicosEditor</text>\n  <rect class=\"box\" x=\"400\" y=\"120\" width=\"200\" height=\"100\"/>\n  <text class=\"label\" x=\"500\" y=\"170\">RicosViewer</text>\n  <ellipse class=\"ellipse\" cx=\"310\" cy=\"55\" rx=\"120\" ry=\"40\"/>\n  <text class=\"label\" x=\"310\" y=\"55\">RicosDocument</text>\n  <line class=\"arrow\" x1=\"200\" y1=\"130\" x2=\"260\" y2=\"85\"/>\n  <line class=\"arrow\" x1=\"270\" y1=\"95\" x2=\"215\" y2=\"135\"/>\n  <line class=\"arrow\" x1=\"350\" y1=\"85\" x2=\"420\" y2=\"130\"/>\n</svg>\n\n```bash\nnpm i @wix/ricos\n```\n\nAll three are exported from `@wix/ricos`:\n\n```tsx\nimport { RicosEditor, RicosViewer, type RicosDocument } from '@wix/ricos';\n```\n\n## Quick Start\n\n### Viewer\n\n```tsx widget\nimport '@wix/ricos/css/plugin-image-viewer.global.css';\nimport '@wix/ricos/css/ricos-viewer.global.css';\nimport type { RicosDocument } from '@wix/ricos';\nimport { pluginImageViewer, RicosViewer } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  return <RicosViewer content={content} plugins={[pluginImageViewer()]} />;\n  // @essential-end\n};\n\nconst content: RicosDocument = {\n  nodes: [\n    {\n      type: 'PARAGRAPH',\n      id: 'p1',\n      nodes: [\n        {\n          type: 'TEXT',\n          id: '',\n          nodes: [],\n          textData: { text: 'A read-only Ricos document with an image:', decorations: [] },\n        },\n      ],\n    },\n    {\n      type: 'IMAGE',\n      id: 'img1',\n      nodes: [],\n      imageData: {\n        containerData: {\n          width: { size: 'CONTENT' },\n          alignment: 'CENTER',\n          textWrap: true,\n        },\n        image: {\n          src: { url: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg' },\n          width: 5120,\n          height: 3413,\n        },\n        altText: 'A tree during sunset.',\n      },\n    },\n  ],\n};\n```\n\n### Editor\n\n```tsx widget\nimport type { RicosDocument, RicosEditorType } from '@wix/ricos';\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  const editorRef = React.useRef<RicosEditorType>(null);\n\n  // oxlint-disable-next-line no-alert\n  const handlePublish = async () => {\n    // @essential-start\n    const document = await editorRef.current?.prePublish();\n    alert(`Publishing ${document?.nodes.length ?? 0} nodes`);\n    // @essential-end\n  };\n\n  return (\n    // @essential-start\n    <>\n      <RicosEditor\n        ref={editorRef}\n        initialContent={initialContent}\n        plugins={[pluginImage()]}\n        placeholder={'Edit me — drag an image in or use the toolbar'}\n      />\n      <button onClick={handlePublish} type=\"button\">\n        Publish\n      </button>\n    </>\n    // @essential-end\n  );\n};\n\nconst initialContent: RicosDocument = {\n  nodes: [\n    {\n      type: 'PARAGRAPH',\n      id: 'p1',\n      nodes: [\n        {\n          type: 'TEXT',\n          id: '',\n          nodes: [],\n          textData: { text: 'An editable Ricos document with an image.', decorations: [] },\n        },\n      ],\n    },\n    {\n      type: 'IMAGE',\n      id: 'img1',\n      nodes: [],\n      imageData: {\n        containerData: {\n          width: { size: 'CONTENT' },\n          alignment: 'CENTER',\n          textWrap: true,\n        },\n        image: {\n          src: { url: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg' },\n          width: 5120,\n          height: 3413,\n        },\n        altText: 'A tree during sunset.',\n      },\n    },\n  ],\n};\n```\n\n",
-  "editor": "### Basic Setup\n\n`RicosEditor` needs an authenticated context to load plugins, upload media, and resolve relative links. Pick the variant matching your hosting environment.\n\n#### Headless: pass a `wixClient`\n\nWhen you own the React tree and have an `@wix/sdk` client, pass it directly. The editor uses it for every authenticated request:\n\n```tsx widget\nimport { createClient, OAuthStrategy } from '@wix/sdk';\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nconst wixClient = createClient({\n  modules: {},\n  auth: OAuthStrategy({ clientId: 'YOUR_CLIENT_ID' }),\n});\n\nexport default () => (\n  // @essential-start\n  <RicosEditor\n    wixClient={wixClient}\n    baseUrl=\"https://www.example.com/my-site\"\n    plugins={[pluginImage()]}\n    placeholder=\"Type or insert an image…\"\n  />\n  // @essential-end\n);\n```\n\n#### In-Wix: pass an `instance` (and `msid`)\n\nWhen the editor renders inside a Wix-served page, your runtime usually already has a per-session `instance` token and the site's `msid`. Pass them and Ricos builds its own client internally:\n\n```tsx widget\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default ({ instance, msid }: { instance: string; msid: string }) => (\n  // @essential-start\n  <RicosEditor\n    instance={instance}\n    msid={msid}\n    baseUrl=\"https://www.example.com/my-site\"\n    plugins={[pluginImage()]}\n    placeholder=\"Type or insert an image…\"\n  />\n  // @essential-end\n);\n```\n\n#### Always pass `baseUrl`\n\n`baseUrl` is the public URL of the site that owns the content. It's used by link decorations, button plugins, gallery items, and vertical embeds to resolve page-relative hrefs (`/about` → `https://www.example.com/my-site/about`).\n\nThe in-Wix flow can auto-fetch this from `/_api/ricos-site-pages/base-url`, but in any headless or cross-origin context you must pass it explicitly — without it, page-relative links in your content render as raw paths.\n\n### Ricos Editor Props\n\n#### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">RicosEditorProps</span>\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> RicosEditorProps</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>plugins</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#editorpluginoptions\"><span class=\"font-mono\">EditorPluginOptions</span></a>[]</code></dt>\n<dd><p>Array of editor plugins to enable. Each plugin adds editing capabilities (e.g., image, video, table).</p></dd>\n<dt><code><strong>onChange</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#oncontentchangefunction\"><span class=\"font-mono\">OnContentChangeFunction</span></a></code></dt>\n<dd><p>Fires only when document content changes (not on selection changes).</p></dd>\n<dt><code><strong>onSelectionChange</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#onselectionchangefunction\"><span class=\"font-mono\">OnSelectionChangeFunction</span></a></code></dt>\n<dd><p>Fires when the selection/cursor position changes (including during edits).</p></dd>\n<dt><code><strong>placeholder</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Placeholder text displayed when the editor is empty.</p></dd>\n</dl>\n\n<div class=\"pl-4 border-l-2 border-slate-200 mb-4\">\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  return <RicosEditor placeholder={'Type here!'} />;\n  // @essential-end\n};\n```\n\n</div>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>toolbars</strong><span class=\"text-slate-400\">?</span>: <a href=\"#toolbarsconfig\"><span class=\"font-mono\">ToolbarsConfig</span></a></code></dt>\n<dd><p>Toolbars configuration — controls the text formatting toolbar, insert plugin toolbars, plugin context toolbars and the quick-actions menu.</p></dd>\n<dt><code><strong>onBusyChange</strong><span class=\"text-slate-400\">?</span>: (isBusy: boolean) =&gt; void</code></dt>\n<dd><p>Callback fired when the editor transitions between busy and idle states (e.g., during media uploads).</p></dd>\n<dt><code><strong>maxTextLength</strong><span class=\"text-slate-400\">?</span>: number</code></dt>\n<dd><p>Maximum number of text characters allowed in the editor. When the limit is reached, further text input is ignored and paste actions are canceled if the result would exceed the limit.</p></dd>\n<dt><code><strong>sideBlockComponent</strong><span class=\"text-slate-400\">?</span>: FC&lt;{         id: string;     }&gt;</code></dt>\n<dd><p>A React component rendered as a side block alongside the editor content. Receives the block `id` as a prop.</p></dd>\n<dt><code><strong>commands</strong><span class=\"text-slate-400\">?</span>: any[]</code></dt>\n<dd><p>Custom commands to register with the editor.</p></dd>\n<dt><code><strong>historySettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#historysettings\"><span class=\"font-mono\">HistorySettings</span></a></code></dt>\n<dd><p>Settings for undo/redo history.</p></dd>\n<dt><code><strong>onLoad</strong><span class=\"text-slate-400\">?</span>: (editor: any) =&gt; void</code></dt>\n<dd><p>Callback fired when the editor finishes loading and is ready for interaction.</p></dd>\n<dt><code><strong>autofocus</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#focusposition\"><span class=\"font-mono\">FocusPosition</span></a></code></dt>\n<dd><p>Controls initial cursor/focus position when the editor mounts.</p></dd>\n<dt><code><strong>container</strong><span class=\"text-slate-400\">?</span>: HTMLElement | (() =&gt; HTMLElement | null)</code></dt>\n<dd><p>HTML element or factory function that returns the container element for rendering editor popovers and modals.</p></dd>\n<dt><code><strong>initialContent</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricosdocument\"><span class=\"font-mono\">RicosDocument</span></a></code></dt>\n<dd><p>Initial content for the editor. Only used during initialization — not a controlled value.</p></dd>\n<dt><code><strong>keyboardShortcuts</strong><span class=\"text-slate-400\">?</span>: any[]</code></dt>\n<dd><p>Custom keyboard shortcuts to register with the editor.</p></dd>\n<dt><code><strong>loadingPlaceholder</strong><span class=\"text-slate-400\">?</span>: React.ReactNode</code></dt>\n<dd><p>The placeholder to be displayed while the editor is loading.</p></dd>\n<dt><code><strong>tabFocusBehavior</strong><span class=\"text-slate-400\">?</span>: 'edit' | 'container'</code></dt>\n<dd><p>Controls focus behavior when tabbing into the editor: - `'edit'`: (default) Immediately enables typing when editor receives keyboard focus. - `'container'`: Shows focus ring but requires Enter/key press to start editing.</p>\n<p>Default: <code>'edit'</code></p></dd>\n<dt><code><strong>colorManager</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#colorpalettemanager\"><span class=\"font-mono\">ColorPaletteManager</span></a></code></dt>\n<dd><p>Unified color manager for sharing custom colors across all plugins.</p></dd>\n<dt><code><strong>modalSettings</strong><span class=\"text-slate-400\">?</span>: ModalSettings</code></dt>\n<dd></dd>\n<dt><code><strong>pickMedia</strong><span class=\"text-slate-400\">?</span>: _PublicPickMedia</code></dt>\n<dd><p>Pick media implementation used by media-related plugins (e.g., image, gallery).</p></dd>\n<dt><code><strong>visitorUploads</strong><span class=\"text-slate-400\">?</span>: _VisitorUploads</code></dt>\n<dd><p>Visitor upload settings used by file-upload-capable plugins.</p></dd>\n<dt><code><strong>fileUploadSizeLimit</strong><span class=\"text-slate-400\">?</span>: number</code></dt>\n<dd><p>Maximum file size limit (in bytes) for uploads.</p></dd>\n<dt><code><strong>htmlAttributes</strong><span class=\"text-slate-400\">?</span>: {         autoCapitalize?: string;         spellCheck?: boolean;         autoComplete?: string;         autoCorrect?: string;         tabIndex?: number;         ariaLabel?: string;     }</code></dt>\n<dd><p>HTML attributes applied to the editor's content-editable element.</p></dd>\n<dt><code><strong>isMobile</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, renders in mobile-optimized mode.</p></dd>\n<dt><code><strong>generalLinkSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#generallinksettings\"><span class=\"font-mono\">GeneralLinkSettings</span></a></code></dt>\n<dd><p>Link settings applied globally to all linkable plugins.</p></dd>\n<dt><code><strong>locale</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Two-letter locale code (e.g., `'en'`, `'he'`). Determines the language and text direction of modals and settings.</p></dd>\n<dt><code><strong>localeContent</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Locale for content, when different from UI locale. If not defined, `locale` is used.</p></dd>\n<dt><code><strong>onError</strong><span class=\"text-slate-400\">?</span>: (error: string) =&gt; void</code></dt>\n<dd><p>Callback fired when an error occurs in a Ricos component.</p></dd>\n<dt><code><strong>theme</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/theming#ricostheme\"><span class=\"font-mono\">RicosTheme</span></a></code></dt>\n<dd><p>Theme configuration for colors, fonts, and custom styles.</p></dd>\n<dt><code><strong>textAlignment</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#textalignment\"><span class=\"font-mono\">TextAlignment</span></a></code></dt>\n<dd><p>Default text alignment direction.</p></dd>\n<dt><code><strong>onAtomicBlockFocus</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#onatomicblockfocus\"><span class=\"font-mono\">onAtomicBlockFocus</span></a></code></dt>\n<dd><p>Callback fired when an atomic block (plugin) receives focus.</p></dd>\n<dt><code><strong>iframeSandboxDomain</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Domain used to render UGC source code in an isolated sandboxed iframe.</p></dd>\n<dt><code><strong>textWrap</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, wraps text around left/right-aligned plugins.</p></dd>\n<dt><code><strong>responsiveBehavior</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#responsivebehavior\"><span class=\"font-mono\">ResponsiveBehavior</span></a></code></dt>\n<dd><p>What responsive styles (narrow layouts, stacked columns, smaller paddings) respond to: - `'container'`: (default) the editor or viewer width, through CSS container queries. - `'viewport'`: the window width, through media queries. Ricos then declares no CSS containers, so `cqw` units in host styles (such as site theme fonts) resolve against the host's own containers.</p>\n<p>Default: <code>'container'</code></p></dd>\n<dt><code><strong>debugMode</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#debugmode\"><span class=\"font-mono\">DebugMode</span></a>[]</code></dt>\n<dd><p>Debug mode flags for enabling development-time diagnostics.</p></dd>\n<dt><code><strong>environment</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#environment\"><span class=\"font-mono\">Environment</span></a></code></dt>\n<dd><p>Theme variant to apply: - `'businessManager'`: BM theme is applied and cannot be overridden. - `'liveSite'`: liveSite theme is applied and can be overridden via `theme`.   'liveSite'</p></dd>\n<dt><code><strong>baseUrl</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Base URL of the site, used to resolve page-relative URLs. Used by links, buttons, gallery items, and vertical embeds to construct full hrefs from relative paths (e.g., `/my-page` → `https://example.com/my-site/my-page`).  If not provided, fetched automatically from `/_api/ricos-site-pages/base-url`.</p></dd>\n<dt><code><strong>biSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#bisettings\"><span class=\"font-mono\">BISettings</span></a></code></dt>\n<dd><p>Business intelligence configuration for analytics and tracking.</p></dd>\n<dt><code><strong>wixClient</strong><span class=\"text-slate-400\">?</span>: WixClient</code></dt>\n<dd><p>Authenticated `WixClient` from `@wix/sdk`. When provided, takes priority over `instance` for authorizing every request the editor makes (media uploads, link previews, etc.). Use this in headless apps where you own the React tree.</p></dd>\n<dt><code><strong>instance</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Per-session Wix instance token. Used when no `wixClient` is provided — Ricos builds an internal client from it. Typically set by Wix-served host pages.</p></dd>\n<dt><code><strong>msid</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Metasite ID. Scopes storage and CDN traffic to the owning site when no `wixClient` is given.</p></dd>\n<dt><code><strong>shouldNormalizeRichContent</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, normalises rich content via `normalizeRicosDocument` before rendering. Set to `false` to skip normalisation when content is already known to be valid.   true</p></dd>\n<dt><code><strong>mediaSettings</strong><span class=\"text-slate-400\">?</span>: MediaSettings</code></dt>\n<dd><p>Media-upload, capture, and resolution settings shared across media plugins.</p></dd>\n<dt style=\"opacity: 0.5;\"><code><strong>linkSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#linksettings\"><span class=\"font-mono\">LinkSettings</span></a></code></dt>\n<dd><p><em>Deprecated.</em> Use `generalLinkSettings` instead.</p></dd>\n<dt><code><strong>preserveDomOnUnmount</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>Keep the editor's DOM alive across a transient React unmount instead of tearing it down and rebuilding it on remount. Lets the host preserve editor state (and avoid flicker) when the editor is briefly unmounted/remounted.   false</p></dd>\n<dt style=\"opacity: 0.5;\"><code><strong>experiments</strong><span class=\"text-slate-400\">?</span>: AvailableExperiments</code></dt>\n<dd><p><em>Deprecated.</em> Not used at runtime.</p></dd>\n</dl>\n\n### Ricos Editor Imperative API\n\n#### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">RicosEditorAPI</span>\n\nImperative API for controlling a mounted `RicosEditor`. Accessed via a React ref — `const editorRef = useRef<RicosEditorType>(null)` — and read inside event handlers (publish flows, programmatic content swaps, focus/undo/redo controls). For UI that needs to react to editor state in render — toolbar enable/disable, undo-stack indicators — prefer the reactive hooks (`useToolbarProps`, `useUndoState`) over polling these methods.\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> RicosEditorAPI</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>focus</strong>: (focusPosition?: FocusPosition): void;</code></dt>\n<dd><p>Focuses the editor. Optionally moves the cursor to `focusPosition`.</p></dd>\n<dt><code><strong>blur</strong>: (): void;</code></dt>\n<dd><p>Removes focus from the editor.</p></dd>\n<dt><code><strong>undo</strong>: (): void;</code></dt>\n<dd><p>Undoes the last editor action.</p></dd>\n<dt><code><strong>redo</strong>: (): void;</code></dt>\n<dd><p>Redoes the last undone action.</p></dd>\n<dt><code><strong>getContent</strong>: (postId?: string, forPublish?: boolean, shouldRemoveErrorBlocks?: boolean): Promise&lt;RicosDocument&gt;;</code></dt>\n<dd><p>Returns the current content as a `RicosDocument`. Resolves after any pending async operations.</p></dd>\n<dt><code><strong>getContentPromise</strong>: (props: {         flush?: boolean;         publishId?: string;     } | undefined): Promise&lt;RicosDocument&gt;;</code></dt>\n<dd><p>Returns a promise of the current content. `publishId` — used for BI (`onPublish` event), set it when called before publishing. `flush` — triggers editor blur to force pending changes (e.g., Android composition mode) before reading content.</p></dd>\n<dt><code><strong>getContentTraits</strong>: (): {         isEmpty: boolean;         isContentChanged: boolean;         isLastChangeEdit: boolean;     };</code></dt>\n<dd><p>Returns content traits: whether the editor is empty, content has changed, and the last change was an edit.</p></dd>\n<dt><code><strong>setContent</strong>: (content: RicosDocument): void;</code></dt>\n<dd><p>Replaces the editor content. Imperative replacement for the removed `injectedContent` prop.</p></dd>\n<dt><code><strong>getEditorContainer</strong>: (): HTMLElement | undefined;</code></dt>\n<dd><p>Returns the DOM element wrapping the editor's content-editable, if mounted.</p></dd>\n<dt><code><strong>openModal</strong>: (options: {         type: 'AI_IMAGE' | 'INLINE_AI' | 'SHORTCUTS_SHEET' | 'AI_WIDGET';     }) =&gt; void</code></dt>\n<dd><p>Opens a built-in modal (AI image generation, inline AI, keyboard shortcuts sheet, or AI widget).</p></dd>\n<dt><code><strong>useToolbarProps</strong>: (type: UseToolbarPropsType): ToolbarPropsResult;</code></dt>\n<dd><p>Subscribe to the reactive button list for a toolbar. Re-runs on selection and content changes, so consumers rendering a custom toolbar stay in sync automatically. Must be called inside a React component.</p></dd>\n<dt><code><strong>useInlineAiState</strong>: (invocationId: string) =&gt; unknown</code></dt>\n<dd></dd>\n<dt><code><strong>prePublish</strong>: (): Promise&lt;RicosDocument&gt;;</code></dt>\n<dd><p>Runs plugin pre-publish hooks (e.g. poll sync) and returns the content.</p></dd>\n<dt><code><strong>useUndoState</strong>: () =&gt; {         isUndoStackEmpty: boolean;         isRedoStackEmpty: boolean;     }</code></dt>\n<dd><p>Reactive undo/redo state. Must be called inside a React component.</p></dd>\n</dl>\n\n```tsx widget\nimport type { RicosDocument, RicosEditorType } from '@wix/ricos';\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  const editorRef = React.useRef<RicosEditorType>(null);\n\n  // @essential-start\n  const UndoButtons = () => {\n    const { isUndoStackEmpty, isRedoStackEmpty } = editorRef.current?.useUndoState() ?? {\n      isUndoStackEmpty: true,\n      isRedoStackEmpty: true,\n    };\n    return (\n      <>\n        <button onClick={() => editorRef.current?.undo()} disabled={isUndoStackEmpty} type=\"button\">\n          Undo\n        </button>\n        <button onClick={() => editorRef.current?.redo()} disabled={isRedoStackEmpty} type=\"button\">\n          Redo\n        </button>\n      </>\n    );\n  };\n\n  const handlePublish = async () => {\n    const document = await editorRef.current?.prePublish();\n    alert(`Publishing ${document?.nodes.length ?? 0} nodes`);\n  };\n\n  const handleReset = () => editorRef.current?.setContent(initialContent);\n\n  return (\n    <>\n      <RicosEditor\n        ref={editorRef}\n        initialContent={initialContent}\n        plugins={[pluginImage()]}\n        placeholder=\"Edit me — drag an image in or use the toolbar\"\n      />\n      <UndoButtons />\n      <button onClick={handlePublish} type=\"button\">\n        Publish\n      </button>\n      <button onClick={handleReset} type=\"button\">\n        Reset\n      </button>\n    </>\n  );\n  // @essential-end\n};\n\nconst initialContent: RicosDocument = {\n  nodes: [\n    {\n      type: 'PARAGRAPH',\n      id: 'p1',\n      nodes: [\n        {\n          type: 'TEXT',\n          id: '',\n          nodes: [],\n          textData: { text: 'Edit, undo, publish, reset.', decorations: [] },\n        },\n      ],\n    },\n    {\n      type: 'IMAGE',\n      id: 'img1',\n      nodes: [],\n      imageData: {\n        containerData: {\n          width: { size: 'CONTENT' },\n          alignment: 'CENTER',\n          textWrap: true,\n        },\n        image: {\n          src: { url: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg' },\n          width: 5120,\n          height: 3413,\n        },\n        altText: 'A tree during sunset.',\n      },\n    },\n  ],\n};\n```\n\n\n## Toolbars\n\nRicos ships with four consumer-facing toolbars, all configured through a single `toolbars` prop on `RicosEditor`:\n\n- **Text toolbar** — formatting controls shown when the user selects text (floating by default, or rendered into a container)\n- **Insert toolbar** — the inline plus button on empty lines and the footer plugin bar\n- **Plugin toolbar** — the bubble that appears when a plugin node or decoration (e.g. a link) is selected\n- **Quick actions** — the slash-command menu triggered by typing `/`\n\nEach is optional — omit a section to keep its default behaviour. Fields are grouped by concept, not by the low-level rendering variant, so the same config drives desktop and mobile without platform-specific branches.\n\n##### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">ToolbarsConfig</span>\n\nConfiguration for the editor's consumer-facing toolbars — text formatting, insert plugin menus, plugin context bubbles and quick actions.  Fields are grouped by concept (`text`, `insert`, `plugin`, `quickActions`) so the same config drives desktop and mobile without platform-specific branching.\n\n<pre class=\"block py-4 px-4 my-2 overflow-auto rounded border-none bg-slate-200 font-mono text-sm leading-6 tracking-wide text-slate-900\"><code><span class=\"text-blue-700\">type</span> ToolbarsConfig = {     text?: TextToolbarConfig;     insert?: InsertToolbarConfig;     plugin?: PluginToolbarConfig;     quickActions?: <a href=\"#quickactionsconfig\"><span class=\"font-mono\">QuickActionsConfig</span></a>; }</code></pre>\n\n### Text toolbar\n\nTwo mutually exclusive modes: `floating` (above the selection) and `static` (rendered into a DOM container the consumer owns).\n\n#### Floating mode with custom buttons\n\nFilter the default button list and register your own components:\n\n```tsx widget\nimport { FORMATTING_BUTTONS, RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Floating text toolbar with:\n * - `buttons` callback filtering out CODE_BLOCK from defaults and appending\n *   a custom button name\n * - `customButtons` registering a React component for that name\n *\n * The callback receives `defaultButtons` already resolved to the platform's\n * default text button ids.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        text: {\n          mode: 'floating',\n          buttons: ({ defaultButtons }) => [\n            ...defaultButtons.filter(id => id !== FORMATTING_BUTTONS.CODE_BLOCK),\n            'MY_INFO',\n          ],\n          customButtons: {\n            MY_INFO: {\n              component: () => (\n                // oxlint-disable-next-line\n                <div onClick={() => console.log('info!')} style={{ padding: '0 8px' }}>\n                  ℹ︎\n                </div>\n              ),\n            },\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'בחר טקסט כדי לראות את סרגל הכלים הצף!'\n          : 'Select text to see the floating toolbar!'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\nThe `buttons` callback receives `defaultButtons` — the platform-resolved list of built-in button ids. Return the desired order; unknown ids are dropped silently. Use `customButtons` to register React components keyed by the ids you reference.\n\n#### Static mode\n\nRender the text toolbar into a container outside the editor — useful when the page already has a fixed toolbar area:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Static text toolbar rendered into a container the consumer owns.\n *\n *   toolbars: { text: { mode: 'static', container, alignment: 'left' } }\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  const [toolbarContainer, setToolbarContainer] = React.useState<HTMLDivElement | null>(null);\n\n  return (\n    <div style={{ display: 'grid', gap: 16 }}>\n      <div\n        ref={setToolbarContainer}\n        style={{ minHeight: 48, border: '1px dashed #ccc', padding: 8 }}\n      />\n      {/* @essential-start */}\n      <RicosEditor\n        initialContent={content}\n        plugins={editorPlugins}\n        toolbars={\n          toolbarContainer\n            ? { text: { mode: 'static', container: toolbarContainer, alignment: 'left' } }\n            : undefined\n        }\n        onChange={setContent}\n        placeholder={locale === 'he' ? 'הוסף קצת טקסט!' : 'Add some text!'}\n        isMobile={isMobile}\n        environment={environment}\n        locale={locale}\n        localeContent={localeContent}\n      />\n      {/* @essential-end */}\n    </div>\n  );\n};\n```\n\nSet `container` to any `HTMLElement`. `alignment` controls horizontal positioning inside that container.\n\n#### Mobile\n\nThe same config drives both platforms — the runtime picks the mobile variant automatically when `isMobile` is on. `defaultButtons` in the callback is already resolved to the platform's defaults (headings inline, no font family / AI controls, `AddPlugin` inserted), so one filter works everywhere:\n\n```tsx widget\nimport { FORMATTING_BUTTONS, RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Text formatting toolbar on mobile.\n *\n * On mobile the runtime automatically renders the mobile variant of whichever\n * `text.mode` you picked. The same config drives both platforms:\n *\n * - Headings render as individual buttons on mobile (no dropdown).\n * - Font family / AI / indent controls are not part of the mobile defaults.\n * - `AddPlugin` appears inline at the start of the mobile toolbar.\n *\n * The `buttons` callback is invoked once per platform with the\n * platform-resolved `defaultButtons`, so the same filter/reorder logic\n * applies to both without extra code.\n *\n * Toggle the **isMobile** switch in the dev panel to see the desktop variant\n * — this example forces mobile on mount.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n    environment: 'businessManager',\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      // Force mobile so the mobile text toolbar is visible without toggling.\n      isMobile\n      toolbars={{\n        text: {\n          mode: 'floating',\n          // Same callback on desktop and mobile — `defaultButtons` is\n          // platform-resolved. Drop the CODE_BLOCK button on both platforms.\n          buttons: ({ defaultButtons }) =>\n            defaultButtons.filter(id => id !== FORMATTING_BUTTONS.CODE_BLOCK),\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'בחירת טקסט — סרגל הכלים לעיצוב לנייד מופיע.'\n          : 'Select text — the mobile formatting toolbar appears.'\n      }\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Insert toolbar\n\nTwo surfaces share a single `buttons` list: the inline plus button's popup menu and the footer bar.\n\n#### Footer with pinned plugins\n\nPin a subset of installed plugins to the footer. The rest stay accessible via the \"More\" menu:\n\n```tsx widget\nimport { INSERT_PLUGIN_BUTTONS, RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Footer insert toolbar pinning only a subset of installed plugins.\n *\n * All plugins remain installed; only the listed ones get a dedicated footer\n * button. The rest live under the \"More\" menu.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        insert: {\n          footer: {\n            pluginsToDisplayInToolbar: [\n              INSERT_PLUGIN_BUTTONS.IMAGE,\n              INSERT_PLUGIN_BUTTONS.VIDEO,\n              INSERT_PLUGIN_BUTTONS.GIF,\n            ],\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'רק תמונה, סרטון וגיף מוצמדים למטה!'\n          : 'Only image, video & gif are pinned below!'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\nUse the `INSERT_PLUGIN_BUTTONS` constants to reference built-in plugin buttons by id.\n\n#### Custom plus button trigger\n\nOverride what happens when the user clicks the inline plus button. `defaultTrigger` opens the built-in menu — call it to preserve the default, skip it to replace entirely:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Custom behaviour for the inline plus button.\n *\n * `insert.plusButton.onTrigger` receives `defaultTrigger` — call it to keep\n * the built-in open-menu behaviour, skip it to replace entirely, or wrap\n * with extra logic (tracking, permission gates, a custom panel, …).\n *\n * This example shows a \"track + fall through\" pattern. Click the plus button\n * on an empty line: you'll see a log line and then the default menu opens.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        insert: {\n          plusButton: {\n            onTrigger: defaultTrigger => {\n              // oxlint-disable-next-line\n              console.log('[plusButton] clicked — tracking, then opening menu');\n              defaultTrigger?.();\n            },\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'לחץ על כפתור הפלוס שליד שורה ריקה!'\n          : 'Click the plus button next to an empty line!'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Plugin toolbar\n\nThe `buttons` callback is invoked every time a plugin node or decoration is focused, with a discriminated context: `{ type: 'node', nodeType }` or `{ type: 'decoration', decoration }`.\n\n#### Filter buttons on a specific plugin\n\nDrop or reorder buttons only for the plugin you care about, pass through everything else:\n\n```tsx widget\nimport { RicosEditor, RicosPluginToolbarNames } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Filter and reorder buttons on a specific plugin node's toolbar.\n *\n * `plugin.buttons` receives a discriminated ctx. When `type === 'node'`, the\n * `nodeType` tells you which plugin's toolbar is about to render. Return an\n * array of ids in the desired order — unknown ids are silently dropped.\n *\n * This example drops the \"size\" button from the IMAGE plugin toolbar and\n * moves \"alignment\" to the front, leaving other plugin toolbars untouched.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'imageContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        plugin: {\n          buttons: ctx => {\n            if (ctx.type === 'node' && ctx.nodeType === RicosPluginToolbarNames.IMAGE) {\n              const alignmentId = ctx.defaultButtons.find(id =>\n                id.toLowerCase().includes('alignment')\n              );\n              const rest = ctx.defaultButtons.filter(\n                id => id !== alignmentId && !id.toLowerCase().includes('size')\n              );\n              return alignmentId ? [alignmentId, ...rest] : rest;\n            }\n            return ctx.defaultButtons;\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'לחץ על התמונה - סרגל הכלים שלה מותאם אישית.'\n          : 'Click the image — its toolbar is customized.'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\nThe `RicosPluginToolbarNames` enum provides typed names for every built-in plugin / decoration.\n\n#### Hide a decoration bubble entirely\n\nReturn `[]` from the callback to suppress the toolbar for that selection — this is how you hide the LINK bubble:\n\n```tsx widget\nimport { RicosEditor, RicosPluginToolbarNames } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Hide the LINK bubble toolbar via `plugin.buttons`.\n *\n * Links are surfaced as a *decoration* plugin toolbar. Returning `[]` for the\n * matching ctx hides the bubble entirely.\n *\n * Click inside a link in the content — the usual bubble no longer appears.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        plugin: {\n          buttons: ctx =>\n            ctx.type === 'decoration' && ctx.decoration === RicosPluginToolbarNames.LINK\n              ? []\n              : ctx.defaultButtons,\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'הקלד טקסט, הוסף קישור ולאחר מכן לחץ עליו - ללא בועה.'\n          : 'Type text, add a link, then click it — no bubble.'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Quick actions\n\nThe slash-command menu. Pass `placeholder` to override the prompt shown in the slash input (default: `'Type /'`), or `disabled: true` to remove the menu entirely:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Custom quick-actions placeholder.\n *\n * Type `/` in an empty line to open the slash menu with the custom placeholder.\n * Set `disabled: true` to turn off the slash menu entirely.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        quickActions: {\n          placeholder: 'Type / to add a block',\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'לחץ על / בשורה ריקה כדי לפתוח את תפריט הפעולות המהירות'\n          : 'Press / on an empty line to open the quick-actions menu'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Disabling everything\n\nSet `disabled: true` on each section to remove all consumer-facing chrome — useful when rendering fully external toolbars:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Minimal editor — every consumer-facing toolbar turned off.\n *\n * Shows how `*.disabled: true` combines:\n *   - `text.disabled: true`              — no floating/static/mobile formatting bar\n *   - `insert.plusButton.disabled: true` — no inline plus button\n *   - `insert.footer.disabled: true`     — no footer plugin bar\n *   - `plugin.disabled: true`            — no plugin bubble toolbars (also hides LINK)\n *   - `quickActions.disabled: true`      — no slash menu\n *\n * The result is a bare content-editable with no chrome — useful when the\n * consumer renders their own toolbars externally.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        text: { mode: 'floating', disabled: true },\n        insert: {\n          plusButton: { disabled: true },\n          footer: { disabled: true },\n        },\n        plugin: { disabled: true },\n        quickActions: { disabled: true },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he' ? 'עורך פשוט - ללא סרגלי כלים כלל.' : 'A bare editor — no toolbars at all.'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### External toolbars via `useToolbarProps`\n\nWhen the default placements don't fit your design, hide the internal toolbars and render buttons wherever you want — `RicosEditorAPI.useToolbarProps(type)` returns the current button state and re-runs on selection and content changes:\n\n```tsx widget\nimport type { RicosEditorAPI } from '@wix/ricos';\nimport { RicosEditor, ToolbarType } from '@wix/ricos';\nimport React from 'react';\nimport {\n  ExternalToolbar,\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * External formatting toolbar — render your own toolbar DOM off to the side.\n *\n * The pattern is:\n *   1. Hide the editor's internal toolbars via `toolbars`.\n *   2. Read reactive button state via `editorApi.useToolbarProps(type)`.\n *   3. Render the buttons wherever the consumer wants.\n *\n * The hook re-runs on selection and content changes, so the external toolbar\n * stays in sync automatically.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  const [editorApi, setEditorApi] = React.useState<RicosEditorAPI | null>(null);\n\n  return (\n    <>\n      {editorApi && <ConsumerToolbar editorApi={editorApi} />}\n      {/* @essential-start */}\n      <RicosEditor\n        initialContent={content}\n        plugins={editorPlugins}\n        toolbars={{\n          // Hide everything the editor would render itself…\n          text: { mode: 'floating', disabled: true },\n          insert: { plusButton: { disabled: true }, footer: { disabled: true } },\n        }}\n        onChange={setContent}\n        placeholder={'Select text — the buttons above will activate.'}\n        ref={setEditorApi}\n        isMobile={isMobile}\n        environment={environment}\n        locale={locale}\n        localeContent={localeContent}\n      />\n    </>\n  );\n};\n\nconst ConsumerToolbar: React.FC<{ editorApi: RicosEditorAPI }> = ({ editorApi }) => {\n  // …then read button state from the hook and render it ourselves.\n  const formatting = editorApi.useToolbarProps(ToolbarType.FORMATTING);\n  const plugin = editorApi.useToolbarProps(ToolbarType.PLUGIN);\n\n  const buttons =\n    'buttons' in plugin && Object.keys(plugin.buttons).length ? plugin.buttons : formatting.buttons;\n\n  return <ExternalToolbar buttons={buttons} />;\n      // @essential-end\n};\n```\n\nPass a `ToolbarType` (e.g. `ToolbarType.FORMATTING`, `ToolbarType.PLUGIN`) to pick which button set to read. Each returned button exposes `onClick`, `isActive`, `isDisabled`, `getIcon`, `getLabel`, and more — see `ToolbarButtonProps` for the full shape.\n\n`useToolbarProps('quickActions')` is the button set for a custom add panel. Entries that open a picker — `layoutPresets` and `SMART_BLOCK` — remain `ActionButton`s: their `onClick` opens the built-in picker. They also expose `options`: the blank `twoColumns` / `threeColumns` and designed `preset1` … `preset8` layouts, or smart-block variants (`SOLID_BOXES`, `TIMELINE`, …). Each option carries a stable `id`, thumbnail `icon`, translated `label`, translated picker section `group`, and an `onClick` that inserts it directly. The layout and smart-block actions returned by `useToolbarProps('insert')` expose the same options. The built-in slash and insert menus continue to show the parent actions.\n",
+  "editor": "### Basic Setup\n\n`RicosEditor` needs an authenticated context to load plugins, upload media, and resolve relative links. Pick the variant matching your hosting environment.\n\n#### Headless: pass a `wixClient`\n\nWhen you own the React tree and have an `@wix/sdk` client, pass it directly. The editor uses it for every authenticated request:\n\n```tsx widget\nimport { createClient, OAuthStrategy } from '@wix/sdk';\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nconst wixClient = createClient({\n  modules: {},\n  auth: OAuthStrategy({ clientId: 'YOUR_CLIENT_ID' }),\n});\n\nexport default () => (\n  // @essential-start\n  <RicosEditor\n    wixClient={wixClient}\n    baseUrl=\"https://www.example.com/my-site\"\n    plugins={[pluginImage()]}\n    placeholder=\"Type or insert an image…\"\n  />\n  // @essential-end\n);\n```\n\n#### In-Wix: pass an `instance` (and `msid`)\n\nWhen the editor renders inside a Wix-served page, your runtime usually already has a per-session `instance` token and the site's `msid`. Pass them and Ricos builds its own client internally:\n\n```tsx widget\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default ({ instance, msid }: { instance: string; msid: string }) => (\n  // @essential-start\n  <RicosEditor\n    instance={instance}\n    msid={msid}\n    baseUrl=\"https://www.example.com/my-site\"\n    plugins={[pluginImage()]}\n    placeholder=\"Type or insert an image…\"\n  />\n  // @essential-end\n);\n```\n\n#### Always pass `baseUrl`\n\n`baseUrl` is the public URL of the site that owns the content. It's used by link decorations, button plugins, gallery items, and vertical embeds to resolve page-relative hrefs (`/about` → `https://www.example.com/my-site/about`).\n\nThe in-Wix flow can auto-fetch this from `/_api/ricos-site-pages/base-url`, but in any headless or cross-origin context you must pass it explicitly — without it, page-relative links in your content render as raw paths.\n\n### Ricos Editor Props\n\n#### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">RicosEditorProps</span>\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> RicosEditorProps</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>plugins</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#editorpluginoptions\"><span class=\"font-mono\">EditorPluginOptions</span></a>[]</code></dt>\n<dd><p>Array of editor plugins to enable. Each plugin adds editing capabilities (e.g., image, video, table).</p></dd>\n<dt><code><strong>onChange</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#oncontentchangefunction\"><span class=\"font-mono\">OnContentChangeFunction</span></a></code></dt>\n<dd><p>Fires only when document content changes (not on selection changes).</p></dd>\n<dt><code><strong>onSelectionChange</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#onselectionchangefunction\"><span class=\"font-mono\">OnSelectionChangeFunction</span></a></code></dt>\n<dd><p>Fires when the selection/cursor position changes (including during edits).</p></dd>\n<dt><code><strong>placeholder</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Placeholder text displayed when the editor is empty.</p></dd>\n</dl>\n\n<div class=\"pl-4 border-l-2 border-slate-200 mb-4\">\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  return <RicosEditor placeholder={'Type here!'} />;\n  // @essential-end\n};\n```\n\n</div>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>toolbars</strong><span class=\"text-slate-400\">?</span>: <a href=\"#toolbarsconfig\"><span class=\"font-mono\">ToolbarsConfig</span></a></code></dt>\n<dd><p>Toolbars configuration — controls the text formatting toolbar, insert plugin toolbars, plugin context toolbars and the quick-actions menu.</p></dd>\n<dt><code><strong>onBusyChange</strong><span class=\"text-slate-400\">?</span>: (isBusy: boolean) =&gt; void</code></dt>\n<dd><p>Callback fired when the editor transitions between busy and idle states (e.g., during media uploads).</p></dd>\n<dt><code><strong>maxTextLength</strong><span class=\"text-slate-400\">?</span>: number</code></dt>\n<dd><p>Maximum number of text characters allowed in the editor. When the limit is reached, further text input is ignored and paste actions are canceled if the result would exceed the limit.</p></dd>\n<dt><code><strong>sideBlockComponent</strong><span class=\"text-slate-400\">?</span>: FC&lt;{         id: string;     }&gt;</code></dt>\n<dd><p>A React component rendered as a side block alongside the editor content. Receives the block `id` as a prop.</p></dd>\n<dt><code><strong>commands</strong><span class=\"text-slate-400\">?</span>: any[]</code></dt>\n<dd><p>Custom commands to register with the editor.</p></dd>\n<dt><code><strong>historySettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#historysettings\"><span class=\"font-mono\">HistorySettings</span></a></code></dt>\n<dd><p>Settings for undo/redo history.</p></dd>\n<dt><code><strong>onLoad</strong><span class=\"text-slate-400\">?</span>: (editor: any) =&gt; void</code></dt>\n<dd><p>Callback fired when the editor finishes loading and is ready for interaction.</p></dd>\n<dt><code><strong>autofocus</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#focusposition\"><span class=\"font-mono\">FocusPosition</span></a></code></dt>\n<dd><p>Controls initial cursor/focus position when the editor mounts.</p></dd>\n<dt><code><strong>container</strong><span class=\"text-slate-400\">?</span>: HTMLElement | (() =&gt; HTMLElement | null)</code></dt>\n<dd><p>HTML element or factory function that returns the container element for rendering editor popovers and modals.</p></dd>\n<dt><code><strong>initialContent</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricosdocument\"><span class=\"font-mono\">RicosDocument</span></a></code></dt>\n<dd><p>Initial content for the editor. Only used during initialization — not a controlled value.</p></dd>\n<dt><code><strong>keyboardShortcuts</strong><span class=\"text-slate-400\">?</span>: any[]</code></dt>\n<dd><p>Custom keyboard shortcuts to register with the editor.</p></dd>\n<dt><code><strong>loadingPlaceholder</strong><span class=\"text-slate-400\">?</span>: React.ReactNode</code></dt>\n<dd><p>The placeholder to be displayed while the editor is loading.</p></dd>\n<dt><code><strong>tabFocusBehavior</strong><span class=\"text-slate-400\">?</span>: 'edit' | 'container'</code></dt>\n<dd><p>Controls focus behavior when tabbing into the editor: - `'edit'`: (default) Immediately enables typing when editor receives keyboard focus. - `'container'`: Shows focus ring but requires Enter/key press to start editing.</p>\n<p>Default: <code>'edit'</code></p></dd>\n<dt><code><strong>colorManager</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#colorpalettemanager\"><span class=\"font-mono\">ColorPaletteManager</span></a></code></dt>\n<dd><p>Unified color manager for sharing custom colors across all plugins.</p></dd>\n<dt><code><strong>modalSettings</strong><span class=\"text-slate-400\">?</span>: ModalSettings</code></dt>\n<dd></dd>\n<dt><code><strong>pickMedia</strong><span class=\"text-slate-400\">?</span>: _PublicPickMedia</code></dt>\n<dd><p>Pick media implementation used by media-related plugins (e.g., image, gallery).</p></dd>\n<dt><code><strong>visitorUploads</strong><span class=\"text-slate-400\">?</span>: _VisitorUploads</code></dt>\n<dd><p>Visitor upload settings used by file-upload-capable plugins.</p></dd>\n<dt><code><strong>fileUploadSizeLimit</strong><span class=\"text-slate-400\">?</span>: number</code></dt>\n<dd><p>Maximum file size limit (in bytes) for uploads.</p></dd>\n<dt><code><strong>htmlAttributes</strong><span class=\"text-slate-400\">?</span>: {         autoCapitalize?: string;         spellCheck?: boolean;         autoComplete?: string;         autoCorrect?: string;         tabIndex?: number;         ariaLabel?: string;     }</code></dt>\n<dd><p>HTML attributes applied to the editor's content-editable element.</p></dd>\n<dt><code><strong>isMobile</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, renders in mobile-optimized mode.</p></dd>\n<dt><code><strong>generalLinkSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#generallinksettings\"><span class=\"font-mono\">GeneralLinkSettings</span></a></code></dt>\n<dd><p>Link settings applied globally to all linkable plugins.</p></dd>\n<dt><code><strong>locale</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Two-letter locale code (e.g., `'en'`, `'he'`). Determines the language and text direction of modals and settings.</p></dd>\n<dt><code><strong>localeContent</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Locale for content, when different from UI locale. If not defined, `locale` is used.</p></dd>\n<dt><code><strong>onError</strong><span class=\"text-slate-400\">?</span>: (error: string) =&gt; void</code></dt>\n<dd><p>Callback fired when an error occurs in a Ricos component.</p></dd>\n<dt><code><strong>theme</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/theming#ricostheme\"><span class=\"font-mono\">RicosTheme</span></a></code></dt>\n<dd><p>Theme configuration for colors, fonts, and custom styles.</p></dd>\n<dt><code><strong>textAlignment</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#textalignment\"><span class=\"font-mono\">TextAlignment</span></a></code></dt>\n<dd><p>Default text alignment direction.</p></dd>\n<dt><code><strong>onAtomicBlockFocus</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#onatomicblockfocus\"><span class=\"font-mono\">onAtomicBlockFocus</span></a></code></dt>\n<dd><p>Callback fired when an atomic block (plugin) receives focus.</p></dd>\n<dt><code><strong>iframeSandboxDomain</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Domain used to render UGC source code in an isolated sandboxed iframe.</p></dd>\n<dt><code><strong>textWrap</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, wraps text around left/right-aligned plugins.</p></dd>\n<dt><code><strong>responsiveBehavior</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#responsivebehavior\"><span class=\"font-mono\">ResponsiveBehavior</span></a></code></dt>\n<dd><p>What responsive styles (narrow layouts, stacked columns, smaller paddings) respond to: - `'container'`: (default) the editor or viewer width, through CSS container queries. - `'viewport'`: the window width, through media queries. Ricos then declares no CSS containers, so `cqw` units in host styles (such as site theme fonts) resolve against the host's own containers.</p>\n<p>Default: <code>'container'</code></p></dd>\n<dt><code><strong>debugMode</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#debugmode\"><span class=\"font-mono\">DebugMode</span></a>[]</code></dt>\n<dd><p>Debug mode flags for enabling development-time diagnostics.</p></dd>\n<dt><code><strong>environment</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#environment\"><span class=\"font-mono\">Environment</span></a></code></dt>\n<dd><p>Theme variant to apply: - `'businessManager'`: BM theme is applied and cannot be overridden. - `'liveSite'`: liveSite theme is applied and can be overridden via `theme`.   'liveSite'</p></dd>\n<dt><code><strong>baseUrl</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Base URL of the site, used to resolve page-relative URLs. Used by links, buttons, gallery items, and vertical embeds to construct full hrefs from relative paths (e.g., `/my-page` → `https://example.com/my-site/my-page`).  If not provided, fetched automatically from `/_api/ricos-site-pages/base-url`.</p></dd>\n<dt><code><strong>biSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#bisettings\"><span class=\"font-mono\">BISettings</span></a></code></dt>\n<dd><p>Business intelligence configuration for analytics and tracking.</p></dd>\n<dt><code><strong>wixClient</strong><span class=\"text-slate-400\">?</span>: WixClient</code></dt>\n<dd><p>Authenticated `WixClient` from `@wix/sdk`. When provided, takes priority over `instance` for authorizing every request the editor makes (media uploads, link previews, etc.). Use this in headless apps where you own the React tree.</p></dd>\n<dt><code><strong>instance</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Per-session Wix instance token. Used when no `wixClient` is provided — Ricos builds an internal client from it. Typically set by Wix-served host pages.</p></dd>\n<dt><code><strong>msid</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Metasite ID. Scopes storage and CDN traffic to the owning site when no `wixClient` is given.</p></dd>\n<dt><code><strong>shouldNormalizeRichContent</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, normalises rich content via `normalizeRicosDocument` before rendering. Set to `false` to skip normalisation when content is already known to be valid.   true</p></dd>\n<dt><code><strong>mediaSettings</strong><span class=\"text-slate-400\">?</span>: MediaSettings</code></dt>\n<dd><p>Media-upload, capture, and resolution settings shared across media plugins.</p></dd>\n<dt style=\"opacity: 0.5;\"><code><strong>linkSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#linksettings\"><span class=\"font-mono\">LinkSettings</span></a></code></dt>\n<dd><p><em>Deprecated.</em> Use `generalLinkSettings` instead.</p></dd>\n<dt><code><strong>preserveDomOnUnmount</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>Keep the editor's DOM alive across a transient React unmount instead of tearing it down and rebuilding it on remount. Lets the host preserve editor state (and avoid flicker) when the editor is briefly unmounted/remounted.   false</p></dd>\n<dt style=\"opacity: 0.5;\"><code><strong>experiments</strong><span class=\"text-slate-400\">?</span>: AvailableExperiments</code></dt>\n<dd><p><em>Deprecated.</em> Not used at runtime.</p></dd>\n</dl>\n\n### Ricos Editor Imperative API\n\n#### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">RicosEditorAPI</span>\n\nImperative API for controlling a mounted `RicosEditor`. Accessed via a React ref — `const editorRef = useRef<RicosEditorType>(null)` — and read inside event handlers (publish flows, programmatic content swaps, focus/undo/redo controls). For UI that needs to react to editor state in render — toolbar enable/disable, undo-stack indicators — prefer the reactive hooks (`useToolbarProps`, `useUndoState`) over polling these methods.\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> RicosEditorAPI</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>focus</strong>: (focusPosition?: FocusPosition): void;</code></dt>\n<dd><p>Focuses the editor. Optionally moves the cursor to `focusPosition`.</p></dd>\n<dt><code><strong>blur</strong>: (): void;</code></dt>\n<dd><p>Removes focus from the editor.</p></dd>\n<dt><code><strong>undo</strong>: (): void;</code></dt>\n<dd><p>Undoes the last editor action.</p></dd>\n<dt><code><strong>redo</strong>: (): void;</code></dt>\n<dd><p>Redoes the last undone action.</p></dd>\n<dt><code><strong>getContent</strong>: (postId?: string, forPublish?: boolean, shouldRemoveErrorBlocks?: boolean): Promise&lt;RicosDocument&gt;;</code></dt>\n<dd><p>Returns the current content as a `RicosDocument`. Resolves after any pending async operations.</p></dd>\n<dt><code><strong>getContentPromise</strong>: (props: {         flush?: boolean;         publishId?: string;     } | undefined): Promise&lt;RicosDocument&gt;;</code></dt>\n<dd><p>Returns a promise of the current content. `publishId` — used for BI (`onPublish` event), set it when called before publishing. `flush` — triggers editor blur to force pending changes (e.g., Android composition mode) before reading content.</p></dd>\n<dt><code><strong>getContentTraits</strong>: (): {         isEmpty: boolean;         isContentChanged: boolean;         isLastChangeEdit: boolean;     };</code></dt>\n<dd><p>Returns content traits: whether the editor is empty, content has changed, and the last change was an edit.</p></dd>\n<dt><code><strong>setContent</strong>: (content: RicosDocument): void;</code></dt>\n<dd><p>Replaces the editor content. Imperative replacement for the removed `injectedContent` prop.</p></dd>\n<dt><code><strong>insertContent</strong>: (content: {         nodes: RicosDocumentNode[];     }): void;</code></dt>\n<dd><p>Inserts the nodes at the cursor, replacing the selection if there is one.</p></dd>\n<dt><code><strong>getEditorContainer</strong>: (): HTMLElement | undefined;</code></dt>\n<dd><p>Returns the DOM element wrapping the editor's content-editable, if mounted.</p></dd>\n<dt><code><strong>openModal</strong>: (options: {         type: 'AI_IMAGE' | 'INLINE_AI' | 'SHORTCUTS_SHEET' | 'AI_WIDGET';     }) =&gt; void</code></dt>\n<dd><p>Opens a built-in modal (AI image generation, inline AI, keyboard shortcuts sheet, or AI widget).</p></dd>\n<dt><code><strong>useToolbarProps</strong>: (type: UseToolbarPropsType): ToolbarPropsResult;</code></dt>\n<dd><p>Subscribe to the reactive button list for a toolbar. Re-runs on selection and content changes, so consumers rendering a custom toolbar stay in sync automatically. Must be called inside a React component.</p></dd>\n<dt><code><strong>useInlineAiState</strong>: (invocationId: string) =&gt; unknown</code></dt>\n<dd></dd>\n<dt><code><strong>prePublish</strong>: (): Promise&lt;RicosDocument&gt;;</code></dt>\n<dd><p>Runs plugin pre-publish hooks (e.g. poll sync) and returns the content.</p></dd>\n<dt><code><strong>useUndoState</strong>: () =&gt; {         isUndoStackEmpty: boolean;         isRedoStackEmpty: boolean;     }</code></dt>\n<dd><p>Reactive undo/redo state. Must be called inside a React component.</p></dd>\n</dl>\n\n```tsx widget\nimport type { RicosDocument, RicosEditorType } from '@wix/ricos';\nimport { pluginImage, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  const editorRef = React.useRef<RicosEditorType>(null);\n\n  // @essential-start\n  const UndoButtons = () => {\n    const { isUndoStackEmpty, isRedoStackEmpty } = editorRef.current?.useUndoState() ?? {\n      isUndoStackEmpty: true,\n      isRedoStackEmpty: true,\n    };\n    return (\n      <>\n        <button onClick={() => editorRef.current?.undo()} disabled={isUndoStackEmpty} type=\"button\">\n          Undo\n        </button>\n        <button onClick={() => editorRef.current?.redo()} disabled={isRedoStackEmpty} type=\"button\">\n          Redo\n        </button>\n      </>\n    );\n  };\n\n  const handlePublish = async () => {\n    const document = await editorRef.current?.prePublish();\n    alert(`Publishing ${document?.nodes.length ?? 0} nodes`);\n  };\n\n  const handleReset = () => editorRef.current?.setContent(initialContent);\n\n  return (\n    <>\n      <RicosEditor\n        ref={editorRef}\n        initialContent={initialContent}\n        plugins={[pluginImage()]}\n        placeholder=\"Edit me — drag an image in or use the toolbar\"\n      />\n      <UndoButtons />\n      <button onClick={handlePublish} type=\"button\">\n        Publish\n      </button>\n      <button onClick={handleReset} type=\"button\">\n        Reset\n      </button>\n    </>\n  );\n  // @essential-end\n};\n\nconst initialContent: RicosDocument = {\n  nodes: [\n    {\n      type: 'PARAGRAPH',\n      id: 'p1',\n      nodes: [\n        {\n          type: 'TEXT',\n          id: '',\n          nodes: [],\n          textData: { text: 'Edit, undo, publish, reset.', decorations: [] },\n        },\n      ],\n    },\n    {\n      type: 'IMAGE',\n      id: 'img1',\n      nodes: [],\n      imageData: {\n        containerData: {\n          width: { size: 'CONTENT' },\n          alignment: 'CENTER',\n          textWrap: true,\n        },\n        image: {\n          src: { url: 'https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg' },\n          width: 5120,\n          height: 3413,\n        },\n        altText: 'A tree during sunset.',\n      },\n    },\n  ],\n};\n```\n\n\n## Toolbars\n\nRicos ships with four consumer-facing toolbars, all configured through a single `toolbars` prop on `RicosEditor`:\n\n- **Text toolbar** — formatting controls shown when the user selects text (floating by default, or rendered into a container)\n- **Insert toolbar** — the inline plus button on empty lines and the footer plugin bar\n- **Plugin toolbar** — the bubble that appears when a plugin node or decoration (e.g. a link) is selected\n- **Quick actions** — the slash-command menu triggered by typing `/`\n\nEach is optional — omit a section to keep its default behaviour. Fields are grouped by concept, not by the low-level rendering variant, so the same config drives desktop and mobile without platform-specific branches.\n\n##### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">ToolbarsConfig</span>\n\nConfiguration for the editor's consumer-facing toolbars — text formatting, insert plugin menus, plugin context bubbles and quick actions.  Fields are grouped by concept (`text`, `insert`, `plugin`, `quickActions`) so the same config drives desktop and mobile without platform-specific branching.\n\n<pre class=\"block py-4 px-4 my-2 overflow-auto rounded border-none bg-slate-200 font-mono text-sm leading-6 tracking-wide text-slate-900\"><code><span class=\"text-blue-700\">type</span> ToolbarsConfig = {     text?: TextToolbarConfig;     insert?: InsertToolbarConfig;     plugin?: PluginToolbarConfig;     quickActions?: <a href=\"#quickactionsconfig\"><span class=\"font-mono\">QuickActionsConfig</span></a>; }</code></pre>\n\n### Text toolbar\n\nTwo mutually exclusive modes: `floating` (above the selection) and `static` (rendered into a DOM container the consumer owns).\n\n#### Floating mode with custom buttons\n\nFilter the default button list and register your own components:\n\n```tsx widget\nimport { FORMATTING_BUTTONS, RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Floating text toolbar with:\n * - `buttons` callback filtering out CODE_BLOCK from defaults and appending\n *   a custom button name\n * - `customButtons` registering a React component for that name\n *\n * The callback receives `defaultButtons` already resolved to the platform's\n * default text button ids.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        text: {\n          mode: 'floating',\n          buttons: ({ defaultButtons }) => [\n            ...defaultButtons.filter(id => id !== FORMATTING_BUTTONS.CODE_BLOCK),\n            'MY_INFO',\n          ],\n          customButtons: {\n            MY_INFO: {\n              component: () => (\n                // oxlint-disable-next-line\n                <div onClick={() => console.log('info!')} style={{ padding: '0 8px' }}>\n                  ℹ︎\n                </div>\n              ),\n            },\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'בחר טקסט כדי לראות את סרגל הכלים הצף!'\n          : 'Select text to see the floating toolbar!'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\nThe `buttons` callback receives `defaultButtons` — the platform-resolved list of built-in button ids. Return the desired order; unknown ids are dropped silently. Use `customButtons` to register React components keyed by the ids you reference.\n\n#### Static mode\n\nRender the text toolbar into a container outside the editor — useful when the page already has a fixed toolbar area:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Static text toolbar rendered into a container the consumer owns.\n *\n *   toolbars: { text: { mode: 'static', container, alignment: 'left' } }\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  const [toolbarContainer, setToolbarContainer] = React.useState<HTMLDivElement | null>(null);\n\n  return (\n    <div style={{ display: 'grid', gap: 16 }}>\n      <div\n        ref={setToolbarContainer}\n        style={{ minHeight: 48, border: '1px dashed #ccc', padding: 8 }}\n      />\n      {/* @essential-start */}\n      <RicosEditor\n        initialContent={content}\n        plugins={editorPlugins}\n        toolbars={\n          toolbarContainer\n            ? { text: { mode: 'static', container: toolbarContainer, alignment: 'left' } }\n            : undefined\n        }\n        onChange={setContent}\n        placeholder={locale === 'he' ? 'הוסף קצת טקסט!' : 'Add some text!'}\n        isMobile={isMobile}\n        environment={environment}\n        locale={locale}\n        localeContent={localeContent}\n      />\n      {/* @essential-end */}\n    </div>\n  );\n};\n```\n\nSet `container` to any `HTMLElement`. `alignment` controls horizontal positioning inside that container.\n\n#### Mobile\n\nThe same config drives both platforms — the runtime picks the mobile variant automatically when `isMobile` is on. `defaultButtons` in the callback is already resolved to the platform's defaults (headings inline, no font family / AI controls, `AddPlugin` inserted), so one filter works everywhere:\n\n```tsx widget\nimport { FORMATTING_BUTTONS, RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Text formatting toolbar on mobile.\n *\n * On mobile the runtime automatically renders the mobile variant of whichever\n * `text.mode` you picked. The same config drives both platforms:\n *\n * - Headings render as individual buttons on mobile (no dropdown).\n * - Font family / AI / indent controls are not part of the mobile defaults.\n * - `AddPlugin` appears inline at the start of the mobile toolbar.\n *\n * The `buttons` callback is invoked once per platform with the\n * platform-resolved `defaultButtons`, so the same filter/reorder logic\n * applies to both without extra code.\n *\n * Toggle the **isMobile** switch in the dev panel to see the desktop variant\n * — this example forces mobile on mount.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n    environment: 'businessManager',\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      // Force mobile so the mobile text toolbar is visible without toggling.\n      isMobile\n      toolbars={{\n        text: {\n          mode: 'floating',\n          // Same callback on desktop and mobile — `defaultButtons` is\n          // platform-resolved. Drop the CODE_BLOCK button on both platforms.\n          buttons: ({ defaultButtons }) =>\n            defaultButtons.filter(id => id !== FORMATTING_BUTTONS.CODE_BLOCK),\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'בחירת טקסט — סרגל הכלים לעיצוב לנייד מופיע.'\n          : 'Select text — the mobile formatting toolbar appears.'\n      }\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Insert toolbar\n\nTwo surfaces share a single `buttons` list: the inline plus button's popup menu and the footer bar.\n\n#### Footer with pinned plugins\n\nPin a subset of installed plugins to the footer. The rest stay accessible via the \"More\" menu:\n\n```tsx widget\nimport { INSERT_PLUGIN_BUTTONS, RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Footer insert toolbar pinning only a subset of installed plugins.\n *\n * All plugins remain installed; only the listed ones get a dedicated footer\n * button. The rest live under the \"More\" menu.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        insert: {\n          footer: {\n            pluginsToDisplayInToolbar: [\n              INSERT_PLUGIN_BUTTONS.IMAGE,\n              INSERT_PLUGIN_BUTTONS.VIDEO,\n              INSERT_PLUGIN_BUTTONS.GIF,\n            ],\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'רק תמונה, סרטון וגיף מוצמדים למטה!'\n          : 'Only image, video & gif are pinned below!'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\nUse the `INSERT_PLUGIN_BUTTONS` constants to reference built-in plugin buttons by id.\n\n#### Custom plus button trigger\n\nOverride what happens when the user clicks the inline plus button. `defaultTrigger` opens the built-in menu — call it to preserve the default, skip it to replace entirely:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Custom behaviour for the inline plus button.\n *\n * `insert.plusButton.onTrigger` receives `defaultTrigger` — call it to keep\n * the built-in open-menu behaviour, skip it to replace entirely, or wrap\n * with extra logic (tracking, permission gates, a custom panel, …).\n *\n * This example shows a \"track + fall through\" pattern. Click the plus button\n * on an empty line: you'll see a log line and then the default menu opens.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        insert: {\n          plusButton: {\n            onTrigger: defaultTrigger => {\n              // oxlint-disable-next-line\n              console.log('[plusButton] clicked — tracking, then opening menu');\n              defaultTrigger?.();\n            },\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'לחץ על כפתור הפלוס שליד שורה ריקה!'\n          : 'Click the plus button next to an empty line!'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Plugin toolbar\n\nThe `buttons` callback is invoked every time a plugin node or decoration is focused, with a discriminated context: `{ type: 'node', nodeType }` or `{ type: 'decoration', decoration }`.\n\n#### Filter buttons on a specific plugin\n\nDrop or reorder buttons only for the plugin you care about, pass through everything else:\n\n```tsx widget\nimport { RicosEditor, RicosPluginToolbarNames } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Filter and reorder buttons on a specific plugin node's toolbar.\n *\n * `plugin.buttons` receives a discriminated ctx. When `type === 'node'`, the\n * `nodeType` tells you which plugin's toolbar is about to render. Return an\n * array of ids in the desired order — unknown ids are silently dropped.\n *\n * This example drops the \"size\" button from the IMAGE plugin toolbar and\n * moves \"alignment\" to the front, leaving other plugin toolbars untouched.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'imageContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        plugin: {\n          buttons: ctx => {\n            if (ctx.type === 'node' && ctx.nodeType === RicosPluginToolbarNames.IMAGE) {\n              const alignmentId = ctx.defaultButtons.find(id =>\n                id.toLowerCase().includes('alignment')\n              );\n              const rest = ctx.defaultButtons.filter(\n                id => id !== alignmentId && !id.toLowerCase().includes('size')\n              );\n              return alignmentId ? [alignmentId, ...rest] : rest;\n            }\n            return ctx.defaultButtons;\n          },\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'לחץ על התמונה - סרגל הכלים שלה מותאם אישית.'\n          : 'Click the image — its toolbar is customized.'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\nThe `RicosPluginToolbarNames` enum provides typed names for every built-in plugin / decoration.\n\n#### Hide a decoration bubble entirely\n\nReturn `[]` from the callback to suppress the toolbar for that selection — this is how you hide the LINK bubble:\n\n```tsx widget\nimport { RicosEditor, RicosPluginToolbarNames } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Hide the LINK bubble toolbar via `plugin.buttons`.\n *\n * Links are surfaced as a *decoration* plugin toolbar. Returning `[]` for the\n * matching ctx hides the bubble entirely.\n *\n * Click inside a link in the content — the usual bubble no longer appears.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        plugin: {\n          buttons: ctx =>\n            ctx.type === 'decoration' && ctx.decoration === RicosPluginToolbarNames.LINK\n              ? []\n              : ctx.defaultButtons,\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'הקלד טקסט, הוסף קישור ולאחר מכן לחץ עליו - ללא בועה.'\n          : 'Type text, add a link, then click it — no bubble.'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Quick actions\n\nThe slash-command menu. Pass `placeholder` to override the prompt shown in the slash input (default: `'Type /'`), or `disabled: true` to remove the menu entirely:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Custom quick-actions placeholder.\n *\n * Type `/` in an empty line to open the slash menu with the custom placeholder.\n * Set `disabled: true` to turn off the slash menu entirely.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        quickActions: {\n          placeholder: 'Type / to add a block',\n        },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he'\n          ? 'לחץ על / בשורה ריקה כדי לפתוח את תפריט הפעולות המהירות'\n          : 'Press / on an empty line to open the quick-actions menu'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### Disabling everything\n\nSet `disabled: true` on each section to remove all consumer-facing chrome — useful when rendering fully external toolbars:\n\n```tsx widget\nimport { RicosEditor } from '@wix/ricos';\nimport React from 'react';\nimport {\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * Minimal editor — every consumer-facing toolbar turned off.\n *\n * Shows how `*.disabled: true` combines:\n *   - `text.disabled: true`              — no floating/static/mobile formatting bar\n *   - `insert.plusButton.disabled: true` — no inline plus button\n *   - `insert.footer.disabled: true`     — no footer plugin bar\n *   - `plugin.disabled: true`            — no plugin bubble toolbars (also hides LINK)\n *   - `quickActions.disabled: true`      — no slash menu\n *\n * The result is a bare content-editable with no chrome — useful when the\n * consumer renders their own toolbars externally.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  return (\n    // @essential-start\n    <RicosEditor\n      initialContent={content}\n      plugins={editorPlugins}\n      toolbars={{\n        text: { mode: 'floating', disabled: true },\n        insert: {\n          plusButton: { disabled: true },\n          footer: { disabled: true },\n        },\n        plugin: { disabled: true },\n        quickActions: { disabled: true },\n      }}\n      onChange={setContent}\n      placeholder={\n        locale === 'he' ? 'עורך פשוט - ללא סרגלי כלים כלל.' : 'A bare editor — no toolbars at all.'\n      }\n      isMobile={isMobile}\n      environment={environment}\n      locale={locale}\n      localeContent={localeContent}\n    />\n    // @essential-end\n  );\n};\n```\n\n### External toolbars via `useToolbarProps`\n\nWhen the default placements don't fit your design, hide the internal toolbars and render buttons wherever you want — `RicosEditorAPI.useToolbarProps(type)` returns the current button state and re-runs on selection and content changes:\n\n```tsx widget\nimport type { RicosEditorAPI } from '@wix/ricos';\nimport { RicosEditor, ToolbarType } from '@wix/ricos';\nimport React from 'react';\nimport {\n  ExternalToolbar,\n  preconfiguredEditorPlugins,\n  useDevContent,\n  useDevSettings,\n} from 'ricos-dev-utils/next';\n\n/**\n * External formatting toolbar — render your own toolbar DOM off to the side.\n *\n * The pattern is:\n *   1. Hide the editor's internal toolbars via `toolbars`.\n *   2. Read reactive button state via `editorApi.useToolbarProps(type)`.\n *   3. Render the buttons wherever the consumer wants.\n *\n * The hook re-runs on selection and content changes, so the external toolbar\n * stays in sync automatically.\n */\nexport default () => {\n  const [content, setContent] = useDevContent({\n    contentSlug: 'emptyContent',\n  });\n  const { isMobile, environment, locale, localeContent, editorPlugins } = useDevSettings({\n    editorPlugins: preconfiguredEditorPlugins,\n  });\n\n  const [editorApi, setEditorApi] = React.useState<RicosEditorAPI | null>(null);\n\n  return (\n    <>\n      {editorApi && <ConsumerToolbar editorApi={editorApi} />}\n      {/* @essential-start */}\n      <RicosEditor\n        initialContent={content}\n        plugins={editorPlugins}\n        toolbars={{\n          // Hide everything the editor would render itself…\n          text: { mode: 'floating', disabled: true },\n          insert: { plusButton: { disabled: true }, footer: { disabled: true } },\n        }}\n        onChange={setContent}\n        placeholder={'Select text — the buttons above will activate.'}\n        ref={setEditorApi}\n        isMobile={isMobile}\n        environment={environment}\n        locale={locale}\n        localeContent={localeContent}\n      />\n    </>\n  );\n};\n\nconst ConsumerToolbar: React.FC<{ editorApi: RicosEditorAPI }> = ({ editorApi }) => {\n  // …then read button state from the hook and render it ourselves.\n  const formatting = editorApi.useToolbarProps(ToolbarType.FORMATTING);\n  const plugin = editorApi.useToolbarProps(ToolbarType.PLUGIN);\n\n  const buttons =\n    'buttons' in plugin && Object.keys(plugin.buttons).length ? plugin.buttons : formatting.buttons;\n\n  return <ExternalToolbar buttons={buttons} />;\n      // @essential-end\n};\n```\n\nPass a `ToolbarType` (e.g. `ToolbarType.FORMATTING`, `ToolbarType.PLUGIN`) to pick which button set to read. Each returned button exposes `onClick`, `isActive`, `isDisabled`, `getIcon`, `getLabel`, and more — see `ToolbarButtonProps` for the full shape.\n\n`useToolbarProps('quickActions')` is the button set for a custom add panel. Entries that open a picker — `layoutPresets` and `SMART_BLOCK` — remain `ActionButton`s: their `onClick` opens the built-in picker. They also expose `options`: the blank `twoColumns` / `threeColumns` and designed `preset1` … `preset8` layouts, or smart-block variants (`SOLID_BOXES`, `TIMELINE`, …). Each option carries a stable `id`, thumbnail `icon`, translated `label`, translated picker section `group`, and an `onClick` that inserts it directly. The layout and smart-block actions returned by `useToolbarProps('insert')` expose the same options. The built-in slash and insert menus continue to show the parent actions.\n",
   "viewer": "### Render-only entry point\n\nIf a bundle only renders content, import the viewer and its plugins from `@wix/ricos/viewer`\ninstead of `@wix/ricos`. It exports the same `RicosViewer`, `quickStartViewerPlugins` and\n`plugin*Viewer` factories, but never reaches the editor, so your bundler has far less to\nparse. Importing types with `import type` from `@wix/ricos` costs nothing at build time.\n\n```tsx\nimport { RicosViewer, quickStartViewerPlugins } from '@wix/ricos/viewer';\nimport type { RicosViewerProps } from '@wix/ricos/viewer';\n```\n\n### Ricos Viewer Props\n\n#### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">RicosViewerProps</span>\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> RicosViewerProps</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>children</strong><span class=\"text-slate-400\">?</span>: React.ReactElement</code></dt>\n<dd><p>Optional child element to render inside the viewer.</p></dd>\n<dt><code><strong>plugins</strong><span class=\"text-slate-400\">?</span>: (ViewerPlugin | any)[]</code></dt>\n<dd><p>Array of viewer plugins to enable. Each plugin adds rendering capabilities for specific content types.</p></dd>\n<dt><code><strong>seoSettings</strong><span class=\"text-slate-400\">?</span>: boolean | any</code></dt>\n<dd><p>SEO settings for server-side rendering. When `true`, enables default SEO mode.</p></dd>\n<dt><code><strong>textSelectionToolbar</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, shows a floating toolbar when the user selects text in the viewer.</p></dd>\n<dt><code><strong>content</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricosdocument\"><span class=\"font-mono\">RicosDocument</span></a></code></dt>\n<dd><p>The rich content to display. Required for the viewer to render anything.</p></dd>\n<dt><code><strong>addAnchors</strong><span class=\"text-slate-400\">?</span>: boolean | string</code></dt>\n<dd><p>When `true`, adds anchor elements to content blocks for deep linking. Pass a string to use as a prefix for generated anchor IDs.</p></dd>\n<dt><code><strong>onNodeClick</strong><span class=\"text-slate-400\">?</span>: ({ node }: {         node: any;     }) =&gt; void</code></dt>\n<dd><p>Callback fired when a user clicks on a content node in the viewer.</p></dd>\n<dt><code><strong>jsdomMode</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, renders in jsdom-compatible mode for server-side rendering environments.</p></dd>\n<dt><code><strong>isPrint</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, renders in print-optimized mode (e.g., for `window.print()`).</p></dd>\n<dt><code><strong>onLoad</strong><span class=\"text-slate-400\">?</span>: () =&gt; void</code></dt>\n<dd><p>Callback fired once, after the viewer first renders. Lazily loaded plugins may still be loading.</p></dd>\n<dt><code><strong>firstFoldNodeCount</strong><span class=\"text-slate-400\">?</span>: number</code></dt>\n<dd><p>Number of leading top-level nodes to treat as being in the first fold. Images among them render their full-quality source during SSR, with a `srcset` and `fetchpriority=\"high\"`, instead of the blurred placeholder that is only swapped for the real image after hydration. Nested images (inside a card, table, collapsible list, etc.) never qualify.   0 - every image keeps the placeholder behaviour</p></dd>\n<dt><code><strong>isMobile</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, renders in mobile-optimized mode.</p></dd>\n<dt><code><strong>generalLinkSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#generallinksettings\"><span class=\"font-mono\">GeneralLinkSettings</span></a></code></dt>\n<dd><p>Link settings applied globally to all linkable plugins.</p></dd>\n<dt><code><strong>locale</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Two-letter locale code (e.g., `'en'`, `'he'`). Determines the language and text direction of modals and settings.</p></dd>\n<dt><code><strong>localeContent</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Locale for content, when different from UI locale. If not defined, `locale` is used.</p></dd>\n<dt><code><strong>onError</strong><span class=\"text-slate-400\">?</span>: (error: string) =&gt; void</code></dt>\n<dd><p>Callback fired when an error occurs in a Ricos component.</p></dd>\n<dt><code><strong>theme</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/theming#ricostheme\"><span class=\"font-mono\">RicosTheme</span></a></code></dt>\n<dd><p>Theme configuration for colors, fonts, and custom styles.</p></dd>\n<dt><code><strong>textAlignment</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#textalignment\"><span class=\"font-mono\">TextAlignment</span></a></code></dt>\n<dd><p>Default text alignment direction.</p></dd>\n<dt><code><strong>onAtomicBlockFocus</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#onatomicblockfocus\"><span class=\"font-mono\">onAtomicBlockFocus</span></a></code></dt>\n<dd><p>Callback fired when an atomic block (plugin) receives focus.</p></dd>\n<dt><code><strong>iframeSandboxDomain</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Domain used to render UGC source code in an isolated sandboxed iframe.</p></dd>\n<dt><code><strong>textWrap</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, wraps text around left/right-aligned plugins.</p></dd>\n<dt><code><strong>responsiveBehavior</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#responsivebehavior\"><span class=\"font-mono\">ResponsiveBehavior</span></a></code></dt>\n<dd><p>What responsive styles (narrow layouts, stacked columns, smaller paddings) respond to: - `'container'`: (default) the editor or viewer width, through CSS container queries. - `'viewport'`: the window width, through media queries. Ricos then declares no CSS containers, so `cqw` units in host styles (such as site theme fonts) resolve against the host's own containers.</p>\n<p>Default: <code>'container'</code></p></dd>\n<dt><code><strong>debugMode</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#debugmode\"><span class=\"font-mono\">DebugMode</span></a>[]</code></dt>\n<dd><p>Debug mode flags for enabling development-time diagnostics.</p></dd>\n<dt><code><strong>environment</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#environment\"><span class=\"font-mono\">Environment</span></a></code></dt>\n<dd><p>Theme variant to apply: - `'businessManager'`: BM theme is applied and cannot be overridden. - `'liveSite'`: liveSite theme is applied and can be overridden via `theme`.   'liveSite'</p></dd>\n<dt><code><strong>baseUrl</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Base URL of the site, used to resolve page-relative URLs. Must be provided explicitly. If missing, page links will render as relative paths without the site domain.</p></dd>\n<dt><code><strong>biSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#bisettings\"><span class=\"font-mono\">BISettings</span></a></code></dt>\n<dd><p>Business intelligence configuration for analytics and tracking.</p></dd>\n<dt><code><strong>wixClient</strong><span class=\"text-slate-400\">?</span>: WixClient</code></dt>\n<dd><p>Authenticated `WixClient` from `@wix/sdk`. When provided, takes priority over `instance` for authorizing every request the viewer makes. Use this in headless apps where you own the React tree.</p></dd>\n<dt><code><strong>instance</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Per-session Wix instance token. Used when no `wixClient` is provided — Ricos builds an internal client from it.</p></dd>\n<dt><code><strong>msid</strong><span class=\"text-slate-400\">?</span>: string</code></dt>\n<dd><p>Metasite ID. Scopes storage and CDN traffic to the owning site when no `wixClient` is given.</p></dd>\n<dt><code><strong>shouldNormalizeRichContent</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, normalises rich content via `normalizeRicosDocument` before rendering. Set to `false` to skip normalisation when content is already known to be valid.   true</p></dd>\n<dt><code><strong>mediaSettings</strong><span class=\"text-slate-400\">?</span>: MediaSettings</code></dt>\n<dd><p>Media-upload, capture, and resolution settings shared across media plugins.</p></dd>\n<dt style=\"opacity: 0.5;\"><code><strong>linkSettings</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#linksettings\"><span class=\"font-mono\">LinkSettings</span></a></code></dt>\n<dd><p><em>Deprecated.</em> Use `generalLinkSettings` instead.</p></dd>\n<dt style=\"opacity: 0.5;\"><code><strong>experiments</strong><span class=\"text-slate-400\">?</span>: AvailableExperiments</code></dt>\n<dd><p><em>Deprecated.</em> Not used at runtime.</p></dd>\n</dl>\n\n#### `seoSettings`\n\n```jsx\nseoSettings?: boolean | {\n  paywall: {\n    className: string;\n    index: number;\n  };\n}\n```\n\nWhen given a truthy value, renders RicosViewer in a SEO optimized mode.\nAn object allows extended configuration.\n\n##### `paywall`\n\nclassName - Content blocked by a payall will be marked up using this string (This class will be used by Googlebot to discern between paid and free content on a page level)\nindex - number of free content blocks\n\n#### `addAnchors`\n\nTODO\n\n#### `textSelectionToolbar`\n\nWhen given a truthy value, text-selection-toolbar appears inline when selecting some text and allows tweet text.\n\nSelect some text below to see text-selection-toolbar\n\n```tsx widget\nimport '@wix/ricos/css/all-plugins-viewer.css';\nimport { quickStartViewerPlugins, RicosViewer } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  return (\n    // @essential-start\n    <div style={{ position: 'relative' }}>\n      <RicosViewer textSelectionToolbar plugins={quickStartViewerPlugins()} content={demoContent} />{' '}\n    </div>\n    // @essential-end\n  );\n};\n```\n",
   "theming": "## Theming\n\n### Ricos Theme\n\n#### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">RicosTheme</span>\n\nTheme input for `RicosEditor` and `RicosViewer`. Values flow into CSS variables consumed by every plugin, the toolbars, and the settings panels — prefer this over wrapping Ricos with external CSS, because external CSS only reaches the editable area, not the chrome. Pair `colorPalette` (broad colors) with `customStyles` (per-element overrides) for full control.\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> RicosTheme</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>colorPalette</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricospalette\"><span class=\"font-mono\">RicosPalette</span></a></code></dt>\n<dd><p>Global color tokens shared across all plugins, toolbars, and settings panels.</p></dd>\n</dl>\n\n<div class=\"pl-4 border-l-2 border-slate-200 mb-4\">\n\n```tsx widget\nimport { fromPlainText, pluginHashtag, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  return (\n    <div style={{ background: '#C9C9C9' }}>\n      <RicosEditor\n        initialContent={fromPlainText('This is a #hashtag, see it has a unique color.')}\n        placeholder=\"Type here!\"\n        theme={{\n          colorPalette: {\n            format: 'color',\n            bgColor: '#0E092B',\n            textColor: '#FFFFFF',\n            accent1: '#D6FF00',\n          },\n        }}\n        plugins={[pluginHashtag()]}\n      />\n    </div>\n  );\n  // @essential-end\n};\n```\n\n</div>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>typography</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricostypography\"><span class=\"font-mono\">RicosTypography</span></a></code></dt>\n<dd><p>Typography tokens. `fontFamily` cascades to every text node unless a `customStyles.&lt;element&gt;.fontFamily` overrides it.</p></dd>\n<dt><code><strong>customStyles</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricoscustomstyles\"><span class=\"font-mono\">RicosCustomStyles</span></a></code></dt>\n<dd><p>Per-element style overrides for headings, paragraphs, quotes, plugin cards, and the editor container itself.</p></dd>\n</dl>\n\n<div class=\"pl-4 border-l-2 border-slate-200 mb-4\">\n\n```tsx widget\nimport { fromPlainText, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  const theme = {\n    customStyles: {\n      h2: {\n        fontFamily: 'Times',\n        fontSize: '26px',\n        color: 'orange',\n        fontStyle: 'italic',\n        textDecoration: 'underline',\n      },\n      h3: {\n        fontFamily: 'Tahoma',\n        fontSize: '20px',\n        color: 'purple',\n        textDecoration: 'none',\n      },\n      quote: {\n        lineHeight: '24px',\n        fontWeight: 'bold',\n        color: 'brown',\n      },\n    },\n  };\n\n  return (\n    <RicosEditor\n      initialContent={fromPlainText('Apply heading 2 or 3 from the toolbar to see the styles.')}\n      placeholder=\"Type here!\"\n      theme={theme}\n    />\n  );\n  // @essential-end\n};\n```\n\n</div>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>settingsStyles</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricossettingsstyles\"><span class=\"font-mono\">RicosSettingsStyles</span></a></code></dt>\n<dd><p>Style overrides for settings modals (z-index layering). Most fields are deprecated — only `modals` is supported going forward.</p></dd>\n<dt><code><strong>nativeStyle</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#ricosnativestyles\"><span class=\"font-mono\">RicosNativeStyles</span></a></code></dt>\n<dd><p>React-Native-flavoured style overrides; only consumed when `useNativeStyles` is `true`.</p></dd>\n<dt><code><strong>useWixStyles</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, applies the Wix Studio default theme on top of the supplied values.</p></dd>\n<dt><code><strong>useNativeStyles</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, switches the renderer to consume `nativeStyle` instead of CSS overrides — used by mobile builds.</p></dd>\n<dt><code><strong>breakout</strong><span class=\"text-slate-400\">?</span>: {         rule: ({ node }: {             node: <a href=\"/api-docs/related-types#ricosdocumentnode\"><span class=\"font-mono\">RicosDocumentNode</span></a>;         }) =&gt; 'fullWidth' | 'normal';         normalPadding: {             start: CSSProperties['paddingInlineStart'];             end: CSSProperties['paddingInlineEnd'];         };         fullWidthPadding?: {             start: CSSProperties['paddingInlineStart'];             end: CSSProperties['paddingInlineEnd'];         };     }</code></dt>\n<dd><p>Breakout layout: lets specific nodes flow beyond the content column to viewport edges. `rule` is called once per node at layout time; return `'fullWidth'` for the chosen nodes (typically images and galleries) and `'normal'` for everything else. `fullWidthPadding` overrides `normalPadding` for the `'fullWidth'` case.</p></dd>\n</dl>\n\n### Recipes\n\n#### Choosing between `colorPalette` and `customStyles`\n\n`colorPalette` is the broad brush — a small set of color tokens (`bgColor`, `textColor`, `accent1..4`, `shade1..3`) that flow into every plugin's CSS variables. Set it once and the editor, toolbars, settings panels, and every plugin card pick up the new colors together.\n\n`customStyles` is the per-element scalpel. Reach for it when you need to override font, size, padding, or borders on a specific element (`h1`, `quote`, `editor`, `footerToolbar`, …). When both apply to the same element, `customStyles` wins.\n\n#### Color formats\n\n`RicosPalette.format` controls how Ricos interprets every other value in the palette:\n\n- `'color'` — values are standard CSS color strings (hex, `rgb()`, named colors). This is what most consumers want.\n- `'rgbTuple'` — values are bare `R, G, B` triples (e.g. `'132, 84, 252'`). Use this mode when you want Ricos to derive opacity variants downstream (`rgba(R, G, B, 0.5)` etc.) — applying an alpha channel to a hex string isn't possible.\n\nThe same key names work in both modes — only the format of the values changes.\n\n```tsx widget\nimport { fromPlainText, pluginHashtag, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => (\n  <div style={{ background: '#C9C9C9' }}>\n    {/* @essential-start */}\n    <RicosEditor\n      initialContent={fromPlainText('This is a #hashtag, see it has a unique color.')}\n      placeholder=\"Type here!\"\n      theme={{\n        colorPalette: {\n          format: 'color',\n          bgColor: '#0E092B',\n          textColor: '#FFFFFF',\n          accent1: '#D6FF00',\n        },\n      }}\n      plugins={[pluginHashtag()]}\n    />\n    {/* @essential-end */}\n  </div>\n);\n```\n\n#### Per-element `customStyles`\n\nMost consumers only touch `h1..h6`, `p`, `link`, `quote`. The full surface is in the `RicosCustomStyles` table — link to it from the row above. A few less obvious entries worth knowing:\n\n- `editor` — controls the editable container's `minHeight`/`maxHeight`, placeholder color, and the position of the inline plus button.\n- `footerToolbar` — controls the inline plus-button bar at the bottom of the editor.\n- `card` — the per-plugin selection chrome (selection border, background image, padding).\n- `container` — the outermost wrapper's top/bottom padding.\n\n```tsx widget\nimport { fromPlainText, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  const theme = {\n    customStyles: {\n      h2: {\n        fontFamily: 'Times',\n        fontSize: '26px',\n        color: 'orange',\n        fontStyle: 'italic',\n        textDecoration: 'underline',\n      },\n      h3: {\n        fontFamily: 'Tahoma',\n        fontSize: '20px',\n        color: 'purple',\n        textDecoration: 'none',\n      },\n      quote: {\n        lineHeight: '24px',\n        fontWeight: 'bold',\n        color: 'brown',\n      },\n    },\n  };\n\n  return (\n    <RicosEditor\n      initialContent={fromPlainText('Apply heading 2 or 3 from the toolbar to see the styles.')}\n      placeholder=\"Type here!\"\n      theme={theme}\n    />\n  );\n  // @essential-end\n};\n```\n\n#### `font` shorthand\n\nText elements (`h1..h6`, `p`, `quote`, `link`, `hashtag`) accept the CSS `font` shorthand as an alternative to font longhands (`fontSize`, `fontFamily`, `fontWeight`, `fontStyle`, `lineHeight`); when `font` is set, the element's `fontSize`, `fontWeight`, `fontStyle` and `lineHeight` are ignored. `font` takes a literal value or a `var()` reference, so a host theme token such as `var(--wst-heading-1-font)` can be passed as is.\n\n- When `font` is set, it alone defines the element's font: Ricos font defaults do not apply, and parts the shorthand omits (style, variant, weight, stretch, line height) reset to `normal`, as in CSS. `font-size` and `font-family` are required by the shorthand.\n- Document styles still win: a heading size or weight set in the document overrides the shorthand.\n- Other properties (`color`, `letterSpacing`, `textDecoration`, …) combine with `font` as usual.\n- Elements that only borrow a text element's font family (plugin titles and labels, buttons, captions) take just the family from its shorthand and keep their own size, weight and line height.\n- Also pass the shorthand's family as `fontFamily` (on `h1` and `p` at least). The rendered font still comes from `font`, but the HTML embed and the font family dropdown read the family from `fontFamily`, since they can't resolve a `var()`.\n- If a `var()` reference is undefined at runtime, the element inherits its font. Add a fallback inside the value: `var(--wst-heading-1-font, 700 32px/1.2 sans-serif)`.\n- If the font's size uses container units (`cqw`), as Wix Studio's site theme fonts do, also pass `responsiveBehavior=\"viewport\"` to the editor and viewer. Otherwise the units measure Ricos's own width instead of the host container's, and the text shrinks.\n\n```tsx widget\nimport { fromPlainText, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  const theme = {\n    customStyles: {\n      h2: { font: 'italic 700 28px/1.3 Georgia, serif', color: 'teal' },\n      p: {\n        font: 'var(--my-body-font, 16px/1.6 Helvetica, sans-serif)',\n        fontFamily: 'Helvetica, sans-serif',\n      },\n    },\n  };\n\n  return (\n    <RicosEditor\n      initialContent={fromPlainText('Apply heading 2 from the toolbar to see the shorthand.')}\n      placeholder=\"Type here!\"\n      theme={theme}\n    />\n  );\n  // @essential-end\n};\n```\n\n#### Breakout layout\n\n`breakout.rule({ node }) => 'fullWidth' | 'normal'` runs once per node at layout time. Return `'fullWidth'` to let that node flow to the viewport edges; return `'normal'` (or omit the field entirely) to keep it inside the content column. `fullWidthPadding` overrides `normalPadding` for the `'fullWidth'` case, so you can leave a small inset even on edge-to-edge images.\n\nTypical use: media plugins (`image`, `gallery`, `video`) go full-width on large viewports; text stays in the content column.\n",
   "plugins/audio": "## Plugins\n\n### Audio Plugin\n\nThe Audio plugin lets users upload audio files or embed audio from SoundCloud and Spotify.\n\n#### Editor\n\n```tsx widget\nimport { pluginAudio, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => (\n  // @essential-start\n  <RicosEditor placeholder={'Upload an audio file...'} plugins={[pluginAudio()]} />\n  // @essential-end\n);\n```\n\n##### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">AudioPluginEditorConfig</span>\n\nConfiguration for the Audio editor plugin. Pass to `pluginAudio()`.\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> AudioPluginEditorConfig</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>exposeButtons</strong><span class=\"text-slate-400\">?</span>: <a href=\"/api-docs/related-types#audiobutton\"><span class=\"font-mono\">AudioButton</span></a>[]</code></dt>\n<dd><p>Controls which audio source buttons appear in the toolbar insert menu. By default, only the file-upload (`'audio'`) button is shown. Add `'soundCloud'` and `'spotify'` to enable embedding from those services.</p>\n<p>Default: <code>`['audio']`</code></p></dd>\n<dt><code><strong>disableDownload</strong><span class=\"text-slate-400\">?</span>: boolean</code></dt>\n<dd><p>When `true`, disables the download button on newly inserted audio blocks.</p>\n<p>Default: <code>true</code></p></dd>\n<dt><code><strong>getAudioUrl</strong><span class=\"text-slate-400\">?</span>: (src: {         id: string;     }) =&gt; string</code></dt>\n<dd><p>Resolves an audio file ID to a full playback URL. Called when rendering audio nodes that store a relative source (e.g. Wix Media). If not provided, a default Wix Media resolver is used.</p></dd>\n</dl>\n\nTo expose SoundCloud and Spotify embed buttons alongside the default file-upload button:\n\n```tsx widget\nimport { pluginAudio, RicosEditor } from '@wix/ricos';\nimport React from 'react';\n\nexport default () => (\n  // @essential-start\n  <RicosEditor\n    placeholder={'Upload audio, or embed from SoundCloud / Spotify...'}\n    plugins={[pluginAudio({ exposeButtons: ['audio', 'soundCloud', 'spotify'] })]}\n  />\n  // @essential-end\n);\n```\n\n#### Viewer\n\n```tsx widget\n// @essential-start\nimport '@wix/ricos/css/plugin-audio-viewer.global.css';\nimport '@wix/ricos/css/ricos-viewer.global.css';\nimport { pluginAudioViewer, type RicosDocument, RicosViewer } from '@wix/ricos';\n// @essential-end\nimport React from 'react';\n\nexport default () => {\n  // @essential-start\n  return <RicosViewer content={content} plugins={[pluginAudioViewer()]} />;\n  // @essential-end\n};\n\nconst content = {\n  nodes: [\n    {\n      type: 'PARAGRAPH',\n      id: 'foo',\n      nodes: [],\n      paragraphData: {\n        textStyle: {\n          textAlignment: 'AUTO',\n        },\n        indentation: 0,\n      },\n    },\n    {\n      type: 'AUDIO',\n      id: '8q61c',\n      nodes: [],\n      audioData: {\n        containerData: {\n          alignment: 'CENTER',\n          width: {\n            size: 'CONTENT',\n          },\n          textWrap: true,\n        },\n        audio: {\n          src: {\n            id: 'mp3/f0f74f_48772df0375c41cd88e8e29370ccf899',\n          },\n        },\n        disableDownload: true,\n        coverImage: {\n          src: {\n            id: 'f0f74f_2973832f552e4002b58ec6abbe7fce71~mv2.png',\n          },\n          width: 436,\n          height: 524,\n        },\n        name: 'Dear Fear',\n        authorName: 'Kota The Friend',\n      },\n    },\n  ],\n} as RicosDocument;\n```\n\n##### <span style=\"font-weight: 700;\" class=\"rounded-lg border-[1px] border-blue-300 font-mono border-none bg-blue-100 px-2 py-1 leading-[18px] tracking-[0.0175em] font-bold text-slate-900\">AudioPluginViewerConfig</span>\n\nConfiguration for the Audio viewer plugin. Pass to `pluginAudioViewer()`.\n\n<code class=\"font-mono text-sm\"><span class=\"text-blue-700\">interface</span> AudioPluginViewerConfig</code>\n\n<dl class=\"pl-4 border-l-2 border-slate-200\">\n<dt><code><strong>getAudioUrl</strong><span class=\"text-slate-400\">?</span>: (src: {         id: string;     }) =&gt; string</code></dt>\n<dd><p>Resolves an audio file ID to a full playback URL. Called when rendering audio nodes that store a relative source (e.g. Wix Media). If not provided, a default Wix Media resolver is used.</p></dd>\n</dl>\n",