` - the same markup the tools produce, so the saved blocks are identical.
- **Source map**: `sourceMap(el, markdown)` gives every block's range in the Markdown (the blocks `setMarkdown()` renders from the same string), and `locate(el, markdown, start, end)` turns a span of the source into `{ block, text, occurrence }` - the block that renders it and its text there, without heading marks, list markers or inline Markdown. That is a Document Comments span: annotations made against a Markdown file (a review that quotes `# Einschränkung`) anchor in the editor. Normalize `\r\n` to `\n` first - marked does.
- The skill does not restate Editor.js's API: `df$.shadcn.editorjs.editor(el)` returns the instance for anything beyond this surface.
## API
### States
type EditorjsState = 'default' | 'readonly' - `setState(name, config)` takes the config of the state it names (`EditorjsStateConfigs[name]`).
| State | Description |
|---|---|
| `default` | Editable: the editor accepts input, the toolbar commands apply. No config. |
| `readonly` | Read only: the document shows, nothing edits it (data-readonly on the element). No config. |
### Every element
| Member | Description |
|---|---|
| el.api.setState<S extends EditorjsState>(name: S, config?: EditorjsStateConfigs[S]): unknown | Enter a state: the DOM work runs (also when it is the current state), the store records it. Argument Type Description nameSa declared state (an unknown name throws) config?EditorjsStateConfigs[S]that state's config (merged into the stored one when the component merges)
Returns unknown - what the state's DOM work returned - a Promise for an async state (or await settled()) |
| el.api.getState(): { name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel } | The state the element shows now - read back from the DOM, so it includes what the user changed. Returns { name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from |
| el.api.render(state?: { name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel }): string | The element's markup in a state - the authored markup with that state applied; a pure function of the state. Argument Type Description state?{ name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel }a state as getState() returns it (default: the current one)
Returns string - the element's outer HTML in that state |
| el.api.settled(): Promise<void> | Wait for the last state's DOM work (async states: a diagram rendering, a chart mounting). Returns Promise<void> - resolves when nothing is pending |
| el.store: Store<{ name: EditorjsState; config: EditorjsStateConfigs[EditorjsState] }> | A defuss-store store of the element's state - subscribe to follow every change (also the user's), set it to drive the component. |
### Registry
| Member | Description |
|---|---|
| df$.shadcn.editorjsApi.setState<S extends EditorjsState>(el: HTMLElement, name: S, config?: EditorjsStateConfigs[S]): unknown | Enter a state: the DOM work runs (also when it is the current state), the store records it. Argument Type Description elHTMLElementthe component's element nameSa declared state (an unknown name throws) config?EditorjsStateConfigs[S]that state's config (merged into the stored one when the component merges)
Returns unknown - what the state's DOM work returned - a Promise for an async state (await it, or el.api.settled()) |
| df$.shadcn.editorjsApi.getState(el: HTMLElement): { name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel } | The state the element shows now - read back from the DOM, so it includes what the user changed. Argument Type Description elHTMLElementthe component's element
Returns { name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from |
| df$.shadcn.editorjsApi.render(state: { name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel }): string | The element's markup in a state - the authored markup with that state applied; a pure function of the state. Argument Type Description state{ name: EditorjsState; config: EditorjsStateConfigs[EditorjsState]; model?: ElementModel }a state as getState() returns it (with its model)
Returns string - the element's outer HTML in that state |
| df$.shadcn.editorjsApi.store(el: HTMLElement): Store<{ name: EditorjsState; config: EditorjsStateConfigs[EditorjsState] }> | The element's store (bindComponent made it). Argument Type Description elHTMLElementthe component's element
Returns Store<{ name: EditorjsState; config: EditorjsStateConfigs[EditorjsState] }> - a defuss-store store of { name, config } - subscribe to follow every change, set it to drive the component |
| df$.shadcn.editorjsApi.commit<S extends EditorjsState>(el: HTMLElement, name: S, config?: EditorjsStateConfigs[S]): void | Record a state the element reached on its own (no DOM work) - for a component's own handlers. Argument Type Description elHTMLElementthe component's element nameSthe state it is in config?EditorjsStateConfigs[S]its config
|
| df$.shadcn.editorjsStates: EditorjsState[] | The declared states, 'default' first: default, readonly. |
### `df$.shadcn.editorjs`
| Member | Description |
|---|---|
| load(url?: string): Promise<unknown> | Load the pinned editor build ahead of the first element (or a self-hosted copy). Argument Type Description url?stringthe Editor.js ESM module to load instead of the pinned one
Returns Promise<unknown> - resolves when the module is loaded |
| url: string | The pinned Editor.js build the component loads. |
| markdown(target: string \| HTMLElement): Promise<string> | The document as Markdown - headings, paragraphs, lists (nested, checklists), quotes, code, rules, tables; inline bold, italic, code and links. Argument Type Description targetstring \| HTMLElementthe .editorjs element or its selector
Returns Promise<string> - the Markdown, '' before the editor is ready |
| setMarkdown(target: string \| HTMLElement, markdown: string): Promise<void> | Replace the document with Markdown. Argument Type Description targetstring \| HTMLElementthe .editorjs element or its selector markdownstringthe new document
Returns Promise<void> - resolves once the blocks are rendered |
| blocks(target: string \| HTMLElement): Promise<EditorjsDocument \| null> | The document as Editor.js data (blocks with their ids). Argument Type Description targetstring \| HTMLElementthe .editorjs element or its selector
Returns Promise<EditorjsDocument \| null> - the saved document, or null before the editor is ready |
| setBlocks(target: string \| HTMLElement, data: EditorjsDocument): Promise<void> | Replace the document with Editor.js data. Argument Type Description targetstring \| HTMLElementthe .editorjs element or its selector dataEditorjsDocumentthe blocks to render
Returns Promise<void> - resolves once the blocks are rendered |
| command(target: string \| HTMLElement, name: string): Promise<boolean> | Run a formatting command on the current selection or block - what a toolbar button with data-editor-command sends. Argument Type Description targetstring \| HTMLElementthe .editorjs element or its selector namestringbold, italic, underline, marker, inline-code, paragraph, header:1-6, list:unordered\|ordered\|checklist, quote, code, delimiter, table
Returns Promise<boolean> - true when the command applied |
| editor(target: string \| HTMLElement): unknown | The Editor.js instance behind an element, for anything this API does not cover. Argument Type Description targetstring \| HTMLElementthe .editorjs element or its selector
Returns unknown - the editor, or undefined before it mounted |
| toBlocks(target: string \| HTMLElement, markdown: string): EditorjsBlock[] | Markdown → Editor.js blocks, with the parser the component loaded (after the first editor is ready). Argument Type Description targetstring \| HTMLElementany mounted .editorjs element or its selector (its parser is used) markdownstringthe Markdown to convert
Returns EditorjsBlock[] - the blocks, [] before a parser is loaded |
| sourceMap(target: string \| HTMLElement, markdown: string): EditorjsSourceRange[] | Where each block of a Markdown document comes from - its id, its tool and its range in the source, the blocks setMarkdown() renders from the same Markdown. Argument Type Description targetstring \| HTMLElementany mounted .editorjs element or its selector (its parser is used) markdownstringthe Markdown the blocks are rendered from
Returns EditorjsSourceRange[] - one range per block, in document order; [] before a parser is loaded |
| locate(target: string \| HTMLElement, markdown: string, start: number, end: number): EditorjsLocation \| null | A span of the Markdown source as the editor shows it: the block that renders it, its text there and which occurrence of that text it is - the anchor an annotation made against the Markdown needs (a Document Comments span). A span that runs past its block is cut at the block's end. Argument Type Description targetstring \| HTMLElementany mounted .editorjs element or its selector (its parser is used) markdownstringthe Markdown the editor rendered (setMarkdown() or the element's source) startnumberwhere the span starts in the source (UTF-16 offset) endnumberwhere it ends, exclusive
Returns EditorjsLocation \| null - the block, the rendered text and its occurrence (0 = the first); null when the span holds no text of a block |
| toMarkdown(blocks: EditorjsBlock[]): string | Editor.js blocks → Markdown. Argument Type Description blocksEditorjsBlock[]the blocks to serialize
Returns string - the Markdown |
### Events
| Event | Description |
|---|---|
| `editorjs-change` | Fires after the document changed (typing, a block added or converted, a toolbar command) - how many blocks it has now. detail: EditorjsChangeDetail Field Type Description blocksnumberhow many blocks the document has after the change
|
| `editorjs-ready` | Fires once the editor mounted its blocks - the count it started with. detail: EditorjsReadyDetail Field Type Description blocksnumberhow many blocks the document started with
|
### Types
| Type | Description |
|---|---|
| `EditorjsBlock` | One Editor.js block, as the editor saves it. Field Type Description id?stringthe block's id (Editor.js writes it on .ce-block[data-id]) typestringthe tool: paragraph, header, list, quote, code, delimiter, table dataRecord<string, unknown>the tool's data
|
| `EditorjsChangeDetail` | What editorjs-change carries. Field Type Description blocksnumberhow many blocks the document has after the change
|
| `EditorjsDocument` | The saved document: Editor.js output data. Field Type Description blocksEditorjsBlock[]the blocks, in order version?stringthe editor's version, when saved by it time?numberwhen it was saved, ms since the epoch
|
| `EditorjsLocation` | A span of the Markdown source as the editor shows it - the shape a Document Comments span takes. Field Type Description blockstringthe id of the block that renders the span textstringthe span's text as rendered in that block: no heading marks, list markers or inline Markdown occurrencenumberwhich occurrence of that text in the block it is (0 = the first)
|
| `EditorjsReadyDetail` | What editorjs-ready carries. Field Type Description blocksnumberhow many blocks the document started with
|
| `EditorjsSourceRange` | Where one block of a Markdown document comes from. Field Type Description blockstringthe block's id (b1, b2, ... - the id setMarkdown() renders it with) typestringthe tool that renders it: header, paragraph, list, quote, code, delimiter, table level?numberthe heading level, for a header block startnumberwhere the block starts in the Markdown (UTF-16 offset) endnumberwhere it ends, exclusive (the blank lines after it belong to the gap, not the block)
|