@growgroup/visual-editor 0.1.6 → 0.2.0

package/src/editor/hooks/useIframeSetup.ts

@@ -10,6 +10,7 @@ import { useCallback, useRef, useEffect } from 'react';
 import { useEditorContext } from '../EditorContext';
 import { buildDomTree, isInlineElement } from '../utils/dom-utils';
 import { EDITOR_IFRAME_STYLES } from '../constants';
+import { isLockedInsidePart } from '../parts';
 
 interface UseIframeSetupReturn {
   /**
@@ -111,6 +112,15 @@ export function useIframeSetup(): UseIframeSetupReturn {
       // selection-boxの子孫要素をすべてスキップ（念のため）
       if (element.closest('.selection-box')) return;
 
+      // 部品のインスタンス(data-part)の中で、スロット(data-slot)の外にある要素は編集対象にしない。
+      // ルート自身とスロットの中は通常どおり(src/editor/parts.ts)。
+      // 保存 HTML には data-editable が残らないので、古い保存物には効かない = 既存の挙動は変わらない
+      if (isLockedInsidePart(element)) {
+        element.removeAttribute('data-editable');
+        element.removeAttribute('data-element-id');
+        return;
+      }
+
       // 既にIDがある場合はスキップ
       if (!element.getAttribute('data-element-id')) {
         const elementId = `el-${Date.now()}-${elementIndex++}`;

package/src/editor/hooks/useMediaLibrary.ts

@@ -9,6 +9,7 @@
  * 同時オープン時のリクエスト重複も in-flight promise で防ぐ。
  */
 
+import { io, notProvided } from '../../io';
 import { useCallback, useEffect, useState } from 'react';
 
 export interface MediaItem {
@@ -48,11 +49,9 @@ function normalizeItem(raw: unknown): MediaItem | null {
 }
 
 async function fetchMediaItems(): Promise<MediaItem[]> {
-  const res = await fetch('/__media');
-  if (!res.ok) {
-    throw new Error(`メディア一覧の取得に失敗しました (HTTP ${res.status})`);
-  }
-  const data = (await res.json()) as MediaResponse;
+  const fetchCatalog = io().apiFetch;
+  if (!fetchCatalog) throw notProvided('apiFetch');
+  const data = await fetchCatalog('/__media') as MediaResponse;
   const items = Array.isArray(data.items) ? data.items : [];
   return items.map(normalizeItem).filter((i): i is MediaItem => i !== null);
 }

package/src/editor/hooks/useResizablePanel.ts

@@ -24,6 +24,15 @@ export interface UseResizablePanelReturn {
   isDragging: boolean;
   /** リサイズハンドルのprops */
   resizeHandleProps: {
+    role: 'separator';
+    tabIndex: number;
+    'aria-label': string;
+    'aria-orientation': 'vertical';
+    'aria-valuemin': number;
+    'aria-valuemax': number;
+    'aria-valuenow': number;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    onDoubleClick: () => void;
     onMouseDown: (e: React.MouseEvent) => void;
     onTouchStart: (e: React.TouchEvent) => void;
     style: React.CSSProperties;
@@ -44,7 +53,8 @@ export function useResizablePanel({
   // ローカルストレージから初期値を読み込み
   const getInitialWidth = () => {
     if (storageKey && typeof window !== 'undefined') {
-      const stored = localStorage.getItem(storageKey);
+      let stored: string | null = null;
+      try { stored = localStorage.getItem(storageKey); } catch { /* 既定幅を使う */ }
       if (stored) {
         const parsed = parseInt(stored, 10);
         if (!isNaN(parsed) && parsed >= minWidth && parsed <= maxWidth) {
@@ -65,11 +75,13 @@ export function useResizablePanel({
     const clampedWidth = Math.min(maxWidth, Math.max(minWidth, newWidth));
     setWidthState(clampedWidth);
 
-    // ローカルストレージに保存
-    if (storageKey && typeof window !== 'undefined') {
-      localStorage.setItem(storageKey, String(clampedWidth));
-    }
-  }, [minWidth, maxWidth, storageKey]);
+  }, [minWidth, maxWidth]);
+
+  // ドラッグ中の同期ストレージ書込みを避け、確定時だけ幅を記憶する。
+  useEffect(() => {
+    if (isDragging || !storageKey) return;
+    try { localStorage.setItem(storageKey, String(width)); } catch { /* 表示は継続 */ }
+  }, [width, isDragging, storageKey]);
 
   // マウスダウン
   const handleMouseDown = useCallback((e: React.MouseEvent) => {
@@ -123,8 +135,11 @@ export function useResizablePanel({
     document.addEventListener('mouseup', handleMouseUp);
     document.addEventListener('touchmove', handleTouchMove);
     document.addEventListener('touchend', handleTouchEnd);
+    document.addEventListener('touchcancel', handleTouchEnd);
 
     // カーソルスタイルを変更
+    const previousCursor = document.body.style.cursor;
+    const previousSelect = document.body.style.userSelect;
     document.body.style.cursor = 'col-resize';
     document.body.style.userSelect = 'none';
 
@@ -133,21 +148,35 @@ export function useResizablePanel({
       document.removeEventListener('mouseup', handleMouseUp);
       document.removeEventListener('touchmove', handleTouchMove);
       document.removeEventListener('touchend', handleTouchEnd);
-      document.body.style.cursor = '';
-      document.body.style.userSelect = '';
+      document.removeEventListener('touchcancel', handleTouchEnd);
+      document.body.style.cursor = previousCursor;
+      document.body.style.userSelect = previousSelect;
     };
   }, [isDragging, direction, setWidth]);
 
   // リサイズハンドルのprops
-  const resizeHandleProps = {
+  const resizeHandleProps: UseResizablePanelReturn['resizeHandleProps'] = {
+    role: 'separator', tabIndex: 0,
+    'aria-label': 'パネルの幅（矢印キーで調整）',
+    'aria-orientation': 'vertical',
+    'aria-valuemin': minWidth, 'aria-valuemax': maxWidth, 'aria-valuenow': width,
+    onDoubleClick: () => setWidth(initialWidth),
+    onKeyDown: (e) => {
+      if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(e.key)) return;
+      e.preventDefault(); e.stopPropagation();
+      const sign = direction === 'right' ? 1 : -1;
+      if (e.key === 'Home') setWidth(minWidth);
+      else if (e.key === 'End') setWidth(maxWidth);
+      else setWidth(width + (e.key === 'ArrowRight' ? sign : -sign) * (e.shiftKey ? 32 : 8));
+    },
     onMouseDown: handleMouseDown,
     onTouchStart: handleTouchStart,
     style: {
-      cursor: 'col-resize',
+      cursor: 'col-resize', touchAction: 'none',
     } as React.CSSProperties,
     className: `
       absolute top-0 ${direction === 'right' ? 'right-0' : 'left-0'}
-      w-1 h-full z-10
+      ed-resize-handle w-1 h-full z-10
       hover:bg-blue-500/50
       ${isDragging ? 'bg-blue-500' : 'bg-transparent'}
       transition-colors duration-150

package/src/editor/parts.ts

@@ -0,0 +1,321 @@
+/**
+ * 部品(パーツ)= HTML の `<template data-part-def>` と、ページに実体化されたインスタンス。
+ *
+ * ここは DOM だけを扱う純粋なユーティリティ(React に依存しない)。
+ *
+ * 【用語】
+ * - 定義   … `<template data-part-def="X" data-part-v="N">` の中のルート要素 1 つ
+ * - 実体化 … 定義を複製してページに置くこと。ルートに `data-part="X" data-part-v="N"` が付く。
+ *            ページには**展開後の完全な HTML** が残る(読むときに何も解決しない)
+ * - スロット … `data-slot="名前"`。インスタンスの中で編集してよい範囲。
+ *            定義を更新したあとの一括反映(parts:sync)でも中身が保たれる
+ *
+ * 【ロック】インスタンスの中でスロットの外にある要素は編集対象にしない
+ * (useIframeSetup が `data-editable` を付けない)。ルート自身は選択できる
+ * (移動・削除・並び替え)。スロットの外を直したいときは「部品から切り離す」。
+ */
+import type { EditorPartDef } from '../io';
+
+export const PART_ATTR = 'data-part';
+export const PART_VERSION_ATTR = 'data-part-v';
+export const SLOT_ATTR = 'data-slot';
+export const PART_DEF_ATTR = 'data-part-def';
+const PART_NAME_ATTR = 'data-part-name';
+const PART_CATEGORY_ATTR = 'data-part-category';
+const PART_DESC_ATTR = 'data-part-desc';
+
+/** 部品の id に使える形へ丸める(ファイル名・属性値になる) */
+export function toPartId(raw: string): string {
+  const s = raw.trim().replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+  return s || `part-${Date.now().toString(36)}`;
+}
+
+function parseIntSafe(v: string | null | undefined, fallback: number): number {
+  const n = Number.parseInt(v ?? '', 10);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+/**
+ * `<template data-part-def>` の文字列(ファイル 1 つぶん)を定義に読む。
+ * template が無い・中身が空なら null。
+ */
+export function parsePartTemplate(source: string, doc: Document = document): EditorPartDef | null {
+  const parser = new (doc.defaultView?.DOMParser ?? DOMParser)();
+  const parsed = parser.parseFromString(source, 'text/html');
+  const tpl = parsed.querySelector<HTMLTemplateElement>(`template[${PART_DEF_ATTR}]`);
+  if (!tpl) return null;
+  const root = tpl.content.firstElementChild;
+  if (!root) return null;
+  const id = tpl.getAttribute(PART_DEF_ATTR)?.trim();
+  if (!id) return null;
+  return {
+    id,
+    name: tpl.getAttribute(PART_NAME_ATTR) ?? undefined,
+    category: tpl.getAttribute(PART_CATEGORY_ATTR) ?? undefined,
+    description: tpl.getAttribute(PART_DESC_ATTR) ?? undefined,
+    version: parseIntSafe(tpl.getAttribute(PART_VERSION_ATTR), 1),
+    html: root.outerHTML,
+  };
+}
+
+function escapeAttr(v: string): string {
+  return v.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+
+/** 定義をファイルに書く形(`<template data-part-def>…</template>`)へ */
+export function serializePartTemplate(def: EditorPartDef): string {
+  const attrs = [
+    `${PART_DEF_ATTR}="${escapeAttr(def.id)}"`,
+    `${PART_VERSION_ATTR}="${def.version}"`,
+    def.name ? `${PART_NAME_ATTR}="${escapeAttr(def.name)}"` : '',
+    def.category ? `${PART_CATEGORY_ATTR}="${escapeAttr(def.category)}"` : '',
+    def.description ? `${PART_DESC_ATTR}="${escapeAttr(def.description)}"` : '',
+  ].filter(Boolean);
+  const body = def.html
+    .split('\n')
+    .map((l) => (l.trim() ? `  ${l}` : l))
+    .join('\n');
+  return `<template ${attrs.join(' ')}>\n${body}\n</template>\n`;
+}
+
+/** 定義の HTML(ルート要素 1 つ)を `doc` の要素にする */
+export function partRootElement(def: EditorPartDef, doc: Document): HTMLElement | null {
+  const tpl = doc.createElement('template');
+  tpl.innerHTML = def.html.trim();
+  const root = tpl.content.firstElementChild;
+  return root ? (doc.importNode(root, true) as HTMLElement) : null;
+}
+
+/**
+ * 実体化: 定義を複製し、ルートに `data-part` `data-part-v` を付けた要素を返す。
+ * ページにはこの要素がそのまま残る。
+ */
+export function materializePart(def: EditorPartDef, doc: Document): HTMLElement | null {
+  const el = partRootElement(def, doc);
+  if (!el) return null;
+  el.setAttribute(PART_ATTR, def.id);
+  el.setAttribute(PART_VERSION_ATTR, String(def.version));
+  return el;
+}
+
+/** インスタンスのルートか */
+export function isPartRoot(el: Element | null | undefined): el is HTMLElement {
+  return !!el && el.nodeType === 1 && el.hasAttribute(PART_ATTR);
+}
+
+/** 要素を含む最も近いインスタンスのルート(自分自身でもよい) */
+export function closestPartRoot(el: Element | null | undefined): HTMLElement | null {
+  if (!el || el.nodeType !== 1) return null;
+  const root = el.closest(`[${PART_ATTR}]`);
+  return root instanceof Element ? (root as HTMLElement) : null;
+}
+
+/** ルートの部品情報(無ければ null) */
+export function partInfoOf(el: Element | null | undefined): { id: string; version: number } | null {
+  if (!isPartRoot(el)) return null;
+  return { id: el.getAttribute(PART_ATTR) ?? '', version: parseIntSafe(el.getAttribute(PART_VERSION_ATTR), 1) };
+}
+
+/**
+ * インスタンスの中でスロットの外にいる(= ロックされている)か。
+ * ルート自身はロックしない(選択して動かせる)。スロット要素とその子孫もロックしない。
+ */
+export function isLockedInsidePart(el: Element): boolean {
+  if (el.hasAttribute(PART_ATTR)) return false;
+  const root = el.parentElement?.closest(`[${PART_ATTR}]`);
+  if (!root) return false;
+  const slot = el.closest(`[${SLOT_ATTR}]`);
+  return !(slot && root.contains(slot) && slot !== root);
+}
+
+/** エディタが作業用に付ける属性・class を落とす(部品の定義や保存 HTML に持ち込まない) */
+export function stripEditorAttrs(root: Element): void {
+  const attrs = ['contenteditable', 'data-editable', 'data-element-id', 'data-original-content', 'data-shape-type', 'data-inline', 'data-display-name', 'data-locked', 'data-hidden'];
+  const classes = ['selected', 'dragging', 'editing', 'rotating', 'panning', 'hover-preview', 'marquee-hover', 'marquee-active', 'text-editable-hover', 'drag-ghost'];
+  const all: Element[] = [root, ...Array.from(root.querySelectorAll('*'))];
+  for (const el of all) {
+    for (const a of attrs) el.removeAttribute(a);
+    for (const attr of Array.from(el.attributes)) {
+      if (attr.name.startsWith('data-original-') || attr.name.startsWith('data-gg-')) el.removeAttribute(attr.name);
+    }
+    if (el.classList.length) {
+      el.classList.remove(...classes);
+      if (!el.getAttribute('class')) el.removeAttribute('class');
+    }
+  }
+}
+
+/** スロットを推定して付ける対象(文字や画像を持ちうる要素) */
+const SLOT_TAGS: Record<string, string> = {
+  h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
+  p: 'body', li: 'item', a: 'link', button: 'button', img: 'image',
+  figcaption: 'caption', blockquote: 'quote', dt: 'term', dd: 'desc',
+  td: 'cell', th: 'cell', label: 'label', span: 'text', time: 'time', small: 'note',
+};
+
+/**
+ * スロットの推定。既に `data-slot` があるものはそのまま。
+ * 文書順に見て、祖先が既にスロットなら付けない(入れ子のスロットを作らない)。
+ * span は文字だけを直接持つときだけ。svg の中は見ない。
+ * 戻り値は付けた数。
+ */
+export function inferSlots(root: Element): number {
+  let count = 0;
+  const used = new Map<string, number>();
+  const nameFor = (base: string) => {
+    const n = (used.get(base) ?? 0) + 1;
+    used.set(base, n);
+    return n === 1 ? base : `${base}-${n}`;
+  };
+  for (const el of Array.from(root.querySelectorAll('[' + SLOT_ATTR + ']'))) {
+    const v = el.getAttribute(SLOT_ATTR) ?? '';
+    const base = v.replace(/-\d+$/, '');
+    if (base) used.set(base, Math.max(used.get(base) ?? 0, 1));
+  }
+  const candidates = Array.from(root.querySelectorAll('*'));
+  for (const el of candidates) {
+    if (el.closest('svg')) continue;
+    if (el.hasAttribute(SLOT_ATTR)) continue;
+    const ancestorSlot = el.parentElement?.closest(`[${SLOT_ATTR}]`);
+    if (ancestorSlot && root.contains(ancestorSlot)) continue;
+    const tag = el.tagName.toLowerCase();
+    const base = SLOT_TAGS[tag];
+    if (!base) continue;
+    if (tag === 'span') {
+      const hasText = Array.from(el.childNodes).some((n) => n.nodeType === 3 && n.textContent?.trim());
+      if (!hasText || el.children.length > 0) continue;
+    }
+    if (tag !== 'img' && !el.textContent?.trim() && el.children.length === 0) continue;
+    el.setAttribute(SLOT_ATTR, nameFor(base));
+    count++;
+  }
+  return count;
+}
+
+/**
+ * 選択要素から部品の定義を作る(「部品として保存」)。
+ * 元の要素は変えない(複製に対して整える)。スロットは推定して付ける。
+ */
+export function partDefFromElement(
+  el: HTMLElement,
+  meta: { id: string; name?: string; category?: string; description?: string; version?: number },
+  options: {
+    /**
+     * スロットを推定して付けるか。新規作成のときだけ true。
+     * 更新(版 +1)で推定すると、定義が意図して固定にしていた要素(ボタンの文言など)が
+     * 黙ってスロットになる。更新では既に付いている data-slot だけを尊重する
+     */
+    inferSlots?: boolean;
+  } = {},
+): EditorPartDef {
+  const clone = el.cloneNode(true) as HTMLElement;
+  stripEditorAttrs(clone);
+  clone.removeAttribute(PART_ATTR);
+  clone.removeAttribute(PART_VERSION_ATTR);
+  // 絶対配置の座標は「その場所」の情報なので定義には持ち込まない
+  for (const k of ['position', 'left', 'top', 'right', 'bottom']) clone.style.removeProperty(k);
+  if (!clone.getAttribute('style')) clone.removeAttribute('style');
+  if (options.inferSlots) inferSlots(clone);
+  return {
+    id: meta.id,
+    name: meta.name,
+    category: meta.category,
+    description: meta.description,
+    version: meta.version ?? 1,
+    html: clone.outerHTML,
+  };
+}
+
+/**
+ * ページ上の要素を、その場でインスタンスにする(「部品として保存」の直後)。
+ * 定義に付けたスロットと同じ位置に `data-slot` を付け、ルートに `data-part` を付ける。
+ * DOM の形は定義と同じ(複製元だから)なので、文書順で対応づける。
+ */
+export function stampAsInstance(el: HTMLElement, def: EditorPartDef, doc: Document): void {
+  const ref = partRootElement(def, doc);
+  if (!ref) return;
+  const refAll = [ref, ...Array.from(ref.querySelectorAll('*'))];
+  const liveAll = [el, ...Array.from(el.querySelectorAll('*'))];
+  // エディタの作業属性は複製時に落としているので、要素数が一致するはず。ずれたらスロットは付けない
+  if (refAll.length === liveAll.length) {
+    for (let i = 0; i < refAll.length; i++) {
+      const s = refAll[i].getAttribute(SLOT_ATTR);
+      if (s) liveAll[i].setAttribute(SLOT_ATTR, s);
+    }
+  }
+  el.setAttribute(PART_ATTR, def.id);
+  el.setAttribute(PART_VERSION_ATTR, String(def.version));
+}
+
+/** 「部品から切り離す」: 出自の記録だけ外す。中身と data-slot はそのまま(普通の HTML になる) */
+export function detachPart(el: HTMLElement): void {
+  el.removeAttribute(PART_ATTR);
+  el.removeAttribute(PART_VERSION_ATTR);
+}
+
+/**
+ * フロー(流し込み)への挿入位置を決める。
+ * ドロップ位置の要素から、「セクションの器」の直下にある祖先まで上がり、その後ろに入れる。
+ * 器 = `[data-wf-body]` / `main` / `#artboard` / body。何も当たらなければ器の末尾。
+ */
+export function insertIntoFlow(doc: Document, el: HTMLElement, x: number, y: number): void {
+  const isContainer = (node: Element | null): boolean =>
+    !!node &&
+    (node === doc.body ||
+      node.id === 'artboard' ||
+      node.hasAttribute('data-wf-body') ||
+      node.tagName === 'MAIN');
+  const fallback = (): Element =>
+    doc.querySelector('[data-wf-body]') ?? doc.querySelector('main') ?? doc.getElementById('artboard') ?? doc.body;
+
+  let hit: Element | null = doc.elementFromPoint(x, y);
+  if (!hit || hit === doc.body || hit.id === 'artboard' || hit.closest('.selection-box')) {
+    fallback().appendChild(el);
+    return;
+  }
+  // 器の直下にあたる祖先まで上がる
+  let anchor: Element = hit;
+  while (anchor.parentElement && !isContainer(anchor.parentElement)) {
+    anchor = anchor.parentElement;
+  }
+  if (!anchor.parentElement) {
+    fallback().appendChild(el);
+    return;
+  }
+  anchor.after(el);
+}
+
+/**
+ * インスタンスの中のロックを今すぐ効かせる(「部品として保存」の直後)。
+ * 通常は useIframeSetup が付け直すが、それは子要素の増減でしか走らないので、ここで落とす。
+ */
+export function applyLockInside(root: HTMLElement): void {
+  for (const el of Array.from(root.querySelectorAll('*'))) {
+    if (!isLockedInsidePart(el)) continue;
+    el.removeAttribute('data-editable');
+    el.removeAttribute('data-element-id');
+    el.removeAttribute('contenteditable');
+    el.classList.remove('selected', 'hover-preview', 'text-editable-hover');
+    if (!el.getAttribute('class')) el.removeAttribute('class');
+  }
+}
+
+/**
+ * 「部品から切り離す」の直後に、ロックされていた子孫を編集できるようにする。
+ * useIframeSetup と同じ形の id を付ける。
+ */
+export function unlockPartDescendants(root: HTMLElement): number {
+  let i = 0;
+  const stamp = Date.now();
+  for (const el of Array.from(root.querySelectorAll('*'))) {
+    if (el.closest('script, style, svg path, svg g')) continue;
+    if (el.tagName === 'SCRIPT' || el.tagName === 'STYLE') continue;
+    if (!el.getAttribute('data-element-id')) {
+      el.setAttribute('data-editable', 'true');
+      el.setAttribute('data-element-id', `el-${stamp}-u${i++}`);
+    } else if (!el.getAttribute('data-editable')) {
+      el.setAttribute('data-editable', 'true');
+    }
+  }
+  return i;
+}

package/src/editor/utils/dom-utils.ts

@@ -253,7 +253,7 @@ export function applyCanvasZoomDom(iframeDoc: Document, zoomPct: number): void {
   // 上の余白は中央寄せでは自然に生まれたが、上端固定では自分で確保する。
   // 縦方向の中央寄せもしない(ページの高さが変わるたびに紙面が動く原因だった)
   const topAnchored = iframeDoc.body.dataset.editorMode === 'webpage';
-  scrollArea.style.paddingTop = topAnchored ? `${padding}px` : '';
+  scrollArea.style.paddingTop = topAnchored ? `32px` : '';
 
   // 紙面が容器に収まる軸はスクロールを中央へ(拡大時のパンには干渉しない)
   if (w * scale <= cw) container.scrollLeft = Math.max(0, (scrollArea.offsetWidth - cw) / 2);
@@ -919,9 +919,10 @@ function buildDomTreeInternal(iframeDoc: Document, rootElement?: Element): DOMTr
         const className = classNameStr.split(' ')
           .filter(c => c && !c.startsWith('selected') && !c.startsWith('dragging') && !c.startsWith('editing'))[0] || '';
 
-        // コンポーネントインスタンス情報を取得
-        const componentInstanceId = htmlChild.getAttribute('data-component-instance') || undefined;
-        const masterComponentId = htmlChild.getAttribute('data-component-master') || undefined;
+        // コンポーネントインスタンス情報を取得(HTML 部品の data-part も同じ印として扱う)
+        const partId = htmlChild.getAttribute('data-part') || undefined;
+        const componentInstanceId = htmlChild.getAttribute('data-component-instance') || partId;
+        const masterComponentId = htmlChild.getAttribute('data-component-master') || partId;
 
         result.push({
           id: elementId,

package/src/index.ts

@@ -52,4 +52,29 @@ export type {
   CommentAction,
   ExportFormat,
   UploadResult,
+  EditorPartDef,
+  EditorPartCategory,
+  EditorPartsLibrary,
 } from "./io";
+export type { CSSVariableDefinition, CSSVariableCategory } from "./types/css-variables";
+
+/**
+ * 部品(HTML の `<template data-part-def>`)のユーティリティ。
+ * 利用側が parts/*.html を読み書きする・スクリプトで同期する(parts:sync)ときに使う。
+ * DOM だけに依存する(Node では linkedom 等の Document を渡す)。
+ */
+export {
+  PART_ATTR,
+  PART_VERSION_ATTR,
+  SLOT_ATTR,
+  PART_DEF_ATTR,
+  parsePartTemplate,
+  serializePartTemplate,
+  materializePart,
+  inferSlots,
+  partDefFromElement,
+  partInfoOf,
+  isPartRoot,
+  isLockedInsidePart,
+  toPartId,
+} from "./editor/parts";

package/src/io.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { CSSVariableDefinition } from "./types/css-variables";
 
 /**
  * エディタと「置き場」のあいだの唯一の境界。
@@ -63,6 +64,43 @@ export type ExportFormat = "pdf" | "pdf-lite" | "pptx" | "pptx-edit";
 
 export type UploadResult = { url: string; width?: number; height?: number };
 
+/**
+ * 部品(パーツ)の定義。利用側では 1 部品 1 ファイル(`parts/<id>.html`)の
+ *
+ *   <template data-part-def="ContactBand" data-part-v="1"
+ *             data-part-name="お問合せ帯" data-part-category="block" data-part-desc="…">
+ *     <section …>…<h2 data-slot="heading">…</h2>…</section>
+ *   </template>
+ *
+ * を想定している。`html` は template の中身(ルート要素 1 つ)。
+ * 文字列と `<template>` の相互変換は `parsePartTemplate` / `serializePartTemplate`(src/editor/parts.ts)。
+ *
+ * ページに挿すときは**実体化**する: 定義を複製してルートに `data-part` `data-part-v` を付けた
+ * 完全な HTML がページに残る。エディタは `data-slot` の中だけを編集対象にし、
+ * 定義を変えたあとの一括反映は利用側のスクリプト(parts:sync)が行う。
+ */
+export type EditorPartDef = {
+  /** 識別子。`data-part` の値になる(ファイル名にも使うので英数字と - _ だけ) */
+  id: string;
+  /** 表示名。無ければ id */
+  name?: string;
+  /** パネルの分類。無ければ "parts" */
+  category?: string;
+  description?: string;
+  /** 定義の版。実体化したインスタンスに `data-part-v` として写る */
+  version: number;
+  /** ルート要素 1 つの HTML */
+  html: string;
+};
+
+export type EditorPartCategory = { id: string; name: string; description?: string };
+
+export type EditorPartsLibrary = {
+  parts: EditorPartDef[];
+  /** 無ければ parts の category から作る */
+  categories?: EditorPartCategory[];
+};
+
 export type EditorIO = {
   /** 一覧とコメントを取る。無ければ空の一覧として振る舞う */
   loadDeck?: () => Promise<EditorDeck>;
@@ -104,6 +142,22 @@ export type EditorIO = {
 
   /** 保存結果の通知。無ければ何もしない */
   notifySave?: (info: { page: number }) => void;
+
+  /**
+   * 部品(HTML の template)の一覧。渡すと部品パネルはこれを使い、
+   * ブラウザ内(localStorage)の JSON コンポーネントは読まない。
+   * 挿入は実体化(完全な HTML をページに残す)になる
+   */
+  loadParts?: () => Promise<EditorPartsLibrary>;
+  /** 部品を作る・更新する(「部品として保存」「部品を更新」)。無ければそれらの操作を出さない */
+  savePart?: (part: EditorPartDef) => Promise<EditorPartDef | void>;
+  /** 部品を消す。無ければ削除を出さない */
+  deletePart?: (id: string) => Promise<void>;
+
+  /** CSS 変数(デザイントークン)の読み込み。無ければブラウザ内(localStorage)に持つ */
+  loadVariables?: () => Promise<CSSVariableDefinition[]>;
+  /** CSS 変数の保存。無ければブラウザ内(localStorage)に持つ */
+  saveVariables?: (variables: CSSVariableDefinition[]) => Promise<void>;
 };
 
 let current: EditorIO = {};