@duplicati/ngclient 0.0.227 → 0.0.229

package/ship-ui-assets/mcp/components.json

@@ -18,6 +18,163 @@
     "cssVariables": [],
     "examples": []
   },
+  {
+    "name": "ShipEditorRegistry",
+    "selector": "ship-editor-registry",
+    "path": "core/projects/ship-ui/ship-editor/ship-editor-core.ts",
+    "description": "### Usage\n\nShipEditor is a premium, config-driven WYSIWYG rich text editor. It allows typing in design view, editing raw source code, and can serialize to `html`, `markdown`, or `json` configuration dynamically.\n\n### Features\n\n- Three output formats: HTML strings, Markdown text, and custom structured block/mark JSON.\n- ControlValueAccessor integration for Reactive and Template-driven forms.\n- Monospace code-view for editing source code directly.\n- Dynamic toolbar selection tracking.\n- Word and character count reporting in the status footer.",
+    "keywords": [
+      "editor",
+      "wysiwyg",
+      "richtext",
+      "html",
+      "markdown",
+      "json",
+      "input",
+      "form"
+    ],
+    "inputs": [],
+    "outputs": [],
+    "methods": [
+      {
+        "name": "runTransaction",
+        "parameters": "action: (\n      doc: ShipEditorDocument,\n      selection: { start: LogicalPosition; end: LogicalPosition }\n    ) =>\n      | {\n          doc?: ShipEditorDocument;\n          selectionShift?: {\n            start: { blockIndex: number; listItemIndex?: number };\n            end: { blockIndex: number; listItemIndex?: number };\n          };\n        }\n      | ShipEditorDocument\n      | void\n      | null",
+        "returnType": "void;\n  applyInlineStyle(tag: string): void;\n  toggleLink(url: string): void;\n  setBlockType(tag: string): void;\n  toggleList(listType: 'ul' | 'ol'): void;\n  insertHorizontalRule(): void;\n  setAlign(direction: 'left' | 'center' | 'right'): void;\n  removeFormat(): void;\n  insertImage(url: string): void;\n  undo(): void;\n  redo(): void;\n  selectBlockType(tag: string): void;\n  formatText(command: string, value?: string): void;\n  openImageModal(): void;\n  openLinkModal(): void;\n}\n\nexport interface ShipEditorCommand",
+        "description": ""
+      },
+      {
+        "name": "registerMark",
+        "parameters": "ext: ShipEditorMarkExtension",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "getAllMarks",
+        "parameters": "",
+        "returnType": "ShipEditorMarkExtension[]",
+        "description": ""
+      },
+      {
+        "name": "registerBlock",
+        "parameters": "ext: ShipEditorBlockExtension",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "getAllBlocks",
+        "parameters": "",
+        "returnType": "ShipEditorBlockExtension[]",
+        "description": ""
+      },
+      {
+        "name": "clear",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "registerDefaults",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "registerDefaultMarks",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "clearBlocks",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "sanitizeNode",
+        "parameters": "child);\n  }\n\n  return body.innerHTML;\n}\n\n// HTML => JSON Converter\nexport function htmlToJSON(\n  html: string,\n  docObj: Document = globalThis.document,\n  registry: ShipEditorRegistry = ShipEditorRegistry.getInstance()",
+        "returnType": "ShipEditorDocument",
+        "description": ""
+      },
+      {
+        "name": "traverse",
+        "parameters": "child);\n  }\n\n  return md;\n}\n\n// Markdown => HTML Converter\nexport function markdownToHTML(\n  markdown: string,\n  registry: ShipEditorRegistry = ShipEditorRegistry.getInstance()",
+        "returnType": "string",
+        "description": ""
+      },
+      {
+        "name": "while",
+        "parameters": "(n = walker.nextNode())",
+        "returnType": "any",
+        "description": ""
+      }
+    ],
+    "cssVariables": [
+      {
+        "name": "--editor-bg",
+        "defaultValue": "var(--base-1)"
+      },
+      {
+        "name": "--editor-code-bg",
+        "defaultValue": "var(--base-2)"
+      },
+      {
+        "name": "--editor-border-color",
+        "defaultValue": "var(--base-4)"
+      },
+      {
+        "name": "--editor-toolbar-bg",
+        "defaultValue": "rgb(from var(--base-1) r g b / 70%)"
+      },
+      {
+        "name": "--editor-toolbar-border",
+        "defaultValue": "var(--base-4)"
+      },
+      {
+        "name": "--editor-btn-hover",
+        "defaultValue": "var(--base-3)"
+      },
+      {
+        "name": "--editor-btn-active-bg",
+        "defaultValue": "var(--primary-3)"
+      },
+      {
+        "name": "--editor-btn-active-c",
+        "defaultValue": "var(--primary-11)"
+      },
+      {
+        "name": "--editor-footer-bg",
+        "defaultValue": "var(--base-2)"
+      },
+      {
+        "name": "--editor-p",
+        "defaultValue": "#{p2r(16)} #{p2r(20)}"
+      },
+      {
+        "name": "--editor-min-h",
+        "defaultValue": "#{p2r(220)}"
+      },
+      {
+        "name": "--editor-border-focus",
+        "defaultValue": "var(--primary-8)"
+      },
+      {
+        "name": "--editor-shadow-focus",
+        "defaultValue": "0 0 0 3px var(--primary-3)"
+      },
+      {
+        "name": "--editor-shape",
+        "defaultValue": "var(--shape-3)"
+      }
+    ],
+    "examples": [
+      {
+        "name": "sandbox-editor",
+        "html": "<div class=\"sandbox-container\">\n  <div class=\"sandbox-sidebar\">\n    <sh-card class=\"type-b control-card\">\n      <h3>Options</h3>\n\n      <div class=\"control-group\">\n        <label class=\"control-label\">Storage Format</label>\n        <sh-button-group size=\"small\" [value]=\"selectedFormat()\" (valueChange)=\"onFormatChange($event)\">\n          <button value=\"html\">HTML</button>\n          <button value=\"markdown\">Markdown</button>\n          <button value=\"json\">JSON</button>\n        </sh-button-group>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"readonly-toggle\" class=\"control-label\">Read-Only</label>\n        <sh-toggle id=\"readonly-toggle\" [(checked)]=\"isReadonly\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"toolbar-toggle\" class=\"control-label\">Show Toolbar</label>\n        <sh-toggle id=\"toolbar-toggle\" [(checked)]=\"showToolbar\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"image-upload-toggle\" class=\"control-label\">Image Upload</label>\n        <sh-toggle id=\"image-upload-toggle\" [(checked)]=\"imageUploadEnabled\"></sh-toggle>\n      </div>\n\n      @if (showToolbar()) {\n        <div class=\"control-group-section-title\">Toolbar Groups</div>\n\n        <div class=\"control-group inline\">\n          <label for=\"formats-toggle\" class=\"control-label\">Formats</label>\n          <sh-toggle id=\"formats-toggle\" [(checked)]=\"showFormats\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"blocks-toggle\" class=\"control-label\">Blocks/Headings</label>\n          <sh-toggle id=\"blocks-toggle\" [(checked)]=\"showBlocks\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"lists-toggle\" class=\"control-label\">Lists</label>\n          <sh-toggle id=\"lists-toggle\" [(checked)]=\"showLists\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"align-toggle\" class=\"control-label\">Alignments</label>\n          <sh-toggle id=\"align-toggle\" [(checked)]=\"showAlignments\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"insert-toggle\" class=\"control-label\">Insertions</label>\n          <sh-toggle id=\"insert-toggle\" [(checked)]=\"showInsertions\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"history-toggle\" class=\"control-label\">History/Code</label>\n          <sh-toggle id=\"history-toggle\" [(checked)]=\"showHistory\"></sh-toggle>\n        </div>\n      }\n    </sh-card>\n  </div>\n\n  <div class=\"sandbox-editor-wrapper\">\n    <sh-editor\n      [(value)]=\"editorValue\"\n      [format]=\"selectedFormat()\"\n      [readonly]=\"isReadonly()\"\n      [toolbar]=\"showToolbar()\"\n      [showFormats]=\"showFormats()\"\n      [showBlocks]=\"showBlocks()\"\n      [showLists]=\"showLists()\"\n      [showAlignments]=\"showAlignments()\"\n      [showInsertions]=\"showInsertions()\"\n      [showHistory]=\"showHistory()\"\n      [customCommands]=\"customEditorCommands()\"\n      [imageUploadEnabled]=\"imageUploadEnabled()\"\n      placeholder=\"Start writing your premium content here...\">\n      <!-- Projected custom toolbar action -->\n      <!-- <button type=\"button\" class=\"sh-editor-btn\" (click)=\"customAction()\" shTooltip=\"Projected Action (Star)\">\n        <sh-icon>star</sh-icon>\n      </button> -->\n    </sh-editor>\n\n    <sh-card class=\"type-b output-card\">\n      <div class=\"output-header\">\n        <h3>Database Output</h3>\n        <button shButton variant=\"outlined\" size=\"small\" (click)=\"copyToClipboard()\">\n          <sh-icon>copy</sh-icon>\n          Copy\n        </button>\n      </div>\n      <p class=\"output-desc\">This is exactly what would be saved in your database:</p>\n      <pre class=\"serialized-preview\"><code>{{ serializedOutput() }}</code></pre>\n    </sh-card>\n  </div>\n</div>\n",
+        "ts": "import { ChangeDetectionStrategy, Component, computed, signal, viewChild } from '@angular/core';\nimport { ShipColor } from '@ship-ui/core';\nimport { ShipButton } from '@ship-ui/core/ship-button';\nimport { ShipButtonGroup } from '@ship-ui/core/ship-button-group';\nimport { ShipCard } from '@ship-ui/core/ship-card';\nimport { ShipEditor, ShipEditorCommand, ShipEditorRegistry, ShipEditorValue } from '@ship-ui/core/ship-editor';\nimport { ShipIcon } from '@ship-ui/core/ship-icon';\nimport { ShipToggle } from '@ship-ui/core/ship-toggle';\n\n@Component({\n  selector: 'app-sandbox-editor',\n  standalone: true,\n  imports: [ShipEditor, ShipButton, ShipCard, ShipToggle, ShipIcon, ShipButtonGroup],\n  templateUrl: './sandbox-editor.html',\n  styleUrl: './sandbox-editor.scss',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class SandboxEditor {\n  constructor() {\n    // Register custom highlight mark extension\n    ShipEditorRegistry.getInstance().registerMark({\n      type: 'highlight',\n      tagName: 'mark',\n      toHTML: (mark: any, text: string) =>\n        `<mark style=\"background-color: var(--warn-2); color: var(--warn-11); padding: 2px 4px; border-radius: 2px;\">${text}</mark>`,\n      parseHTML: (el: HTMLElement) => (el.tagName.toLowerCase() === 'mark' ? { type: 'highlight' } : null),\n    });\n  }\n\n  // Current format selection\n  selectedFormat = signal<'html' | 'markdown' | 'json'>('html');\n\n  editor = viewChild(ShipEditor);\n\n  // Editor states\n  isReadonly = signal<boolean>(false);\n  showToolbar = signal<boolean>(true);\n  selectedColor = signal<ShipColor | null>(null);\n  imageUploadEnabled = signal<boolean>(true);\n\n  // Toolbar group configurations\n  showFormats = signal<boolean>(true);\n  showBlocks = signal<boolean>(true);\n  showLists = signal<boolean>(true);\n  showAlignments = signal<boolean>(true);\n  showInsertions = signal<boolean>(true);\n  showHistory = signal<boolean>(true);\n\n  // Custom action for projected button\n  customAction() {\n    alert('Custom Projected Button Clicked!');\n  }\n\n  customEditorCommands = signal<ShipEditorCommand[]>([\n    // {\n    //   id: 'highlight',\n    //   label: 'Highlight Text',\n    //   icon: 'star',\n    //   description: 'Highlight selected text in yellow',\n    //   action: (editor) => {\n    //     editor.runTransaction((doc, selection) => {\n    //       return formatDocRange(doc, selection.start, selection.end, 'highlight', 'toggle');\n    //     });\n    //   },\n    // },\n    // {\n    //   id: 'info-callout',\n    //   label: 'Info Callout',\n    //   icon: 'terminal',\n    //   description: 'Insert an info callout box',\n    //   action: (editor) => {\n    //     editor.runTransaction((doc, selection) => {\n    //       const { doc: splitDoc } = splitBlock(doc, selection.start);\n    //       const calloutBlock: ShipEditorBlock = {\n    //         type: 'quote',\n    //         attrs: { align: 'left' },\n    //         content: [{ type: 'text', text: '💡 Info: Start typing callout contents here...' }],\n    //       };\n    //       const targetIndex = selection.start.blockIndex + 1;\n    //       splitDoc.splice(targetIndex, 0, calloutBlock);\n    //       return {\n    //         doc: splitDoc,\n    //         selectionShift: {\n    //           start: { blockIndex: targetIndex },\n    //           end: { blockIndex: targetIndex },\n    //         },\n    //       };\n    //     });\n    //   },\n    // },\n  ]);\n\n  // Pre-populated initial contents for each format\n  initialHtml = `<h1>Ship WYSIWYG Editor</h1><p>Welcome! This is a <strong>config-driven</strong> rich-text editor designed to support flexible storage formats.</p><ul><li><strong>Two-way binding</strong> with <code>ControlValueAccessor</code></li><li>Instant conversion to <strong>HTML</strong>, <strong>Markdown</strong>, or <strong>JSON</strong></li><li>Sticky blur-toolbar, light/dark mode support, and word counting</li></ul><blockquote>\"A beautiful interface makes editing content a delight.\"</blockquote><hr><p>Try changing the storage format below to see the serialized output update in real time!</p>`;\n\n  // Current value model\n  editorValue = signal<ShipEditorValue>(this.initialHtml);\n\n  // Stringified preview for database presentation\n  serializedOutput = computed(() => {\n    const val = this.editorValue();\n    if (val === null || val === undefined) return '';\n    if (typeof val === 'string') return val;\n    return JSON.stringify(val, null, 2);\n  });\n\n  // Handle format swapping, converting the value appropriately\n  onFormatChange(format: string | null) {\n    if (format === 'html' || format === 'markdown' || format === 'json') {\n      this.selectedFormat.set(format);\n    }\n  }\n\n  // Copy serialized contents to clipboard\n  copyToClipboard() {\n    navigator.clipboard.writeText(this.serializedOutput());\n  }\n}\n"
+      }
+    ]
+  },
   {
     "name": "ShipEditor",
     "selector": "sh-editor",
@@ -49,7 +206,7 @@
       {
         "name": "readonly",
         "type": "boolean",
-        "description": "",
+        "description": "Block extensions to use. Defaults to the built-in set. Override to customize behavior or add custom blocks. @example ```typescript import { defaultBlockExtensions, configureExtension, imageBlockExtension } from 'ship-ui/ship-editor'; myExtensions = [   ...defaultBlockExtensions.filter(e => e.type !== 'image'),   configureExtension(imageBlockExtension, { defaultMode: 'content', defaultSize: 'auto' }), ]; ``` / extensions = input<ShipEditorBlockExtension[]>(defaultBlockExtensions); #selectedImage = signal<HTMLImageElement | null>(null); imgMode = signal<'content' | 'theater' | 'float' | 'custom'>('content'); imgSize = signal<'auto' | 'small' | 'medium' | 'large'>('auto'); /** Tracks the DOM element with an extension-driven activeClassName applied. */ #activeBlockEl: HTMLElement | null = null; viewMode = signal<'design' | 'code'>('design'); isFocused = signal<boolean>(false); showLinkModal = signal<boolean>(false); showImageModal = signal<boolean>(false); rawCodeValue = signal<string>(''); showBlockMenu = signal<boolean>(false); isBold = signal<boolean>(false); isItalic = signal<boolean>(false); isUnderline = signal<boolean>(false); isStrike = signal<boolean>(false); align = signal<'left' | 'center' | 'right'>('left'); activeBlock = signal<string>('p'); canUndo = signal<boolean>(false); canRedo = signal<boolean>(false); #savedRange: Range | null = null; documentState = signal<ShipEditorDocument>([]); getBlockInlineHTML(block: any): string { return inlineToHTML((block?.content as ShipEditorInlineNode[]) || []) || '<br>'; } getCodeText(block: ShipEditorBlock): string { return ((block.content as ShipEditorInlineNode[]) || []).map((node) => node.text || '').join(''); } getImageClass(block: ShipEditorBlock): string { const mode = block.attrs?.mode || 'content'; const size = block.attrs?.size || 'auto'; if (mode === 'content' || mode === 'theater') { return `sh-editor-img-${mode}`; } return `sh-editor-img-${mode} sh-editor-img-size-${size}`; } #saveAndRestoreSelection(action: () => void) { if (!this.#isBrowser || this.viewMode() === 'code') { action(); return; } const editor = this.editorRef()?.nativeElement; const saved = editor ? EditorSelection.read(editor) : null; action(); // Synchronous caret restoration — the action uses innerHTML which is // synchronous, so the new DOM nodes are immediately available. if (saved && editor) { EditorSelection.apply(editor, this.documentState(), saved.start, saved.end); } } charCount = signal<number>(0); wordCount = signal<number>(0); onChange: (value: ShipEditorValue) => void = () => {}; onTouched: () => void = () => {}; hostClasses = shipComponentClasses('editor', { color: this.color, variant: this.variant, readonly: this.readonly, }); #isWriting = false; #lastFormat: 'json' | 'html' | 'markdown' | null = null; /** Set the document state and increment the version counter for history deduplication. */ #setDocumentState(doc: ShipEditorDocument) { this.#docVersion++; this.documentState.set(doc); // Update word/char counts from the AST. This is the single source of truth for // programmatic doc changes (transactions, undo, paste, etc.). The onDOMInput() // handler provides instant counts from editor.textContent during typing. const text = getJSONText(doc).replace(/\\u00a0/g, ' ').trim(); this.charCount.set(text.length); this.wordCount.set(text === '' ? 0 : text.split(/\\s+/).filter((w) => w.length > 0).length); } /** Run a callback while suppressing feedback loops (DOM→model→DOM cycles). */ #runWithoutFeedback(fn: () => void) { this.#isWriting = true; try { fn(); } finally { this.#isWriting = false; } } /** Unified state commit: AST → signals → serialized value → DOM. Every document mutation should go through this single path to keep state, value, and DOM in sync and avoid forgotten guards. / #commitDocument( newDoc: ShipEditorDocument, options?: { /** Wrap in #runWithoutFeedback to suppress DOM→model→DOM loops. */ suppressFeedback?: boolean; /** Set #isInternalDOMUpdate to block stale selectionchange events. */ guardSelectionChange?: boolean; /** Preserve scroll position across the DOM re-render. */ preserveScroll?: boolean; /** Skip DOM render (caller handles it or no editor ref). */ skipRender?: boolean; } ) { const opts = { suppressFeedback: false, guardSelectionChange: false, preserveScroll: false, skipRender: false, ...options, }; if (opts.guardSelectionChange) this.#isInternalDOMUpdate = true; const commit = () => { this.#setDocumentState(newDoc); this.#updateValueFromState(); if (!opts.skipRender) { const editor = this.editorRef()?.nativeElement; if (editor) { const scrollTop = opts.preserveScroll ? editor.scrollTop : undefined; const scrollLeft = opts.preserveScroll ? editor.scrollLeft : undefined; this.#renderHTMLToDOM(jsonToHTML(newDoc, this.#registry)); if (scrollTop !== undefined) editor.scrollTop = scrollTop; if (scrollLeft !== undefined) editor.scrollLeft = scrollLeft; } } }; if (opts.suppressFeedback) { this.#runWithoutFeedback(commit); } else { commit(); } } /** Serialize an AST to the current format and push to the value signal. Centralises the format-branching logic used by #updateValueFromState, setHTML, setMarkdown, and setJSON. / #serializeASTToValue(ast: ShipEditorDocument): ShipEditorValue { const currentFormat = this.format(); if (currentFormat === 'json') { this.value.set(ast); this.#lastValueWrittenFromDOM = ast; this.onChange(ast); this.rawCodeValue.set(JSON.stringify(ast, null, 2)); return ast; } else { const html = jsonToHTML(ast, this.#registry); if (currentFormat === 'html') { this.value.set(html); this.#lastValueWrittenFromDOM = html; this.onChange(html); return html; } else if (currentFormat === 'markdown') { const md = htmlToMarkdown(html, this.#document, this.#registry); this.value.set(md); this.#lastValueWrittenFromDOM = md; this.onChange(md); this.rawCodeValue.set(md); return md; } } return null; } #linkModalFocusEffect = effect(() => { if (this.showLinkModal()) { const linkInput = this.linkInput(); if (linkInput) { linkInput.nativeElement.focus(); } } }); #imageModalFocusEffect = effect(() => { if (this.showImageModal()) { // Defer focus to next render so Angular has rendered the @if block afterNextRender( () => { const uploadBtn = this.uploadBtn(); const imageInput = this.imageInput(); if (this.imageUploadEnabled()) { if (uploadBtn) { uploadBtn.nativeElement.focus(); } } else { if (imageInput) { imageInput.nativeElement.focus(); } } }, { injector: this.#injector } ); } }); #valueSyncEffect = effect(() => { const val = this.value(); const editor = this.editorRef()?.nativeElement; if (editor && editor !== this.#lastEditorElement) { this.#lastEditorElement = editor; this.#lastValueWrittenFromDOM = undefined; } if (val === this.#lastValueWrittenFromDOM) return; this.#syncModelToDOM(val); }); #formatSwitchEffect = effect(() => { const fmt = this.format(); const prev = this.#lastFormat; this.#lastFormat = fmt; if (prev !== null && prev !== fmt) { const val = this.value(); let html = ''; if (prev === 'html' && typeof val === 'string') { html = val; } else if (prev === 'markdown' && typeof val === 'string') { html = markdownToHTML(val, this.#registry); } else if (prev === 'json' && Array.isArray(val)) { html = jsonToHTML(val, this.#registry); } let newValue: ShipEditorValue = ''; if (fmt === 'html') { newValue = html; } else if (fmt === 'markdown') { newValue = htmlToMarkdown(html, this.#document, this.#registry); } else if (fmt === 'json') { newValue = htmlToJSON(html, this.#document, this.#registry); } this.#runWithoutFeedback(() => { this.value.set(newValue); this.#lastValueWrittenFromDOM = newValue; this.onChange(newValue); if (fmt === 'markdown' && typeof newValue === 'string') { this.rawCodeValue.set(newValue); } else if (fmt === 'json' && Array.isArray(newValue)) { this.rawCodeValue.set(JSON.stringify(newValue, null, 2)); } else { this.rawCodeValue.set(html); } const ast = htmlToJSON(html, this.#document, this.#registry); this.#saveAndRestoreSelection(() => { this.#setDocumentState(ast); }); }); } }); // Word/char counts are updated synchronously in #setDocumentState() (for programmatic // changes) and in onDOMInput() (for instant typing feedback). No async effect needed. #toolbarVisibilityEffect = effect(() => { this.showFormats(); this.showBlocks(); this.showLists(); this.showAlignments(); this.showInsertions(); this.showHistory(); this.toolbar(); this.readonly(); this.#initializeToolbarTabindexes(); }); constructor() { // Register mark extensions once (these aren't configurable via input yet) this.#registry.registerDefaultMarks(); // Register block extensions from the input — defaults to defaultBlockExtensions effect(() => { const exts = this.extensions(); this.#registry.clearBlocks(); exts.forEach((ext) => this.#registry.registerBlock(ext)); }); } ngAfterViewInit() { this.#syncModelToDOM(this.value()); this.#registry.getAllBlocks().forEach((ext) => ext.onInit?.(this)); this.#registry.getAllMarks().forEach((ext) => ext.onInit?.(this)); } ngOnDestroy() { this.#savedRange = null; if (this.#valueUpdateTimeout) { clearTimeout(this.#valueUpdateTimeout); } this.#registry.getAllBlocks().forEach((ext) => ext.onDestroy?.(this)); this.#registry.getAllMarks().forEach((ext) => ext.onDestroy?.(this)); } writeValue(obj: ShipEditorValue): void { this.#runWithoutFeedback(() => { this.value.set(obj); this.#syncModelToDOM(obj); }); } registerOnChange(fn: (value: ShipEditorValue) => void): void { this.onChange = fn; } registerOnTouched(fn: () => void): void { this.onTouched = fn; } setDisabledState(_isDisabled: boolean): void { // CVA disabled state not supported — use the [readonly] signal input instead } #stripCompiledMarkup(html: string): string { if (!html) return ''; let clean = html .replace(/<!--[\\s\\S]*?-->/g, '') .replace(/\\s*_ngcontent-[a-z0-9-]+(?:=\"[^\"]*\"|='[^']*'|=[^\\s>]+)?/gi, '') .replace(/\\s*_nghost-[a-z0-9-]+(?:=\"[^\"]*\"|='[^']*'|=[^\\s>]+)?/gi, '') .replace(/\\s*ng-[a-z0-9-]+(?:=\"[^\"]*\"|='[^']*'|=[^\\s>]+)?/gi, '') .replace(/\\s*data-block-index=\"[0-9]+\"/gi, '') .replace(/\\s*data-item-index=\"[0-9]+\"/gi, ''); clean = clean.replace(/class=\"([^\"]*)sh-editor-active-block([^\"]*)\"/gi, (match, p1, p2) => { const remaining = (p1 + p2).replace(/\\s+/g, ' ').trim(); return remaining ? `class=\"${remaining}\"` : ''; }); // Remove any trailing spaces inside tag brackets (e.g. <p > -> <p>) clean = clean.replace(/\\s+(?=>)/g, ''); return clean; } #renderHTMLToDOM(html: string) { const editor = this.editorRef()?.nativeElement; if (!editor) return; editor.innerHTML = html; const doc = this.documentState(); const children = Array.from(editor.children); children.forEach((child, idx) => { child.setAttribute('data-block-index', idx.toString()); const tag = child.tagName.toLowerCase(); if (tag === 'ul' || tag === 'ol') { const items = Array.from(child.querySelectorAll(':scope > li')); items.forEach((item, itemIdx) => { item.setAttribute('data-item-index', itemIdx.toString()); }); } // Call extension onBlockRender hook for post-render DOM enhancements const block = doc[idx]; if (block) { const ext = this.#registry.getBlock(block.type); if (ext?.onBlockRender) { ext.onBlockRender(child as HTMLElement, block, idx); } } }); } #syncModelToDOM(val: ShipEditorValue) { let ast: ShipEditorDocument = []; let html = ''; if (val === null || val === undefined || val === '') { ast = [{ type: 'paragraph', content: [] }]; html = '<p><br></p>'; } else if (Array.isArray(val)) { ast = val; html = jsonToHTML(val, this.#registry); } else if (typeof val === 'string') { if (this.format() === 'markdown') { html = markdownToHTML(val, this.#registry); } else { html = val; } ast = htmlToJSON(html, this.#document, this.#registry); } const isNewValue = val !== this.#lastValueWrittenFromDOM; if (this.format() === 'markdown' && typeof val === 'string') { this.rawCodeValue.set(val); } else if (this.format() === 'json' && Array.isArray(val)) { this.rawCodeValue.set(JSON.stringify(val, null, 2)); } else { this.rawCodeValue.set(html); } this.#lastValueWrittenFromDOM = val; this.#saveAndRestoreSelection(() => { this.#setDocumentState(ast); this.#renderHTMLToDOM(html); }); if (isNewValue) { this.#historyStack = []; this.#historyIndex = -1; } if (this.#historyStack.length === 0) { this.#saveHistory(); } this.#updateHistoryStates(); } #updateValueFromDOM() { const editor = this.editorRef()?.nativeElement; if (!editor) return; const rawHtml = editor.innerHTML; // Phase 1: Build AST (Internal State) - Fast const initialAst = htmlToJSON(rawHtml, this.#document, this.#registry); let cleanHtml = this.#stripCompiledMarkup(jsonToHTML(initialAst, this.#registry)); if (cleanHtml === '' || cleanHtml === '<br>' || cleanHtml === '<p><br></p>') { cleanHtml = ''; } const ast = htmlToJSON(cleanHtml, this.#document, this.#registry); this.#runWithoutFeedback(() => { this.#saveAndRestoreSelection(() => { this.#setDocumentState(ast); }); // Phase 2: Serialize & Emit Value - Debounced for performance if (this.#valueUpdateTimeout) { clearTimeout(this.#valueUpdateTimeout); } const format = this.format(); // Heuristic: Use longer debounce for heavy markdown serialization on large docs const isHeavy = format === 'markdown' && rawHtml.length > 5000; const emitDelay = isHeavy ? 800 : 200; this.#valueUpdateTimeout = setTimeout(() => { this.#lastValueWrittenFromDOM = this.#serializeASTToValue(ast); this.#saveHistory(); }, emitDelay); }); } onDOMInput() { // Update internal metrics (character and word tracking) instantly via local evaluations const editor = this.editorRef()?.nativeElement; if (editor) { const textContent = editor.textContent || ''; this.charCount.set(textContent.length); this.wordCount.set(textContent.trim() === '' ? 0 : textContent.trim().split(/\\s+/).length); // Run extension onBlockRender for image blocks after browser-native DOM mutations const imgExt = this.#registry.getBlock('image'); if (imgExt?.onBlockRender) { const imgs = editor.querySelectorAll('img'); imgs.forEach((img) => { const blockEl = img.closest('[data-block-index]') as HTMLElement; if (blockEl) { const idx = parseInt(blockEl.getAttribute('data-block-index') || '0', 10); imgExt.onBlockRender!(blockEl, { type: 'image' }, idx); } }); } } const selection = window.getSelection(); let saveImmediately = false; if (selection && selection.rangeCount > 0) { const range = selection.getRangeAt(0); const textNode = range.startContainer; if (textNode.nodeType === 3) { // Node.TEXT_NODE const char = textNode.textContent?.charAt(range.startOffset - 1); if (char && /[\\s.,!?;/]/.test(char)) { saveImmediately = true; } } } if (this.#typingTimeout) { clearTimeout(this.#typingTimeout); } const delay = saveImmediately ? 50 : 500; this.#typingTimeout = setTimeout(() => { this.#updateValueFromDOM(); }, delay); } onDOMBlur() { this.isFocused.set(false); this.onTouched(); // Flush any pending debounced updates immediately on blur if (this.#typingTimeout) { clearTimeout(this.#typingTimeout); this.#updateValueFromDOM(); } // We also need to ensure the Phase 2 (serialization) is flushed if (this.#valueUpdateTimeout) { clearTimeout(this.#valueUpdateTimeout); const ast = this.documentState(); this.#lastValueWrittenFromDOM = this.#serializeASTToValue(ast); } } onBeforeInput(event: InputEvent) { if (this.readonly() || this.viewMode() === 'code') return; const editor = this.editorRef()?.nativeElement; if (!editor) return; const selection = window.getSelection(); if (!selection || selection.rangeCount === 0) return; const range = selection.getRangeAt(0); const position = mapDOMPositionToLogical(editor, range.startContainer, range.startOffset); if (!position) return; const type = event.inputType; if (type === 'insertParagraph' || type === 'insertLineBreak') { event.preventDefault(); // Delegate to extension onBlockKeydown if the block type has one const currentBlock = this.documentState()[position.blockIndex]; if (currentBlock) { const ext = this.#registry.getBlock(currentBlock.type); if (ext?.onBlockKeydown) { const editorEl = this.editorRef()?.nativeElement; const blockEl = editorEl?.children[position.blockIndex] as HTMLElement; const ctx: ShipEditorBlockContext = { position, blockEl, doc: this.documentState(), }; const result = ext.onBlockKeydown(event, ctx); if (result !== false) { this.#updateStateAndCaret(result.doc, result.position); return; } } } const doc = this.documentState(); const { doc: newDoc, newPosition } = splitBlock(doc, position); this.#updateStateAndCaret(newDoc, newPosition); } else if (type === 'deleteContentBackward') { // Backspace // Intercept if caret is at the start of a block if (position.inlineIndex === 0 && position.offset === 0) { event.preventDefault(); const doc = this.documentState(); const { doc: newDoc, newPosition } = mergeBlocks(doc, position); this.#updateStateAndCaret(newDoc, newPosition); } } else if (type === 'deleteContentForward') { // Delete key — merge with the next block when caret is at the end. // Only intercept at block boundaries; let the browser handle mid-block deletes. const doc = this.documentState(); const block = doc[position.blockIndex]; if (block) { const content = (Array.isArray(block.content) ? block.content : []) as ShipEditorInlineNode[]; const lastIdx = Math.max(0, content.length - 1); const lastLen = content[lastIdx]?.text?.length || 0; const isAtEnd = position.inlineIndex >= lastIdx && position.offset >= lastLen; if (isAtEnd) { const result = mergeBlockForward(doc, position); event.preventDefault(); this.#updateStateAndCaret(result.doc, result.newPosition); } } } } #updateStateAndCaret(newDoc: ShipEditorDocument, newPosition: LogicalPosition) { this.#commitDocument(newDoc, { preserveScroll: true }); const editor = this.editorRef()?.nativeElement; if (editor) { // Synchronous caret restoration — #commitDocument uses innerHTML which // is synchronous, so the new DOM nodes are immediately available. EditorSelection.apply(editor, this.documentState(), newPosition, null, { scrollIntoView: true }); this.onSelectionChange(); } } #updateValueFromState() { this.#runWithoutFeedback(() => { this.#serializeASTToValue(this.documentState()); }); } onCodeInput(event: Event) { const textarea = event.target as HTMLTextAreaElement; this.rawCodeValue.set(textarea.value); } onCodeBlur(event: Event) { this.isFocused.set(false); const textarea = event.target as HTMLTextAreaElement; const codeVal = textarea.value; this.#runWithoutFeedback(() => { const currentFormat = this.format(); if (currentFormat === 'html') { this.value.set(codeVal); this.onChange(codeVal); } else if (currentFormat === 'markdown') { this.value.set(codeVal); this.onChange(codeVal); } else if (currentFormat === 'json') { try { const parsed = JSON.parse(codeVal); this.value.set(parsed); this.onChange(parsed); } catch { /* JSON parse error in code view — ignored */ } } }); this.onTouched(); } /** Valid commands for formatText(). Case-insensitive to match template usage.",
         "defaultValue": "false"
       },
       {
@@ -130,10 +287,16 @@
         "description": "",
         "defaultValue": "true"
       },
+      {
+        "name": "extensions",
+        "type": "ShipEditorBlockExtension[]",
+        "description": "Block extensions to use. Defaults to the built-in set. Override to customize behavior or add custom blocks. @example ```typescript import { defaultBlockExtensions, configureExtension, imageBlockExtension } from 'ship-ui/ship-editor'; myExtensions = [   ...defaultBlockExtensions.filter(e => e.type !== 'image'),   configureExtension(imageBlockExtension, { defaultMode: 'content', defaultSize: 'auto' }), ]; ```",
+        "defaultValue": "defaultBlockExtensions"
+      },
       {
         "name": "value",
         "type": "string | ShipEditorDocument | null",
-        "description": "",
+        "description": "Block extensions to use. Defaults to the built-in set. Override to customize behavior or add custom blocks. @example ```typescript import { defaultBlockExtensions, configureExtension, imageBlockExtension } from 'ship-ui/ship-editor'; myExtensions = [   ...defaultBlockExtensions.filter(e => e.type !== 'image'),   configureExtension(imageBlockExtension, { defaultMode: 'content', defaultSize: 'auto' }), ]; ``` / extensions = input<ShipEditorBlockExtension[]>(defaultBlockExtensions); #selectedImage = signal<HTMLImageElement | null>(null); imgMode = signal<'content' | 'theater' | 'float' | 'custom'>('content'); imgSize = signal<'auto' | 'small' | 'medium' | 'large'>('auto'); /** Tracks the DOM element with an extension-driven activeClassName applied. */ #activeBlockEl: HTMLElement | null = null; viewMode = signal<'design' | 'code'>('design'); isFocused = signal<boolean>(false); showLinkModal = signal<boolean>(false); showImageModal = signal<boolean>(false); rawCodeValue = signal<string>(''); showBlockMenu = signal<boolean>(false); isBold = signal<boolean>(false); isItalic = signal<boolean>(false); isUnderline = signal<boolean>(false); isStrike = signal<boolean>(false); align = signal<'left' | 'center' | 'right'>('left'); activeBlock = signal<string>('p'); canUndo = signal<boolean>(false); canRedo = signal<boolean>(false); #savedRange: Range | null = null; documentState = signal<ShipEditorDocument>([]); getBlockInlineHTML(block: any): string { return inlineToHTML((block?.content as ShipEditorInlineNode[]) || []) || '<br>'; } getCodeText(block: ShipEditorBlock): string { return ((block.content as ShipEditorInlineNode[]) || []).map((node) => node.text || '').join(''); } getImageClass(block: ShipEditorBlock): string { const mode = block.attrs?.mode || 'content'; const size = block.attrs?.size || 'auto'; if (mode === 'content' || mode === 'theater') { return `sh-editor-img-${mode}`; } return `sh-editor-img-${mode} sh-editor-img-size-${size}`; } #saveAndRestoreSelection(action: () => void) { if (!this.#isBrowser || this.viewMode() === 'code') { action(); return; } const editor = this.editorRef()?.nativeElement; const saved = editor ? EditorSelection.read(editor) : null; action(); // Synchronous caret restoration — the action uses innerHTML which is // synchronous, so the new DOM nodes are immediately available. if (saved && editor) { EditorSelection.apply(editor, this.documentState(), saved.start, saved.end); } } charCount = signal<number>(0); wordCount = signal<number>(0); onChange: (value: ShipEditorValue) => void = () => {}; onTouched: () => void = () => {}; hostClasses = shipComponentClasses('editor', { color: this.color, variant: this.variant, readonly: this.readonly, }); #isWriting = false; #lastFormat: 'json' | 'html' | 'markdown' | null = null; /** Set the document state and increment the version counter for history deduplication. */ #setDocumentState(doc: ShipEditorDocument) { this.#docVersion++; this.documentState.set(doc); // Update word/char counts from the AST. This is the single source of truth for // programmatic doc changes (transactions, undo, paste, etc.). The onDOMInput() // handler provides instant counts from editor.textContent during typing. const text = getJSONText(doc).replace(/\\u00a0/g, ' ').trim(); this.charCount.set(text.length); this.wordCount.set(text === '' ? 0 : text.split(/\\s+/).filter((w) => w.length > 0).length); } /** Run a callback while suppressing feedback loops (DOM→model→DOM cycles). */ #runWithoutFeedback(fn: () => void) { this.#isWriting = true; try { fn(); } finally { this.#isWriting = false; } } /** Unified state commit: AST → signals → serialized value → DOM. Every document mutation should go through this single path to keep state, value, and DOM in sync and avoid forgotten guards. / #commitDocument( newDoc: ShipEditorDocument, options?: { /** Wrap in #runWithoutFeedback to suppress DOM→model→DOM loops. */ suppressFeedback?: boolean; /** Set #isInternalDOMUpdate to block stale selectionchange events. */ guardSelectionChange?: boolean; /** Preserve scroll position across the DOM re-render. */ preserveScroll?: boolean; /** Skip DOM render (caller handles it or no editor ref). */ skipRender?: boolean; } ) { const opts = { suppressFeedback: false, guardSelectionChange: false, preserveScroll: false, skipRender: false, ...options, }; if (opts.guardSelectionChange) this.#isInternalDOMUpdate = true; const commit = () => { this.#setDocumentState(newDoc); this.#updateValueFromState(); if (!opts.skipRender) { const editor = this.editorRef()?.nativeElement; if (editor) { const scrollTop = opts.preserveScroll ? editor.scrollTop : undefined; const scrollLeft = opts.preserveScroll ? editor.scrollLeft : undefined; this.#renderHTMLToDOM(jsonToHTML(newDoc, this.#registry)); if (scrollTop !== undefined) editor.scrollTop = scrollTop; if (scrollLeft !== undefined) editor.scrollLeft = scrollLeft; } } }; if (opts.suppressFeedback) { this.#runWithoutFeedback(commit); } else { commit(); } } /** Serialize an AST to the current format and push to the value signal. Centralises the format-branching logic used by #updateValueFromState, setHTML, setMarkdown, and setJSON. / #serializeASTToValue(ast: ShipEditorDocument): ShipEditorValue { const currentFormat = this.format(); if (currentFormat === 'json') { this.value.set(ast); this.#lastValueWrittenFromDOM = ast; this.onChange(ast); this.rawCodeValue.set(JSON.stringify(ast, null, 2)); return ast; } else { const html = jsonToHTML(ast, this.#registry); if (currentFormat === 'html') { this.value.set(html); this.#lastValueWrittenFromDOM = html; this.onChange(html); return html; } else if (currentFormat === 'markdown') { const md = htmlToMarkdown(html, this.#document, this.#registry); this.value.set(md); this.#lastValueWrittenFromDOM = md; this.onChange(md); this.rawCodeValue.set(md); return md; } } return null; } #linkModalFocusEffect = effect(() => { if (this.showLinkModal()) { const linkInput = this.linkInput(); if (linkInput) { linkInput.nativeElement.focus(); } } }); #imageModalFocusEffect = effect(() => { if (this.showImageModal()) { // Defer focus to next render so Angular has rendered the @if block afterNextRender( () => { const uploadBtn = this.uploadBtn(); const imageInput = this.imageInput(); if (this.imageUploadEnabled()) { if (uploadBtn) { uploadBtn.nativeElement.focus(); } } else { if (imageInput) { imageInput.nativeElement.focus(); } } }, { injector: this.#injector } ); } }); #valueSyncEffect = effect(() => { const val = this.value(); const editor = this.editorRef()?.nativeElement; if (editor && editor !== this.#lastEditorElement) { this.#lastEditorElement = editor; this.#lastValueWrittenFromDOM = undefined; } if (val === this.#lastValueWrittenFromDOM) return; this.#syncModelToDOM(val); }); #formatSwitchEffect = effect(() => { const fmt = this.format(); const prev = this.#lastFormat; this.#lastFormat = fmt; if (prev !== null && prev !== fmt) { const val = this.value(); let html = ''; if (prev === 'html' && typeof val === 'string') { html = val; } else if (prev === 'markdown' && typeof val === 'string') { html = markdownToHTML(val, this.#registry); } else if (prev === 'json' && Array.isArray(val)) { html = jsonToHTML(val, this.#registry); } let newValue: ShipEditorValue = ''; if (fmt === 'html') { newValue = html; } else if (fmt === 'markdown') { newValue = htmlToMarkdown(html, this.#document, this.#registry); } else if (fmt === 'json') { newValue = htmlToJSON(html, this.#document, this.#registry); } this.#runWithoutFeedback(() => { this.value.set(newValue); this.#lastValueWrittenFromDOM = newValue; this.onChange(newValue); if (fmt === 'markdown' && typeof newValue === 'string') { this.rawCodeValue.set(newValue); } else if (fmt === 'json' && Array.isArray(newValue)) { this.rawCodeValue.set(JSON.stringify(newValue, null, 2)); } else { this.rawCodeValue.set(html); } const ast = htmlToJSON(html, this.#document, this.#registry); this.#saveAndRestoreSelection(() => { this.#setDocumentState(ast); }); }); } }); // Word/char counts are updated synchronously in #setDocumentState() (for programmatic // changes) and in onDOMInput() (for instant typing feedback). No async effect needed. #toolbarVisibilityEffect = effect(() => { this.showFormats(); this.showBlocks(); this.showLists(); this.showAlignments(); this.showInsertions(); this.showHistory(); this.toolbar(); this.readonly(); this.#initializeToolbarTabindexes(); }); constructor() { // Register mark extensions once (these aren't configurable via input yet) this.#registry.registerDefaultMarks(); // Register block extensions from the input — defaults to defaultBlockExtensions effect(() => { const exts = this.extensions(); this.#registry.clearBlocks(); exts.forEach((ext) => this.#registry.registerBlock(ext)); }); } ngAfterViewInit() { this.#syncModelToDOM(this.value()); this.#registry.getAllBlocks().forEach((ext) => ext.onInit?.(this)); this.#registry.getAllMarks().forEach((ext) => ext.onInit?.(this)); } ngOnDestroy() { this.#savedRange = null; if (this.#valueUpdateTimeout) { clearTimeout(this.#valueUpdateTimeout); } this.#registry.getAllBlocks().forEach((ext) => ext.onDestroy?.(this)); this.#registry.getAllMarks().forEach((ext) => ext.onDestroy?.(this)); } writeValue(obj: ShipEditorValue): void { this.#runWithoutFeedback(() => { this.value.set(obj); this.#syncModelToDOM(obj); }); } registerOnChange(fn: (value: ShipEditorValue) => void): void { this.onChange = fn; } registerOnTouched(fn: () => void): void { this.onTouched = fn; } setDisabledState(_isDisabled: boolean): void { // CVA disabled state not supported — use the [readonly] signal input instead } #stripCompiledMarkup(html: string): string { if (!html) return ''; let clean = html .replace(/<!--[\\s\\S]*?-->/g, '') .replace(/\\s*_ngcontent-[a-z0-9-]+(?:=\"[^\"]*\"|='[^']*'|=[^\\s>]+)?/gi, '') .replace(/\\s*_nghost-[a-z0-9-]+(?:=\"[^\"]*\"|='[^']*'|=[^\\s>]+)?/gi, '') .replace(/\\s*ng-[a-z0-9-]+(?:=\"[^\"]*\"|='[^']*'|=[^\\s>]+)?/gi, '') .replace(/\\s*data-block-index=\"[0-9]+\"/gi, '') .replace(/\\s*data-item-index=\"[0-9]+\"/gi, ''); clean = clean.replace(/class=\"([^\"]*)sh-editor-active-block([^\"]*)\"/gi, (match, p1, p2) => { const remaining = (p1 + p2).replace(/\\s+/g, ' ').trim(); return remaining ? `class=\"${remaining}\"` : ''; }); // Remove any trailing spaces inside tag brackets (e.g. <p > -> <p>) clean = clean.replace(/\\s+(?=>)/g, ''); return clean; } #renderHTMLToDOM(html: string) { const editor = this.editorRef()?.nativeElement; if (!editor) return; editor.innerHTML = html; const doc = this.documentState(); const children = Array.from(editor.children); children.forEach((child, idx) => { child.setAttribute('data-block-index', idx.toString()); const tag = child.tagName.toLowerCase(); if (tag === 'ul' || tag === 'ol') { const items = Array.from(child.querySelectorAll(':scope > li')); items.forEach((item, itemIdx) => { item.setAttribute('data-item-index', itemIdx.toString()); }); } // Call extension onBlockRender hook for post-render DOM enhancements const block = doc[idx]; if (block) { const ext = this.#registry.getBlock(block.type); if (ext?.onBlockRender) { ext.onBlockRender(child as HTMLElement, block, idx); } } }); } #syncModelToDOM(val: ShipEditorValue) { let ast: ShipEditorDocument = []; let html = ''; if (val === null || val === undefined || val === '') { ast = [{ type: 'paragraph', content: [] }]; html = '<p><br></p>'; } else if (Array.isArray(val)) { ast = val; html = jsonToHTML(val, this.#registry); } else if (typeof val === 'string') { if (this.format() === 'markdown') { html = markdownToHTML(val, this.#registry); } else { html = val; } ast = htmlToJSON(html, this.#document, this.#registry); } const isNewValue = val !== this.#lastValueWrittenFromDOM; if (this.format() === 'markdown' && typeof val === 'string') { this.rawCodeValue.set(val); } else if (this.format() === 'json' && Array.isArray(val)) { this.rawCodeValue.set(JSON.stringify(val, null, 2)); } else { this.rawCodeValue.set(html); } this.#lastValueWrittenFromDOM = val; this.#saveAndRestoreSelection(() => { this.#setDocumentState(ast); this.#renderHTMLToDOM(html); }); if (isNewValue) { this.#historyStack = []; this.#historyIndex = -1; } if (this.#historyStack.length === 0) { this.#saveHistory(); } this.#updateHistoryStates(); } #updateValueFromDOM() { const editor = this.editorRef()?.nativeElement; if (!editor) return; const rawHtml = editor.innerHTML; // Phase 1: Build AST (Internal State) - Fast const initialAst = htmlToJSON(rawHtml, this.#document, this.#registry); let cleanHtml = this.#stripCompiledMarkup(jsonToHTML(initialAst, this.#registry)); if (cleanHtml === '' || cleanHtml === '<br>' || cleanHtml === '<p><br></p>') { cleanHtml = ''; } const ast = htmlToJSON(cleanHtml, this.#document, this.#registry); this.#runWithoutFeedback(() => { this.#saveAndRestoreSelection(() => { this.#setDocumentState(ast); }); // Phase 2: Serialize & Emit Value - Debounced for performance if (this.#valueUpdateTimeout) { clearTimeout(this.#valueUpdateTimeout); } const format = this.format(); // Heuristic: Use longer debounce for heavy markdown serialization on large docs const isHeavy = format === 'markdown' && rawHtml.length > 5000; const emitDelay = isHeavy ? 800 : 200; this.#valueUpdateTimeout = setTimeout(() => { this.#lastValueWrittenFromDOM = this.#serializeASTToValue(ast); this.#saveHistory(); }, emitDelay); }); } onDOMInput() { // Update internal metrics (character and word tracking) instantly via local evaluations const editor = this.editorRef()?.nativeElement; if (editor) { const textContent = editor.textContent || ''; this.charCount.set(textContent.length); this.wordCount.set(textContent.trim() === '' ? 0 : textContent.trim().split(/\\s+/).length); // Run extension onBlockRender for image blocks after browser-native DOM mutations const imgExt = this.#registry.getBlock('image'); if (imgExt?.onBlockRender) { const imgs = editor.querySelectorAll('img'); imgs.forEach((img) => { const blockEl = img.closest('[data-block-index]') as HTMLElement; if (blockEl) { const idx = parseInt(blockEl.getAttribute('data-block-index') || '0', 10); imgExt.onBlockRender!(blockEl, { type: 'image' }, idx); } }); } } const selection = window.getSelection(); let saveImmediately = false; if (selection && selection.rangeCount > 0) { const range = selection.getRangeAt(0); const textNode = range.startContainer; if (textNode.nodeType === 3) { // Node.TEXT_NODE const char = textNode.textContent?.charAt(range.startOffset - 1); if (char && /[\\s.,!?;/]/.test(char)) { saveImmediately = true; } } } if (this.#typingTimeout) { clearTimeout(this.#typingTimeout); } const delay = saveImmediately ? 50 : 500; this.#typingTimeout = setTimeout(() => { this.#updateValueFromDOM(); }, delay); } onDOMBlur() { this.isFocused.set(false); this.onTouched(); // Flush any pending debounced updates immediately on blur if (this.#typingTimeout) { clearTimeout(this.#typingTimeout); this.#updateValueFromDOM(); } // We also need to ensure the Phase 2 (serialization) is flushed if (this.#valueUpdateTimeout) { clearTimeout(this.#valueUpdateTimeout); const ast = this.documentState(); this.#lastValueWrittenFromDOM = this.#serializeASTToValue(ast); } } onBeforeInput(event: InputEvent) { if (this.readonly() || this.viewMode() === 'code') return; const editor = this.editorRef()?.nativeElement; if (!editor) return; const selection = window.getSelection(); if (!selection || selection.rangeCount === 0) return; const range = selection.getRangeAt(0); const position = mapDOMPositionToLogical(editor, range.startContainer, range.startOffset); if (!position) return; const type = event.inputType; if (type === 'insertParagraph' || type === 'insertLineBreak') { event.preventDefault(); // Delegate to extension onBlockKeydown if the block type has one const currentBlock = this.documentState()[position.blockIndex]; if (currentBlock) { const ext = this.#registry.getBlock(currentBlock.type); if (ext?.onBlockKeydown) { const editorEl = this.editorRef()?.nativeElement; const blockEl = editorEl?.children[position.blockIndex] as HTMLElement; const ctx: ShipEditorBlockContext = { position, blockEl, doc: this.documentState(), }; const result = ext.onBlockKeydown(event, ctx); if (result !== false) { this.#updateStateAndCaret(result.doc, result.position); return; } } } const doc = this.documentState(); const { doc: newDoc, newPosition } = splitBlock(doc, position); this.#updateStateAndCaret(newDoc, newPosition); } else if (type === 'deleteContentBackward') { // Backspace // Intercept if caret is at the start of a block if (position.inlineIndex === 0 && position.offset === 0) { event.preventDefault(); const doc = this.documentState(); const { doc: newDoc, newPosition } = mergeBlocks(doc, position); this.#updateStateAndCaret(newDoc, newPosition); } } else if (type === 'deleteContentForward') { // Delete key — merge with the next block when caret is at the end. // Only intercept at block boundaries; let the browser handle mid-block deletes. const doc = this.documentState(); const block = doc[position.blockIndex]; if (block) { const content = (Array.isArray(block.content) ? block.content : []) as ShipEditorInlineNode[]; const lastIdx = Math.max(0, content.length - 1); const lastLen = content[lastIdx]?.text?.length || 0; const isAtEnd = position.inlineIndex >= lastIdx && position.offset >= lastLen; if (isAtEnd) { const result = mergeBlockForward(doc, position); event.preventDefault(); this.#updateStateAndCaret(result.doc, result.newPosition); } } } } #updateStateAndCaret(newDoc: ShipEditorDocument, newPosition: LogicalPosition) { this.#commitDocument(newDoc, { preserveScroll: true }); const editor = this.editorRef()?.nativeElement; if (editor) { // Synchronous caret restoration — #commitDocument uses innerHTML which // is synchronous, so the new DOM nodes are immediately available. EditorSelection.apply(editor, this.documentState(), newPosition, null, { scrollIntoView: true }); this.onSelectionChange(); } } #updateValueFromState() { this.#runWithoutFeedback(() => { this.#serializeASTToValue(this.documentState()); }); } onCodeInput(event: Event) { const textarea = event.target as HTMLTextAreaElement; this.rawCodeValue.set(textarea.value); } onCodeBlur(event: Event) { this.isFocused.set(false); const textarea = event.target as HTMLTextAreaElement; const codeVal = textarea.value; this.#runWithoutFeedback(() => { const currentFormat = this.format(); if (currentFormat === 'html') { this.value.set(codeVal); this.onChange(codeVal); } else if (currentFormat === 'markdown') { this.value.set(codeVal); this.onChange(codeVal); } else if (currentFormat === 'json') { try { const parsed = JSON.parse(codeVal); this.value.set(parsed); this.onChange(parsed); } catch { /* JSON parse error in code view — ignored */ } } }); this.onTouched(); } /** Valid commands for formatText(). Case-insensitive to match template usage.",
         "defaultValue": "''"
       }
     ],
@@ -146,20 +309,50 @@
     ],
     "methods": [
       {
-        "name": "execCommand",
-        "parameters": "commandId: string, showUI?: boolean, value?: string",
-        "returnType": "boolean;\n  queryCommandState(commandId: string): boolean;\n  queryCommandEnabled(commandId: string): boolean;\n}\n\n\nconst SHIP_EDITOR_VALUE_ACCESSOR: Provider =",
+        "name": "getCodeText",
+        "parameters": "block: ShipEditorBlock",
+        "returnType": "string",
+        "description": ""
+      },
+      {
+        "name": "return",
+        "parameters": "(block.content as ShipEditorInlineNode[]) || []).map((node) => node.text || '').join('');\n  }\n\n  getImageClass(block: ShipEditorBlock",
+        "returnType": "string",
+        "description": ""
+      },
+      {
+        "name": "action",
+        "parameters": ");\n      return;\n    }\n\n    const editor = this.editorRef()?.nativeElement;\n    const saved = editor ? EditorSelection.read(editor",
+        "returnType": "null;\n\n    action();\n\n    // Synchronous caret restoration — the action uses innerHTML which is\n    // synchronous, so the new DOM nodes are immediately available.\n    if (saved && editor)",
+        "description": ""
+      },
+      {
+        "name": "fn",
+        "parameters": ");\n    } finally {\n      this.#isWriting = false;\n    }\n  }\n\n  /**\n   * Unified state commit: AST → signals → serialized value → DOM.\n   * Every document mutation should go through this single path to keep\n   * state, value, and DOM in sync and avoid forgotten guards.\n   */\n  #commitDocument(\n    newDoc: ShipEditorDocument,\n    options?: {\n      /** Wrap in #runWithoutFeedback to suppress DOM→model→DOM loops. */\n      suppressFeedback?: boolean;\n      /** Set #isInternalDOMUpdate to block stale selectionchange events. */\n      guardSelectionChange?: boolean;\n      /** Preserve scroll position across the DOM re-render. */\n      preserveScroll?: boolean;\n      /** Skip DOM render (caller handles it or no editor ref). */\n      skipRender?: boolean;\n    }",
+        "returnType": "any",
+        "description": "Block extensions to use. Defaults to the built-in set. Override to customize behavior or add custom blocks. @example ```typescript import { defaultBlockExtensions, configureExtension, imageBlockExtension } from 'ship-ui/ship-editor'; myExtensions = [   ...defaultBlockExtensions.filter(e => e.type !== 'image'),   configureExtension(imageBlockExtension, { defaultMode: 'content', defaultSize: 'auto' }), ]; ``` / extensions = input<ShipEditorBlockExtension[]>(defaultBlockExtensions); #selectedImage = signal<HTMLImageElement | null>(null); imgMode = signal<'content' | 'theater' | 'float' | 'custom'>('content'); imgSize = signal<'auto' | 'small' | 'medium' | 'large'>('auto'); /** Tracks the DOM element with an extension-driven activeClassName applied. */ #activeBlockEl: HTMLElement | null = null; viewMode = signal<'design' | 'code'>('design'); isFocused = signal<boolean>(false); showLinkModal = signal<boolean>(false); showImageModal = signal<boolean>(false); rawCodeValue = signal<string>(''); showBlockMenu = signal<boolean>(false); isBold = signal<boolean>(false); isItalic = signal<boolean>(false); isUnderline = signal<boolean>(false); isStrike = signal<boolean>(false); align = signal<'left' | 'center' | 'right'>('left'); activeBlock = signal<string>('p'); canUndo = signal<boolean>(false); canRedo = signal<boolean>(false); #savedRange: Range | null = null; documentState = signal<ShipEditorDocument>([]); getBlockInlineHTML(block: any): string { return inlineToHTML((block?.content as ShipEditorInlineNode[]) || []) || '<br>'; } getCodeText(block: ShipEditorBlock): string { return ((block.content as ShipEditorInlineNode[]) || []).map((node) => node.text || '').join(''); } getImageClass(block: ShipEditorBlock): string { const mode = block.attrs?.mode || 'content'; const size = block.attrs?.size || 'auto'; if (mode === 'content' || mode === 'theater') { return `sh-editor-img-${mode}`; } return `sh-editor-img-${mode} sh-editor-img-size-${size}`; } #saveAndRestoreSelection(action: () => void) { if (!this.#isBrowser || this.viewMode() === 'code') { action(); return; } const editor = this.editorRef()?.nativeElement; const saved = editor ? EditorSelection.read(editor) : null; action(); // Synchronous caret restoration — the action uses innerHTML which is // synchronous, so the new DOM nodes are immediately available. if (saved && editor) { EditorSelection.apply(editor, this.documentState(), saved.start, saved.end); } } charCount = signal<number>(0); wordCount = signal<number>(0); onChange: (value: ShipEditorValue) => void = () => {}; onTouched: () => void = () => {}; hostClasses = shipComponentClasses('editor', { color: this.color, variant: this.variant, readonly: this.readonly, }); #isWriting = false; #lastFormat: 'json' | 'html' | 'markdown' | null = null; /** Set the document state and increment the version counter for history deduplication. */ #setDocumentState(doc: ShipEditorDocument) { this.#docVersion++; this.documentState.set(doc); // Update word/char counts from the AST. This is the single source of truth for // programmatic doc changes (transactions, undo, paste, etc.). The onDOMInput() // handler provides instant counts from editor.textContent during typing. const text = getJSONText(doc).replace(/\\u00a0/g, ' ').trim(); this.charCount.set(text.length); this.wordCount.set(text === '' ? 0 : text.split(/\\s+/).filter((w) => w.length > 0).length); } /** Run a callback while suppressing feedback loops (DOM→model→DOM cycles)."
+      },
+      {
+        "name": "commit",
+        "parameters": ");\n    }\n  }\n\n  /**\n   * Serialize an AST to the current format and push to the value signal.\n   * Centralises the format-branching logic used by #updateValueFromState,\n   * setHTML, setMarkdown, and setJSON.\n   */\n  #serializeASTToValue(ast: ShipEditorDocument",
+        "returnType": "ShipEditorValue",
+        "description": "Block extensions to use. Defaults to the built-in set. Override to customize behavior or add custom blocks. @example ```typescript import { defaultBlockExtensions, configureExtension, imageBlockExtension } from 'ship-ui/ship-editor'; myExtensions = [   ...defaultBlockExtensions.filter(e => e.type !== 'image'),   configureExtension(imageBlockExtension, { defaultMode: 'content', defaultSize: 'auto' }), ]; ``` / extensions = input<ShipEditorBlockExtension[]>(defaultBlockExtensions); #selectedImage = signal<HTMLImageElement | null>(null); imgMode = signal<'content' | 'theater' | 'float' | 'custom'>('content'); imgSize = signal<'auto' | 'small' | 'medium' | 'large'>('auto'); /** Tracks the DOM element with an extension-driven activeClassName applied. */ #activeBlockEl: HTMLElement | null = null; viewMode = signal<'design' | 'code'>('design'); isFocused = signal<boolean>(false); showLinkModal = signal<boolean>(false); showImageModal = signal<boolean>(false); rawCodeValue = signal<string>(''); showBlockMenu = signal<boolean>(false); isBold = signal<boolean>(false); isItalic = signal<boolean>(false); isUnderline = signal<boolean>(false); isStrike = signal<boolean>(false); align = signal<'left' | 'center' | 'right'>('left'); activeBlock = signal<string>('p'); canUndo = signal<boolean>(false); canRedo = signal<boolean>(false); #savedRange: Range | null = null; documentState = signal<ShipEditorDocument>([]); getBlockInlineHTML(block: any): string { return inlineToHTML((block?.content as ShipEditorInlineNode[]) || []) || '<br>'; } getCodeText(block: ShipEditorBlock): string { return ((block.content as ShipEditorInlineNode[]) || []).map((node) => node.text || '').join(''); } getImageClass(block: ShipEditorBlock): string { const mode = block.attrs?.mode || 'content'; const size = block.attrs?.size || 'auto'; if (mode === 'content' || mode === 'theater') { return `sh-editor-img-${mode}`; } return `sh-editor-img-${mode} sh-editor-img-size-${size}`; } #saveAndRestoreSelection(action: () => void) { if (!this.#isBrowser || this.viewMode() === 'code') { action(); return; } const editor = this.editorRef()?.nativeElement; const saved = editor ? EditorSelection.read(editor) : null; action(); // Synchronous caret restoration — the action uses innerHTML which is // synchronous, so the new DOM nodes are immediately available. if (saved && editor) { EditorSelection.apply(editor, this.documentState(), saved.start, saved.end); } } charCount = signal<number>(0); wordCount = signal<number>(0); onChange: (value: ShipEditorValue) => void = () => {}; onTouched: () => void = () => {}; hostClasses = shipComponentClasses('editor', { color: this.color, variant: this.variant, readonly: this.readonly, }); #isWriting = false; #lastFormat: 'json' | 'html' | 'markdown' | null = null; /** Set the document state and increment the version counter for history deduplication. */ #setDocumentState(doc: ShipEditorDocument) { this.#docVersion++; this.documentState.set(doc); // Update word/char counts from the AST. This is the single source of truth for // programmatic doc changes (transactions, undo, paste, etc.). The onDOMInput() // handler provides instant counts from editor.textContent during typing. const text = getJSONText(doc).replace(/\\u00a0/g, ' ').trim(); this.charCount.set(text.length); this.wordCount.set(text === '' ? 0 : text.split(/\\s+/).filter((w) => w.length > 0).length); } /** Run a callback while suppressing feedback loops (DOM→model→DOM cycles). */ #runWithoutFeedback(fn: () => void) { this.#isWriting = true; try { fn(); } finally { this.#isWriting = false; } } /** Unified state commit: AST → signals → serialized value → DOM. Every document mutation should go through this single path to keep state, value, and DOM in sync and avoid forgotten guards."
+      },
+      {
+        "name": "afterNextRender",
+        "parameters": "() => {\n        if (nextMode === 'design'",
+        "returnType": "any",
         "description": ""
       },
       {
         "name": "effect",
-        "parameters": "() => {\n      this.showFormats();\n      this.showBlocks();\n      this.showLists();\n      this.showAlignments();\n      this.showInsertions();\n      this.showHistory();\n      this.toolbar();\n      this.readonly();\n      this.#initializeToolbarTabindexes();\n    });\n  }\n\n  ngOnInit(",
+        "parameters": "() => {\n      const exts = this.extensions();\n      this.#registry.clearBlocks();\n      exts.forEach((ext) => this.#registry.registerBlock(ext));\n    });\n  }\n\n  ngAfterViewInit(",
         "returnType": "any",
         "description": ""
       },
       {
         "name": "clearTimeout",
-        "parameters": "this.#typingTimeout);\n    }\n\n    if (saveImmediately",
+        "parameters": "this.#typingTimeout);\n      this.#typingTimeout = undefined;\n      this.#updateValueFromDOM();\n      this.#saveHistory();\n    }\n\n    this.#restoreSelection();\n\n    const selection = window.getSelection();\n    if (selection && selection.rangeCount > 0",
         "returnType": "any",
         "description": ""
       },
@@ -177,22 +370,10 @@
       },
       {
         "name": "setDisabledState",
-        "parameters": "isDisabled: boolean",
+        "parameters": "_isDisabled: boolean",
         "returnType": "void",
         "description": ""
       },
-      {
-        "name": "onDOMInput",
-        "parameters": "",
-        "returnType": "any",
-        "description": ""
-      },
-      {
-        "name": "onDOMBlur",
-        "parameters": "",
-        "returnType": "any",
-        "description": ""
-      },
       {
         "name": "onCodeInput",
         "parameters": "event: Event",
@@ -212,20 +393,8 @@
         "description": ""
       },
       {
-        "name": "applyInlineStyle",
-        "parameters": "tag: string",
-        "returnType": "any",
-        "description": ""
-      },
-      {
-        "name": "while",
-        "parameters": "node",
-        "returnType": "any",
-        "description": ""
-      },
-      {
-        "name": "toggleLink",
-        "parameters": "url: string",
+        "name": "handler",
+        "parameters": "this, value);\n    }\n  }\n\n  runTransaction(\n    action: (\n      doc: ShipEditorDocument,\n      selection: { start: LogicalPosition; end: LogicalPosition }\n    ) =>\n      | {\n          doc?: ShipEditorDocument;\n          selectionShift?: {\n            start: { blockIndex: number; listItemIndex?: number };\n            end: { blockIndex: number; listItemIndex?: number };\n          };\n        }\n      | ShipEditorDocument\n      | void\n      | null",
         "returnType": "any",
         "description": ""
       },
@@ -235,18 +404,6 @@
         "returnType": "any",
         "description": ""
       },
-      {
-        "name": "toggleList",
-        "parameters": "listType: 'ul' | 'ol'",
-        "returnType": "any",
-        "description": ""
-      },
-      {
-        "name": "insertHorizontalRule",
-        "parameters": "",
-        "returnType": "any",
-        "description": ""
-      },
       {
         "name": "setAlign",
         "parameters": "direction: 'left' | 'center' | 'right'",
@@ -278,26 +435,20 @@
         "description": ""
       },
       {
-        "name": "openLinkModal",
-        "parameters": "",
-        "returnType": "any",
-        "description": ""
-      },
-      {
-        "name": "applyLink",
-        "parameters": "url: string",
+        "name": "while",
+        "parameters": "node && node !== editorEl",
         "returnType": "any",
         "description": ""
       },
       {
-        "name": "openImageModal",
+        "name": "openLinkModal",
         "parameters": "",
         "returnType": "any",
         "description": ""
       },
       {
-        "name": "applyImage",
-        "parameters": "url: string",
+        "name": "updater",
+        "parameters": "block);\n\n      this.#saveHistory();\n      this.#commitDocument(newDoc, { guardSelectionChange: true });\n\n      // Synchronous — #commitDocument uses innerHTML so the new DOM is ready.\n      const newImg = this.editorRef()?.nativeElement.querySelector(\n        `img[data-block-index=\"${blockIndex}\"]`\n      ) as HTMLImageElement;\n      if (newImg",
         "returnType": "any",
         "description": ""
       },
@@ -350,41 +501,29 @@
         "description": ""
       },
       {
-        "name": "onComponentScroll",
-        "parameters": "event: Event",
-        "returnType": "any",
-        "description": ""
-      },
-      {
-        "name": "onWindowResize",
-        "parameters": "",
+        "name": "setImageSize",
+        "parameters": "size: 'auto' | 'small' | 'medium' | 'large'",
         "returnType": "any",
         "description": ""
       },
       {
-        "name": "updateImgToolbarPosition",
-        "parameters": "",
+        "name": "onDrop",
+        "parameters": "event: DragEvent",
         "returnType": "any",
         "description": ""
       },
       {
-        "name": "onFileSelected",
-        "parameters": "event: Event",
+        "name": "onMouseDown",
+        "parameters": "event: MouseEvent",
         "returnType": "any",
         "description": ""
       },
       {
-        "name": "onDrop",
+        "name": "onDragEnd",
         "parameters": "event: DragEvent",
         "returnType": "any",
         "description": ""
       },
-      {
-        "name": "onPaste",
-        "parameters": "event: ClipboardEvent",
-        "returnType": "any",
-        "description": ""
-      },
       {
         "name": "insertImage",
         "parameters": "url: string",
@@ -428,15 +567,21 @@
         "description": ""
       },
       {
-        "name": "clear",
-        "parameters": "",
+        "name": "indent",
+        "parameters": "pos: LogicalPosition",
         "returnType": "any",
         "description": ""
       },
       {
-        "name": "traverse",
-        "parameters": "child);\n    }\n\n    return md;\n  }\n\n  // Markdown => HTML Converter\n  #markdownToHTML(markdown: string",
-        "returnType": "string",
+        "name": "outdent",
+        "parameters": "pos: LogicalPosition",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "clear",
+        "parameters": "",
+        "returnType": "any",
         "description": ""
       }
     ],
@@ -492,13 +637,17 @@
       {
         "name": "--editor-shadow-focus",
         "defaultValue": "0 0 0 3px var(--primary-3)"
+      },
+      {
+        "name": "--editor-shape",
+        "defaultValue": "var(--shape-3)"
       }
     ],
     "examples": [
       {
         "name": "sandbox-editor",
-        "html": "<div class=\"sandbox-container\">\n  <div class=\"sandbox-sidebar\">\n    <sh-card class=\"type-b control-card\">\n      <h3>Options</h3>\n\n      <div class=\"control-group\">\n        <label class=\"control-label\">Storage Format</label>\n        <sh-button-group size=\"small\" [value]=\"selectedFormat()\" (valueChange)=\"onFormatChange($event)\">\n          <button value=\"html\">HTML</button>\n          <button value=\"markdown\">Markdown</button>\n          <button value=\"json\">JSON</button>\n        </sh-button-group>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"readonly-toggle\" class=\"control-label\">Read-Only</label>\n        <sh-toggle id=\"readonly-toggle\" [(checked)]=\"isReadonly\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"toolbar-toggle\" class=\"control-label\">Show Toolbar</label>\n        <sh-toggle id=\"toolbar-toggle\" [(checked)]=\"showToolbar\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"image-upload-toggle\" class=\"control-label\">Image Upload</label>\n        <sh-toggle id=\"image-upload-toggle\" [(checked)]=\"imageUploadEnabled\"></sh-toggle>\n      </div>\n\n      @if (showToolbar()) {\n        <div class=\"control-group-section-title\">Toolbar Groups</div>\n\n        <div class=\"control-group inline\">\n          <label for=\"formats-toggle\" class=\"control-label\">Formats</label>\n          <sh-toggle id=\"formats-toggle\" [(checked)]=\"showFormats\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"blocks-toggle\" class=\"control-label\">Blocks/Headings</label>\n          <sh-toggle id=\"blocks-toggle\" [(checked)]=\"showBlocks\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"lists-toggle\" class=\"control-label\">Lists</label>\n          <sh-toggle id=\"lists-toggle\" [(checked)]=\"showLists\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"align-toggle\" class=\"control-label\">Alignments</label>\n          <sh-toggle id=\"align-toggle\" [(checked)]=\"showAlignments\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"insert-toggle\" class=\"control-label\">Insertions</label>\n          <sh-toggle id=\"insert-toggle\" [(checked)]=\"showInsertions\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"history-toggle\" class=\"control-label\">History/Code</label>\n          <sh-toggle id=\"history-toggle\" [(checked)]=\"showHistory\"></sh-toggle>\n        </div>\n      }\n    </sh-card>\n  </div>\n\n  <div class=\"sandbox-editor-wrapper\">\n    <sh-editor\n      [(value)]=\"editorValue\"\n      [format]=\"selectedFormat()\"\n      [readonly]=\"isReadonly()\"\n      [toolbar]=\"showToolbar()\"\n      [showFormats]=\"showFormats()\"\n      [showBlocks]=\"showBlocks()\"\n      [showLists]=\"showLists()\"\n      [showAlignments]=\"showAlignments()\"\n      [showInsertions]=\"showInsertions()\"\n      [showHistory]=\"showHistory()\"\n      [customCommands]=\"customEditorCommands()\"\n      [imageUploadEnabled]=\"imageUploadEnabled()\"\n      placeholder=\"Start writing your premium content here...\">\n      <!-- Projected custom toolbar action -->\n      <button type=\"button\" class=\"sh-editor-btn\" (click)=\"customAction()\" shTooltip=\"Projected Action (Star)\">\n        <sh-icon>star</sh-icon>\n      </button>\n    </sh-editor>\n\n    <sh-card class=\"type-b output-card\">\n      <div class=\"output-header\">\n        <h3>Database Output</h3>\n        <button shButton variant=\"outlined\" size=\"small\" (click)=\"copyToClipboard()\">\n          <sh-icon>copy</sh-icon>\n          Copy\n        </button>\n      </div>\n      <p class=\"output-desc\">This is exactly what would be saved in your database:</p>\n      <pre class=\"serialized-preview\"><code>{{ serializedOutput() }}</code></pre>\n    </sh-card>\n  </div>\n</div>\n",
-        "ts": "import { ChangeDetectionStrategy, Component, computed, signal, viewChild } from '@angular/core';\nimport { ShipColor } from '@ship-ui/core';\nimport { ShipButton } from '@ship-ui/core/ship-button';\nimport { ShipButtonGroup } from '@ship-ui/core/ship-button-group';\nimport { ShipCard } from '@ship-ui/core/ship-card';\nimport { ShipEditor, ShipEditorCommand, ShipEditorValue } from '@ship-ui/core/ship-editor';\nimport { ShipIcon } from '@ship-ui/core/ship-icon';\nimport { ShipToggle } from '@ship-ui/core/ship-toggle';\n\n@Component({\n  selector: 'app-sandbox-editor',\n  standalone: true,\n  imports: [ShipEditor, ShipButton, ShipCard, ShipToggle, ShipIcon, ShipButtonGroup],\n  templateUrl: './sandbox-editor.html',\n  styleUrl: './sandbox-editor.scss',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class SandboxEditor {\n  // Current format selection\n  selectedFormat = signal<'html' | 'markdown' | 'json'>('html');\n\n  editor = viewChild(ShipEditor);\n\n  // Editor states\n  isReadonly = signal<boolean>(false);\n  showToolbar = signal<boolean>(true);\n  selectedColor = signal<ShipColor | null>(null);\n  imageUploadEnabled = signal<boolean>(true);\n\n  // Toolbar group configurations\n  showFormats = signal<boolean>(true);\n  showBlocks = signal<boolean>(true);\n  showLists = signal<boolean>(true);\n  showAlignments = signal<boolean>(true);\n  showInsertions = signal<boolean>(true);\n  showHistory = signal<boolean>(true);\n\n  // Custom action for projected button\n  customAction() {\n    alert('Custom Projected Button Clicked!');\n  }\n\n  customEditorCommands = signal<ShipEditorCommand[]>([\n    {\n      id: 'highlight',\n      label: 'Highlight Text',\n      icon: 'star',\n      description: 'Highlight selected text in yellow',\n      action: (editor) => {\n        editor.formatText('backColor', '#fff2b2');\n      },\n    },\n    {\n      id: 'info-callout',\n      label: 'Info Callout',\n      icon: 'terminal',\n      description: 'Insert an info callout box',\n      action: (editor) => {\n        editor.formatText(\n          'insertHTML',\n          '<div style=\"background-color: var(--primary-2); border-left: 4px solid var(--primary-9); padding: 12px 16px; margin: 12px 0; border-radius: 4px; color: var(--base-12);\"><strong>Info:</strong> Start typing callout contents here...</div>'\n        );\n      },\n    },\n  ]);\n\n  // Pre-populated initial contents for each format\n  initialHtml = `<h1>Ship WYSIWYG Editor</h1><p>Welcome! This is a <strong>config-driven</strong> rich-text editor designed to support flexible storage formats.</p><ul><li><strong>Two-way binding</strong> with <code>ControlValueAccessor</code></li><li>Instant conversion to <strong>HTML</strong>, <strong>Markdown</strong>, or <strong>JSON</strong></li><li>Sticky blur-toolbar, light/dark mode support, and word counting</li></ul><blockquote>\"A beautiful interface makes editing content a delight.\"</blockquote><hr><p>Try changing the storage format below to see the serialized output update in real time!</p>`;\n\n  // Current value model\n  editorValue = signal<ShipEditorValue>(this.initialHtml);\n\n  // Stringified preview for database presentation\n  serializedOutput = computed(() => {\n    const val = this.editorValue();\n    if (val === null || val === undefined) return '';\n    if (typeof val === 'string') return val;\n    return JSON.stringify(val, null, 2);\n  });\n\n  // Handle format swapping, converting the value appropriately\n  onFormatChange(format: string | null) {\n    if (format === 'html' || format === 'markdown' || format === 'json') {\n      this.selectedFormat.set(format);\n    }\n  }\n\n  // Copy serialized contents to clipboard\n  copyToClipboard() {\n    navigator.clipboard.writeText(this.serializedOutput());\n  }\n}\n"
+        "html": "<div class=\"sandbox-container\">\n  <div class=\"sandbox-sidebar\">\n    <sh-card class=\"type-b control-card\">\n      <h3>Options</h3>\n\n      <div class=\"control-group\">\n        <label class=\"control-label\">Storage Format</label>\n        <sh-button-group size=\"small\" [value]=\"selectedFormat()\" (valueChange)=\"onFormatChange($event)\">\n          <button value=\"html\">HTML</button>\n          <button value=\"markdown\">Markdown</button>\n          <button value=\"json\">JSON</button>\n        </sh-button-group>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"readonly-toggle\" class=\"control-label\">Read-Only</label>\n        <sh-toggle id=\"readonly-toggle\" [(checked)]=\"isReadonly\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"toolbar-toggle\" class=\"control-label\">Show Toolbar</label>\n        <sh-toggle id=\"toolbar-toggle\" [(checked)]=\"showToolbar\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"image-upload-toggle\" class=\"control-label\">Image Upload</label>\n        <sh-toggle id=\"image-upload-toggle\" [(checked)]=\"imageUploadEnabled\"></sh-toggle>\n      </div>\n\n      @if (showToolbar()) {\n        <div class=\"control-group-section-title\">Toolbar Groups</div>\n\n        <div class=\"control-group inline\">\n          <label for=\"formats-toggle\" class=\"control-label\">Formats</label>\n          <sh-toggle id=\"formats-toggle\" [(checked)]=\"showFormats\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"blocks-toggle\" class=\"control-label\">Blocks/Headings</label>\n          <sh-toggle id=\"blocks-toggle\" [(checked)]=\"showBlocks\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"lists-toggle\" class=\"control-label\">Lists</label>\n          <sh-toggle id=\"lists-toggle\" [(checked)]=\"showLists\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"align-toggle\" class=\"control-label\">Alignments</label>\n          <sh-toggle id=\"align-toggle\" [(checked)]=\"showAlignments\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"insert-toggle\" class=\"control-label\">Insertions</label>\n          <sh-toggle id=\"insert-toggle\" [(checked)]=\"showInsertions\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"history-toggle\" class=\"control-label\">History/Code</label>\n          <sh-toggle id=\"history-toggle\" [(checked)]=\"showHistory\"></sh-toggle>\n        </div>\n      }\n    </sh-card>\n  </div>\n\n  <div class=\"sandbox-editor-wrapper\">\n    <sh-editor\n      [(value)]=\"editorValue\"\n      [format]=\"selectedFormat()\"\n      [readonly]=\"isReadonly()\"\n      [toolbar]=\"showToolbar()\"\n      [showFormats]=\"showFormats()\"\n      [showBlocks]=\"showBlocks()\"\n      [showLists]=\"showLists()\"\n      [showAlignments]=\"showAlignments()\"\n      [showInsertions]=\"showInsertions()\"\n      [showHistory]=\"showHistory()\"\n      [customCommands]=\"customEditorCommands()\"\n      [imageUploadEnabled]=\"imageUploadEnabled()\"\n      placeholder=\"Start writing your premium content here...\">\n      <!-- Projected custom toolbar action -->\n      <!-- <button type=\"button\" class=\"sh-editor-btn\" (click)=\"customAction()\" shTooltip=\"Projected Action (Star)\">\n        <sh-icon>star</sh-icon>\n      </button> -->\n    </sh-editor>\n\n    <sh-card class=\"type-b output-card\">\n      <div class=\"output-header\">\n        <h3>Database Output</h3>\n        <button shButton variant=\"outlined\" size=\"small\" (click)=\"copyToClipboard()\">\n          <sh-icon>copy</sh-icon>\n          Copy\n        </button>\n      </div>\n      <p class=\"output-desc\">This is exactly what would be saved in your database:</p>\n      <pre class=\"serialized-preview\"><code>{{ serializedOutput() }}</code></pre>\n    </sh-card>\n  </div>\n</div>\n",
+        "ts": "import { ChangeDetectionStrategy, Component, computed, signal, viewChild } from '@angular/core';\nimport { ShipColor } from '@ship-ui/core';\nimport { ShipButton } from '@ship-ui/core/ship-button';\nimport { ShipButtonGroup } from '@ship-ui/core/ship-button-group';\nimport { ShipCard } from '@ship-ui/core/ship-card';\nimport { ShipEditor, ShipEditorCommand, ShipEditorRegistry, ShipEditorValue } from '@ship-ui/core/ship-editor';\nimport { ShipIcon } from '@ship-ui/core/ship-icon';\nimport { ShipToggle } from '@ship-ui/core/ship-toggle';\n\n@Component({\n  selector: 'app-sandbox-editor',\n  standalone: true,\n  imports: [ShipEditor, ShipButton, ShipCard, ShipToggle, ShipIcon, ShipButtonGroup],\n  templateUrl: './sandbox-editor.html',\n  styleUrl: './sandbox-editor.scss',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class SandboxEditor {\n  constructor() {\n    // Register custom highlight mark extension\n    ShipEditorRegistry.getInstance().registerMark({\n      type: 'highlight',\n      tagName: 'mark',\n      toHTML: (mark: any, text: string) =>\n        `<mark style=\"background-color: var(--warn-2); color: var(--warn-11); padding: 2px 4px; border-radius: 2px;\">${text}</mark>`,\n      parseHTML: (el: HTMLElement) => (el.tagName.toLowerCase() === 'mark' ? { type: 'highlight' } : null),\n    });\n  }\n\n  // Current format selection\n  selectedFormat = signal<'html' | 'markdown' | 'json'>('html');\n\n  editor = viewChild(ShipEditor);\n\n  // Editor states\n  isReadonly = signal<boolean>(false);\n  showToolbar = signal<boolean>(true);\n  selectedColor = signal<ShipColor | null>(null);\n  imageUploadEnabled = signal<boolean>(true);\n\n  // Toolbar group configurations\n  showFormats = signal<boolean>(true);\n  showBlocks = signal<boolean>(true);\n  showLists = signal<boolean>(true);\n  showAlignments = signal<boolean>(true);\n  showInsertions = signal<boolean>(true);\n  showHistory = signal<boolean>(true);\n\n  // Custom action for projected button\n  customAction() {\n    alert('Custom Projected Button Clicked!');\n  }\n\n  customEditorCommands = signal<ShipEditorCommand[]>([\n    // {\n    //   id: 'highlight',\n    //   label: 'Highlight Text',\n    //   icon: 'star',\n    //   description: 'Highlight selected text in yellow',\n    //   action: (editor) => {\n    //     editor.runTransaction((doc, selection) => {\n    //       return formatDocRange(doc, selection.start, selection.end, 'highlight', 'toggle');\n    //     });\n    //   },\n    // },\n    // {\n    //   id: 'info-callout',\n    //   label: 'Info Callout',\n    //   icon: 'terminal',\n    //   description: 'Insert an info callout box',\n    //   action: (editor) => {\n    //     editor.runTransaction((doc, selection) => {\n    //       const { doc: splitDoc } = splitBlock(doc, selection.start);\n    //       const calloutBlock: ShipEditorBlock = {\n    //         type: 'quote',\n    //         attrs: { align: 'left' },\n    //         content: [{ type: 'text', text: '💡 Info: Start typing callout contents here...' }],\n    //       };\n    //       const targetIndex = selection.start.blockIndex + 1;\n    //       splitDoc.splice(targetIndex, 0, calloutBlock);\n    //       return {\n    //         doc: splitDoc,\n    //         selectionShift: {\n    //           start: { blockIndex: targetIndex },\n    //           end: { blockIndex: targetIndex },\n    //         },\n    //       };\n    //     });\n    //   },\n    // },\n  ]);\n\n  // Pre-populated initial contents for each format\n  initialHtml = `<h1>Ship WYSIWYG Editor</h1><p>Welcome! This is a <strong>config-driven</strong> rich-text editor designed to support flexible storage formats.</p><ul><li><strong>Two-way binding</strong> with <code>ControlValueAccessor</code></li><li>Instant conversion to <strong>HTML</strong>, <strong>Markdown</strong>, or <strong>JSON</strong></li><li>Sticky blur-toolbar, light/dark mode support, and word counting</li></ul><blockquote>\"A beautiful interface makes editing content a delight.\"</blockquote><hr><p>Try changing the storage format below to see the serialized output update in real time!</p>`;\n\n  // Current value model\n  editorValue = signal<ShipEditorValue>(this.initialHtml);\n\n  // Stringified preview for database presentation\n  serializedOutput = computed(() => {\n    const val = this.editorValue();\n    if (val === null || val === undefined) return '';\n    if (typeof val === 'string') return val;\n    return JSON.stringify(val, null, 2);\n  });\n\n  // Handle format swapping, converting the value appropriately\n  onFormatChange(format: string | null) {\n    if (format === 'html' || format === 'markdown' || format === 'json') {\n      this.selectedFormat.set(format);\n    }\n  }\n\n  // Copy serialized contents to clipboard\n  copyToClipboard() {\n    navigator.clipboard.writeText(this.serializedOutput());\n  }\n}\n"
       }
     ]
   },
@@ -3401,6 +3550,12 @@
         "description": "",
         "defaultValue": "false"
       },
+      {
+        "name": "ctrlOrCmd",
+        "type": "boolean, string | boolean",
+        "description": "",
+        "defaultValue": "false"
+      },
       {
         "name": "enter",
         "type": "boolean, string | boolean",
@@ -4564,8 +4719,8 @@
       },
       {
         "name": "toggle-card-disallowed",
-        "html": "<sh-toggle-card [disableToggle]=\"true\">\n  <ng-container title>Advanced options</ng-container>\n  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>\n</sh-toggle-card>\n",
-        "ts": "import { ChangeDetectionStrategy, Component } from '@angular/core';\nimport { ShipToggleCard } from '@ship-ui/core/ship-toggle-card';\n\n@Component({\n  selector: 'app-toggle-card-disallowed-example',\n  standalone: true,\n  imports: [ShipToggleCard],\n  templateUrl: './toggle-card-disallowed.html',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class ToggleCardDisallowedExampleComponent {}\n"
+        "html": "<sh-toggle-card [disableToggle]=\"true\">\n  <ng-container title>Advanced options</ng-container>\n  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>\n</sh-toggle-card>\n\n<sh-toggle-card [disableToggle]=\"true\">\n  <div title style=\"display: flex; align-items: center; justify-content: space-between; width: 100%;\">\n    <span>Options</span>\n    <sh-menu [searchable]=\"true\">\n      <button shButton class=\"outlined small\">Select option</button>\n      <ng-container menu>\n        @for (item of menuItems; track item.value) {\n          <button (click)=\"select(item)\" [class.selected]=\"selected === item.value\">\n            {{ item.label }}\n          </button>\n        }\n      </ng-container>\n    </sh-menu>\n  </div>\n  <p>This toggle card has a searchable menu in its title. You should be able to type in the search field.</p>\n</sh-toggle-card>\n",
+        "ts": "import { ChangeDetectionStrategy, Component } from '@angular/core';\nimport { ShipButton } from '@ship-ui/core/ship-button';\nimport { ShipMenu } from '@ship-ui/core/ship-menu';\nimport { ShipToggleCard } from '@ship-ui/core/ship-toggle-card';\n\n@Component({\n  selector: 'app-toggle-card-disallowed-example',\n  standalone: true,\n  imports: [ShipToggleCard, ShipMenu, ShipButton],\n  templateUrl: './toggle-card-disallowed.html',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class ToggleCardDisallowedExampleComponent {\n  menuItems = [\n    { label: 'Dashboard', value: 'dashboard' },\n    { label: 'Users', value: 'users' },\n    { label: 'Settings', value: 'settings' },\n    { label: 'Billing', value: 'billing' },\n  ];\n  selected: string | null = null;\n\n  select(item: any) {\n    this.selected = item.value;\n  }\n}\n"
       },
       {
         "name": "base-card",
@@ -5081,6 +5236,18 @@
     "inputs": [],
     "outputs": [],
     "methods": [
+      {
+        "name": "pause",
+        "parameters": "",
+        "returnType": "void",
+        "description": ""
+      },
+      {
+        "name": "resume",
+        "parameters": "",
+        "returnType": "void",
+        "description": ""
+      },
       {
         "name": "registerDefaults",
         "parameters": "defaults: Record<string, string>",
@@ -5839,7 +6006,7 @@
     "methods": [
       {
         "name": "onCleanup",
-        "parameters": "() => {\n      const index = openMenus.indexOf(this);\n      if (index > -1",
+        "parameters": "() => {\n      if (this.searchable()",
         "returnType": "any",
         "description": ""
       },
@@ -5881,6 +6048,11 @@
       }
     ],
     "examples": [
+      {
+        "name": "titles-search-menu-example",
+        "html": "<sh-menu [searchable]=\"true\">\n  <button shButton class=\"outlined\">Menu with Titles and Search</button>\n  <ng-container menu>\n    @for (section of sections; track section.title) {\n      <h3>{{ section.title }}</h3>\n      @for (item of section.items; track item.value) {\n        <button (click)=\"select(item.value)\" [class.selected]=\"selected === item.value\">\n          {{ item.label }}\n        </button>\n      }\n    }\n  </ng-container>\n</sh-menu>\n",
+        "ts": "import { Component } from '@angular/core';\nimport { ShipButton } from '@ship-ui/core/ship-button';\nimport { ShipMenu } from '@ship-ui/core/ship-menu';\n\n@Component({\n  selector: 'sh-titles-search-menu-example',\n  templateUrl: './titles-search-menu-example.html',\n  styleUrls: ['./titles-search-menu-example.scss'],\n  imports: [ShipMenu, ShipButton],\n  standalone: true,\n})\nexport class TitlesSearchMenuExample {\n  sections = [\n    {\n      title: 'Admin',\n      items: [\n        { label: 'Dashboard', value: 'dashboard' },\n        { label: 'Users', value: 'users' },\n        { label: 'Permissions', value: 'permissions' },\n      ]\n    },\n    {\n      title: 'Personal',\n      items: [\n        { label: 'Profile', value: 'profile' },\n        { label: 'Settings', value: 'settings' },\n        { label: 'Security', value: 'security' },\n      ]\n    },\n    {\n      title: 'Support',\n      items: [\n        { label: 'Help Center', value: 'help' },\n        { label: 'Feedback', value: 'feedback' },\n        { label: 'Contact Us', value: 'contact' },\n      ]\n    }\n  ];\n  selected: string | null = null;\n\n  select(value: string) {\n    this.selected = value;\n  }\n}\n"
+      },
       {
         "name": "icon-suffix-menu",
         "html": "<sh-menu>\n  <button shButton class=\"outlined\">Open menu</button>\n  <ng-container menu>\n    @for (item of menuItems; track item.value) {\n      <button (click)=\"select(item)\" [class.selected]=\"selected() === item.value\">\n        <sh-icon>circle</sh-icon>\n        {{ item.label }}\n        <span suffix>{{ item.hotkey }}</span>\n      </button>\n    }\n  </ng-container>\n</sh-menu>\n",