@commonpub/editor 0.5.0 → 0.6.1

package/vue/components/blocks/TextBlock.vue

@@ -0,0 +1,202 @@
+<script setup lang="ts">
+/**
+ * Text/paragraph block — inline TipTap editor for rich text.
+ * Supports bold, italic, code, strike, link, lists.
+ * Detects "/" at start of empty block to trigger slash command menu.
+ */
+import { ref, onMounted, onUnmounted, watch } from 'vue';
+import { Editor } from '@tiptap/core';
+import { Document } from '@tiptap/extension-document';
+import { Text } from '@tiptap/extension-text';
+import { Paragraph } from '@tiptap/extension-paragraph';
+import { Bold } from '@tiptap/extension-bold';
+import { Italic } from '@tiptap/extension-italic';
+import { Code } from '@tiptap/extension-code';
+import { Strike } from '@tiptap/extension-strike';
+import { Link } from '@tiptap/extension-link';
+import { History } from '@tiptap/extension-history';
+import { Placeholder } from '@tiptap/extension-placeholder';
+import { BulletList } from '@tiptap/extension-bullet-list';
+import { OrderedList } from '@tiptap/extension-ordered-list';
+import { ListItem } from '@tiptap/extension-list-item';
+import { Extension } from '@tiptap/core';
+
+const props = defineProps<{
+  content: Record<string, unknown>;
+}>();
+
+const emit = defineEmits<{
+  update: [content: Record<string, unknown>];
+  'slash-command': [];
+  'selection-change': [hasSelection: boolean, rect: DOMRect | null];
+  'enter-at-end': [];
+  'backspace-empty': [];
+}>();
+
+const editorEl = ref<HTMLElement | null>(null);
+let editor: Editor | null = null;
+
+onMounted(() => {
+  if (!editorEl.value) return;
+
+  editor = new Editor({
+    element: editorEl.value,
+    extensions: [
+      Document,
+      Text,
+      Paragraph,
+      Bold,
+      Italic,
+      Code,
+      Strike,
+      Link.configure({ openOnClick: false }),
+      History,
+      BulletList,
+      OrderedList,
+      ListItem,
+      Placeholder.configure({ placeholder: 'Type / for commands...' }),
+      Extension.create({
+        name: 'blockKeyboard',
+        addKeyboardShortcuts() {
+          return {
+            'Enter': ({ editor: e }) => {
+              // If cursor is at the very end of the document and last node is an empty paragraph, create new block
+              const { state } = e;
+              const { $from } = state.selection;
+              const atEnd = $from.pos === state.doc.content.size - 1;
+              const isEmpty = state.doc.textContent.length === 0;
+              const lastNode = state.doc.lastChild;
+              const lastIsEmptyP = lastNode?.type.name === 'paragraph' && lastNode.textContent === '';
+
+              // If we're at end and the text has content, emit to create a new block below
+              if (atEnd && !isEmpty) {
+                emit('enter-at-end');
+                return true;
+              }
+              return false;
+            },
+            'Backspace': ({ editor: e }) => {
+              // If block is completely empty, emit to delete this block
+              if (e.isEmpty) {
+                emit('backspace-empty');
+                return true;
+              }
+              return false;
+            },
+          };
+        },
+      }),
+    ],
+    content: (props.content.html as string) || '',
+    onUpdate: ({ editor: e }) => {
+      const html = e.getHTML();
+      const text = e.getText();
+
+      // Detect slash command: "/" typed at start of otherwise-empty block
+      if (text === '/') {
+        // Clear the slash character and trigger command menu
+        e.commands.clearContent(true);
+        emit('slash-command');
+        return;
+      }
+
+      emit('update', { html });
+    },
+    onSelectionUpdate: ({ editor: e }) => {
+      const { from, to } = e.state.selection;
+      const hasSelection = from !== to;
+
+      if (hasSelection) {
+        // Get the bounding rect of the selection for floating toolbar positioning
+        const view = e.view;
+        const start = view.coordsAtPos(from);
+        const end = view.coordsAtPos(to);
+        const rect = new DOMRect(
+          Math.min(start.left, end.left),
+          start.top,
+          Math.abs(end.right - start.left),
+          end.bottom - start.top,
+        );
+        emit('selection-change', true, rect);
+      } else {
+        emit('selection-change', false, null);
+      }
+    },
+  });
+});
+
+onUnmounted(() => {
+  editor?.destroy();
+});
+
+// Sync external content changes (e.g. undo at the block level)
+watch(() => props.content.html, (newHtml) => {
+  if (editor && newHtml !== editor.getHTML()) {
+    editor.commands.setContent((newHtml as string) || '', false);
+  }
+});
+
+/** Expose the TipTap editor instance for the floating toolbar */
+function getEditor(): Editor | null {
+  return editor;
+}
+
+defineExpose({ getEditor });
+</script>
+
+<template>
+  <div ref="editorEl" class="cpub-text-block" />
+</template>
+
+<style scoped>
+.cpub-text-block {
+  font-size: 15px;
+  line-height: 1.75;
+  color: var(--text);
+  min-height: 1.75em;
+}
+
+.cpub-text-block :deep(.tiptap) {
+  outline: none;
+  min-height: 1.75em;
+}
+
+.cpub-text-block :deep(.tiptap p) {
+  margin-bottom: 0.5em;
+}
+
+.cpub-text-block :deep(.tiptap p:last-child) {
+  margin-bottom: 0;
+}
+
+.cpub-text-block :deep(.tiptap p.is-editor-empty:first-child::before) {
+  content: attr(data-placeholder);
+  color: var(--text-faint);
+  pointer-events: none;
+  float: left;
+  height: 0;
+}
+
+.cpub-text-block :deep(.tiptap strong) {
+  font-weight: 600;
+}
+
+.cpub-text-block :deep(.tiptap code) {
+  font-family: var(--font-mono);
+  font-size: 0.9em;
+  padding: 1px 4px;
+  background: var(--surface3);
+  border: var(--border-width-default) solid var(--border2);
+}
+
+.cpub-text-block :deep(.tiptap a) {
+  color: var(--accent);
+  text-decoration: underline;
+}
+
+.cpub-text-block :deep(.tiptap ul),
+.cpub-text-block :deep(.tiptap ol) {
+  padding-left: 1.5em;
+  margin-bottom: 0.5em;
+}
+</style>

package/vue/components/blocks/ToolListBlock.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+/**
+ * Tool list block — list of required tools with name and notes.
+ */
+import { computed } from 'vue';
+interface Tool { name: string; url?: string; required?: boolean; notes?: string; }
+
+const props = defineProps<{
+  content: Record<string, unknown>;
+}>();
+
+const emit = defineEmits<{
+  update: [content: Record<string, unknown>];
+}>();
+
+const tools = computed(() => (props.content.tools as Tool[]) ?? []);
+
+function updateTool(index: number, field: string, value: unknown): void {
+  const updated = [...tools.value];
+  updated[index] = { ...updated[index]!, [field]: value };
+  emit('update', { tools: updated });
+}
+
+function addTool(): void {
+  emit('update', { tools: [...tools.value, { name: '', required: true }] });
+}
+
+function removeTool(index: number): void {
+  emit('update', { tools: tools.value.filter((_: Tool, i: number) => i !== index) });
+}
+</script>
+
+<template>
+  <div class="cpub-tools-block">
+    <div class="cpub-tools-header">
+      <i class="fa-solid fa-wrench cpub-tools-icon"></i>
+      <span class="cpub-tools-title">Tools Required</span>
+      <button class="cpub-tools-add" @click="addTool"><i class="fa-solid fa-plus"></i> Add tool</button>
+    </div>
+    <div class="cpub-tools-list">
+      <div v-for="(tool, i) in tools" :key="i" class="cpub-tool-item">
+        <input class="cpub-tool-name" type="text" :value="tool.name" placeholder="Tool name..." @input="updateTool(i, 'name', ($event.target as HTMLInputElement).value)" />
+        <input class="cpub-tool-note" type="text" :value="tool.notes ?? ''" placeholder="Notes..." @input="updateTool(i, 'notes', ($event.target as HTMLInputElement).value)" />
+        <button class="cpub-tool-remove" @click="removeTool(i)"><i class="fa-solid fa-xmark"></i></button>
+      </div>
+      <div v-if="tools.length === 0" class="cpub-tools-empty" @click="addTool">
+        <i class="fa-solid fa-plus"></i> Add your first tool
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.cpub-tools-block { border: var(--border-width-default) solid var(--border2); background: var(--surface); }
+.cpub-tools-header { display: flex; align-items: center; gap: 8px; padding: 10px 14px; border-bottom: var(--border-width-default) solid var(--border2); background: var(--surface2); }
+.cpub-tools-icon { font-size: 12px; color: var(--accent); }
+.cpub-tools-title { font-size: 12px; font-weight: 600; flex: 1; }
+.cpub-tools-add { font-family: var(--font-mono); font-size: 10px; padding: 3px 8px; background: transparent; border: var(--border-width-default) solid var(--border2); color: var(--text-dim); cursor: pointer; display: flex; align-items: center; gap: 4px; }
+.cpub-tools-add:hover { border-color: var(--accent); color: var(--accent); }
+.cpub-tools-list { padding: 8px; }
+.cpub-tool-item { display: flex; align-items: center; gap: 8px; padding: 6px 8px; border-bottom: var(--border-width-default) solid var(--border2); }
+.cpub-tool-item:last-child { border-bottom: none; }
+.cpub-tool-name { flex: 1; font-size: 12px; font-weight: 500; background: transparent; border: none; outline: none; color: var(--text); }
+.cpub-tool-name::placeholder { color: var(--text-faint); }
+.cpub-tool-note { flex: 1; font-size: 11px; background: transparent; border: none; outline: none; color: var(--text-dim); }
+.cpub-tool-note::placeholder { color: var(--text-faint); }
+.cpub-tool-remove { background: none; border: none; color: var(--text-faint); cursor: pointer; font-size: 10px; }
+.cpub-tool-remove:hover { color: var(--red); }
+.cpub-tools-empty { padding: 20px; text-align: center; font-size: 12px; color: var(--text-faint); cursor: pointer; }
+.cpub-tools-empty:hover { color: var(--accent); background: var(--accent-bg); }
+</style>

package/vue/components/blocks/VideoBlock.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+
+const props = defineProps<{ content: Record<string, unknown> }>();
+const emit = defineEmits<{ update: [content: Record<string, unknown>] }>();
+const url = computed(() => (props.content.url as string) ?? '');
+function updateField(field: string, value: string): void { emit('update', { ...props.content, [field]: value }); }
+</script>
+<template>
+  <div class="cpub-video-block">
+    <div class="cpub-video-header"><i class="fa-solid fa-film"></i> Video Embed</div>
+    <input class="cpub-video-url" type="url" :value="url" placeholder="Paste YouTube or Vimeo URL..." @input="updateField('url', ($event.target as HTMLInputElement).value)" />
+    <div v-if="url" class="cpub-video-preview"><i class="fa-solid fa-play"></i> {{ url }}</div>
+  </div>
+</template>
+<style scoped>
+.cpub-video-block { border: var(--border-width-default) solid var(--border2); background: var(--surface); }
+.cpub-video-header { padding: 8px 12px; font-size: 12px; font-weight: 600; background: var(--surface2); border-bottom: var(--border-width-default) solid var(--border2); display: flex; align-items: center; gap: 8px; }
+.cpub-video-header i { color: var(--accent); }
+.cpub-video-url { width: 100%; padding: 8px 12px; font-size: 12px; background: transparent; border: none; border-bottom: var(--border-width-default) solid var(--border2); color: var(--text); outline: none; }
+.cpub-video-url:focus { border-bottom-color: var(--accent); }
+.cpub-video-url::placeholder { color: var(--text-faint); }
+.cpub-video-preview { padding: 32px; text-align: center; font-size: 12px; color: var(--text-dim); background: var(--text); color: var(--surface); display: flex; align-items: center; justify-content: center; gap: 8px; }
+</style>

package/vue/composables/useBlockEditor.ts

@@ -0,0 +1,190 @@
+/**
+ * Block editor composable — manages an array of content blocks with full CRUD operations.
+ * Blocks are stored as { id, type, content } and serialized to/from BlockTuple format for persistence.
+ *
+ * This is the canonical location — replaces duplicates in layer and explainer.
+ */
+import { ref, computed, readonly, type Ref } from 'vue';
+import type { BlockTuple } from '@commonpub/editor';
+import type { EditorBlock, BlockEditorOptions } from '../types.js';
+
+/** Default content values when creating a new block of each type */
+const BLOCK_DEFAULTS: Record<string, () => Record<string, unknown>> = {
+  paragraph: () => ({ html: '' }),
+  heading: () => ({ text: '', level: 2 }),
+  code_block: () => ({ code: '', language: '', filename: '' }),
+  image: () => ({ src: '', alt: '', caption: '' }),
+  blockquote: () => ({ html: '', attribution: '' }),
+  callout: () => ({ html: '', variant: 'info' }),
+  gallery: () => ({ images: [] }),
+  video: () => ({ url: '', platform: 'youtube', caption: '' }),
+  embed: () => ({ url: '', type: 'generic', html: '' }),
+  horizontal_rule: () => ({}),
+  partsList: () => ({ parts: [] }),
+  buildStep: () => ({ stepNumber: 1, instructions: '', image: '', time: '' }),
+  toolList: () => ({ tools: [] }),
+  downloads: () => ({ files: [] }),
+  quiz: () => ({ question: '', options: [], feedback: '' }),
+  interactiveSlider: () => ({ label: '', min: 0, max: 100, step: 1, defaultValue: 50, states: [] }),
+  checkpoint: () => ({ message: '' }),
+  mathNotation: () => ({ expression: '', display: false }),
+  bulletList: () => ({ html: '' }),
+  orderedList: () => ({ html: '' }),
+  sectionHeader: () => ({ tag: '', title: '', body: '' }),
+  markdown: () => ({ content: '' }),
+};
+
+function generateId(): string {
+  return `blk-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function useBlockEditor(initialBlocks?: BlockTuple[], options?: BlockEditorOptions) {
+  const blocks = ref<EditorBlock[]>([]);
+  const selectedBlockId = ref<string | null>(null);
+
+  // Merge custom defaults with built-in defaults
+  const defaults = options?.blockDefaults
+    ? { ...BLOCK_DEFAULTS, ...options.blockDefaults }
+    : BLOCK_DEFAULTS;
+
+  // --- Init from BlockTuples ---
+  function fromBlockTuples(tuples: BlockTuple[]): void {
+    blocks.value = tuples.map(([type, content]) => ({
+      id: generateId(),
+      type,
+      content: { ...content },
+    }));
+  }
+
+  if (initialBlocks && initialBlocks.length > 0) {
+    fromBlockTuples(initialBlocks);
+  }
+
+  // --- Serialize back to BlockTuples ---
+  function toBlockTuples(): BlockTuple[] {
+    return blocks.value.map((b) => [b.type, { ...b.content }]);
+  }
+
+  // --- Mutations ---
+
+  function addBlock(type: string, attrs?: Record<string, unknown>, atIndex?: number): string {
+    const blockDefaults = defaults[type]?.() ?? {};
+    const block: EditorBlock = {
+      id: generateId(),
+      type,
+      content: { ...blockDefaults, ...attrs },
+    };
+
+    if (atIndex !== undefined && atIndex >= 0 && atIndex <= blocks.value.length) {
+      blocks.value.splice(atIndex, 0, block);
+    } else {
+      blocks.value.push(block);
+    }
+
+    selectedBlockId.value = block.id;
+    return block.id;
+  }
+
+  function replaceBlock(id: string, newType: string, attrs?: Record<string, unknown>): string {
+    const idx = blocks.value.findIndex((b) => b.id === id);
+    if (idx === -1) return addBlock(newType, attrs);
+
+    const blockDefaults = defaults[newType]?.() ?? {};
+    const newBlock: EditorBlock = {
+      id: generateId(),
+      type: newType,
+      content: { ...blockDefaults, ...attrs },
+    };
+
+    blocks.value.splice(idx, 1, newBlock);
+    selectedBlockId.value = newBlock.id;
+    return newBlock.id;
+  }
+
+  function removeBlock(id: string): void {
+    const idx = blocks.value.findIndex((b) => b.id === id);
+    if (idx === -1) return;
+    blocks.value.splice(idx, 1);
+    if (selectedBlockId.value === id) {
+      selectedBlockId.value = null;
+    }
+  }
+
+  function clearBlocks(): void {
+    blocks.value.splice(0, blocks.value.length);
+    selectedBlockId.value = null;
+  }
+
+  function updateBlock(id: string, content: Record<string, unknown>): void {
+    const block = blocks.value.find((b) => b.id === id);
+    if (block) {
+      block.content = { ...block.content, ...content };
+    }
+  }
+
+  function moveBlock(fromIndex: number, toIndex: number): void {
+    if (fromIndex < 0 || fromIndex >= blocks.value.length) return;
+    if (toIndex < 0 || toIndex >= blocks.value.length) return;
+    const [moved] = blocks.value.splice(fromIndex, 1);
+    blocks.value.splice(toIndex, 0, moved!);
+  }
+
+  function moveBlockUp(id: string): void {
+    const idx = blocks.value.findIndex((b) => b.id === id);
+    if (idx > 0) moveBlock(idx, idx - 1);
+  }
+
+  function moveBlockDown(id: string): void {
+    const idx = blocks.value.findIndex((b) => b.id === id);
+    if (idx < blocks.value.length - 1) moveBlock(idx, idx + 1);
+  }
+
+  function duplicateBlock(id: string): void {
+    const idx = blocks.value.findIndex((b) => b.id === id);
+    if (idx === -1) return;
+    const original = blocks.value[idx]!;
+    const clone: EditorBlock = {
+      id: generateId(),
+      type: original.type,
+      content: JSON.parse(JSON.stringify(original.content)),
+    };
+    blocks.value.splice(idx + 1, 0, clone);
+    selectedBlockId.value = clone.id;
+  }
+
+  function selectBlock(id: string | null): void {
+    selectedBlockId.value = id;
+  }
+
+  function getBlockIndex(id: string): number {
+    return blocks.value.findIndex((b) => b.id === id);
+  }
+
+  const isEmpty = computed(() => blocks.value.length === 0);
+
+  const selectedBlock = computed(() =>
+    blocks.value.find((b) => b.id === selectedBlockId.value) ?? null,
+  );
+
+  return {
+    blocks: readonly(blocks) as Readonly<Ref<EditorBlock[]>>,
+    selectedBlockId: readonly(selectedBlockId),
+    selectedBlock,
+    isEmpty,
+    addBlock,
+    removeBlock,
+    clearBlocks,
+    updateBlock,
+    moveBlock,
+    moveBlockUp,
+    moveBlockDown,
+    duplicateBlock,
+    replaceBlock,
+    selectBlock,
+    getBlockIndex,
+    toBlockTuples,
+    fromBlockTuples,
+  };
+}
+
+export type BlockEditor = ReturnType<typeof useBlockEditor>;

package/vue/index.ts

@@ -0,0 +1,59 @@
+// @commonpub/editor/vue — Vue 3 block editor components and composables
+//
+// Usage:
+//   import { BlockCanvas, BlockPicker, useBlockEditor } from '@commonpub/editor/vue';
+//   import type { EditorBlock, BlockEditor } from '@commonpub/editor/vue';
+
+// --- Composables ---
+export { useBlockEditor } from './composables/useBlockEditor.js';
+export type { BlockEditor } from './composables/useBlockEditor.js';
+
+// --- Infrastructure components ---
+export { default as BlockCanvas } from './components/BlockCanvas.vue';
+export { default as BlockWrapper } from './components/BlockWrapper.vue';
+export { default as BlockPicker } from './components/BlockPicker.vue';
+export { default as BlockInsertZone } from './components/BlockInsertZone.vue';
+export { default as EditorBlocks } from './components/EditorBlocks.vue';
+export { default as EditorSection } from './components/EditorSection.vue';
+export { default as EditorShell } from './components/EditorShell.vue';
+export { default as EditorTagInput } from './components/EditorTagInput.vue';
+export { default as EditorVisibility } from './components/EditorVisibility.vue';
+
+// --- Block components ---
+export { default as TextBlock } from './components/blocks/TextBlock.vue';
+export { default as HeadingBlock } from './components/blocks/HeadingBlock.vue';
+export { default as CodeBlock } from './components/blocks/CodeBlock.vue';
+export { default as ImageBlock } from './components/blocks/ImageBlock.vue';
+export { default as QuoteBlock } from './components/blocks/QuoteBlock.vue';
+export { default as CalloutBlock } from './components/blocks/CalloutBlock.vue';
+export { default as DividerBlock } from './components/blocks/DividerBlock.vue';
+export { default as VideoBlock } from './components/blocks/VideoBlock.vue';
+export { default as EmbedBlock } from './components/blocks/EmbedBlock.vue';
+export { default as GalleryBlock } from './components/blocks/GalleryBlock.vue';
+export { default as MarkdownBlock } from './components/blocks/MarkdownBlock.vue';
+export { default as MathBlock } from './components/blocks/MathBlock.vue';
+export { default as PartsListBlock } from './components/blocks/PartsListBlock.vue';
+export { default as BuildStepBlock } from './components/blocks/BuildStepBlock.vue';
+export { default as ToolListBlock } from './components/blocks/ToolListBlock.vue';
+export { default as DownloadsBlock } from './components/blocks/DownloadsBlock.vue';
+export { default as QuizBlock } from './components/blocks/QuizBlock.vue';
+export { default as SliderBlock } from './components/blocks/SliderBlock.vue';
+export { default as CheckpointBlock } from './components/blocks/CheckpointBlock.vue';
+export { default as SectionHeaderBlock } from './components/blocks/SectionHeaderBlock.vue';
+
+// --- Provide/inject keys ---
+export { BLOCK_COMPONENTS_KEY, UPLOAD_HANDLER_KEY, SEARCH_PRODUCTS_KEY } from './provide.js';
+export type { BlockComponentMap } from './provide.js';
+
+// --- Types ---
+export type {
+  EditorBlock,
+  BlockEditorOptions,
+  BlockTypeDef,
+  BlockTypeGroup,
+  BlockDef,
+  BlockGroup,
+} from './types.js';
+
+// --- Utilities ---
+export { sanitizeBlockHtml } from './utils.js';

package/vue/provide.ts

@@ -0,0 +1,28 @@
+/**
+ * Provide/inject keys for block editor component customization.
+ *
+ * Consumers can override individual block components by providing a component map:
+ *
+ * ```ts
+ * import { provide } from 'vue';
+ * import { BLOCK_COMPONENTS_KEY, type BlockComponentMap } from '@commonpub/editor/vue';
+ * import CustomImageBlock from './CustomImageBlock.vue';
+ *
+ * provide(BLOCK_COMPONENTS_KEY, { image: CustomImageBlock });
+ * ```
+ *
+ * BlockCanvas merges provided overrides with its built-in component map,
+ * so you only need to provide the components you want to override.
+ */
+import type { InjectionKey, Component } from 'vue';
+
+export type BlockComponentMap = Record<string, Component>;
+
+/** Injection key for block component overrides */
+export const BLOCK_COMPONENTS_KEY: InjectionKey<BlockComponentMap> = Symbol('cpub-block-components');
+
+/** Injection key for upload handler */
+export const UPLOAD_HANDLER_KEY: InjectionKey<(file: File) => Promise<{ url: string; width?: number | null; height?: number | null }>> = Symbol('cpub-upload-handler');
+
+/** Injection key for product search handler */
+export const SEARCH_PRODUCTS_KEY: InjectionKey<(query: string) => Promise<Array<{ id: string; name: string; slug: string; description: string | null; category: string | null; imageUrl: string | null; purchaseUrl: string | null }>>> = Symbol('cpub-search-products');

package/vue/types.ts

@@ -0,0 +1,40 @@
+export interface EditorBlock {
+  id: string;
+  type: string;
+  content: Record<string, unknown>;
+}
+
+export interface BlockEditorOptions {
+  /** Override default content values per block type */
+  blockDefaults?: Record<string, () => Record<string, unknown>>;
+}
+
+// BlockEditor type is derived from the composable's return type — see useBlockEditor.ts
+// Re-exported from the composable module to ensure type compatibility
+
+export interface BlockTypeDef {
+  type: string;
+  label: string;
+  icon: string;
+  description?: string;
+  attrs?: Record<string, unknown>;
+}
+
+export interface BlockTypeGroup {
+  name: string;
+  blocks: BlockTypeDef[];
+}
+
+export interface BlockDef {
+  type: string;
+  label: string;
+  icon: string;
+  description?: string;
+  attrs?: Record<string, unknown>;
+}
+
+export interface BlockGroup {
+  name: string;
+  variant?: string;
+  blocks: BlockDef[];
+}

package/vue/utils.ts

@@ -0,0 +1,12 @@
+/**
+ * HTML sanitization for v-html bindings in block editor components.
+ *
+ * Content is sanitized at the API/storage layer:
+ * - Local content: structured blocks via TipTap (no raw HTML injection)
+ * - Federated content: sanitized on ingest
+ *
+ * This provides the interface for components that use v-html.
+ */
+export function sanitizeBlockHtml(html: string): string {
+  return html;
+}