@jackuait/blok 0.10.8 → 0.10.9

package/src/components/utils/data-model-transform.ts

@@ -844,31 +844,105 @@ const processRootCalloutItem = (
  * @param blocks - array of flat blocks with parent/content references
  * @returns collapsed array with nested structures
  */
+/**
+ * Groups one block under its parent in the derived-content map if it has a
+ * valid parent reference. Helper extracted for collapseToLegacy reconciliation.
+ */
+const appendChildToDerivedContent = (
+  block: OutputBlockData,
+  blockById: Map<BlockId, OutputBlockData>,
+  derivedContent: Map<BlockId, BlockId[]>
+): void => {
+  if (!block.id || !block.parent || !blockById.has(block.parent)) {
+    return;
+  }
+  const siblings = derivedContent.get(block.parent);
+
+  if (siblings === undefined) {
+    derivedContent.set(block.parent, [block.id]);
+
+    return;
+  }
+  siblings.push(block.id);
+};
+
+/**
+ * Merges live (parent-derived) ids into the existing content[] preserving its
+ * order, dropping any dead ids that don't resolve to a block in the input.
+ */
+const mergeContentIds = (
+  existingContent: BlockId[] | undefined,
+  derivedIds: BlockId[],
+  blockById: Map<BlockId, OutputBlockData>
+): BlockId[] => {
+  const existing = Array.isArray(existingContent) ? existingContent : [];
+  const merged = existing.filter((id) => blockById.has(id));
+
+  for (const id of derivedIds) {
+    if (!merged.includes(id)) {
+      merged.push(id);
+    }
+  }
+
+  return merged;
+};
+
 export const collapseToLegacy = (blocks: OutputBlockData[]): OutputBlockData[] => {
+  // Defense-in-depth: reconcile each parent's content[] from children's parent
+  // fields before processing. Saver is the primary source of truth for content[]
+  // (see src/components/modules/saver.ts#doSave), but this pass guarantees the
+  // invariant `child.parent === X ⇒ X.content.includes(child.id)` even when
+  // OutputBlockData originates from a path that bypassed the saver — migrations,
+  // external JSON, tests, 3rd-party consumers. Without this, stale content[]
+  // causes processRootCalloutItem to eject real children as root siblings.
+  const reconciledBlocks = blocks.map((block) => ({ ...block }));
+  const reconciledById = new Map<BlockId, OutputBlockData>();
+
+  for (const block of reconciledBlocks) {
+    if (block.id) {
+      reconciledById.set(block.id, block);
+    }
+  }
+
+  const derivedContent = new Map<BlockId, BlockId[]>();
+
+  for (const block of reconciledBlocks) {
+    appendChildToDerivedContent(block, reconciledById, derivedContent);
+  }
+
+  for (const [parentId, derivedIds] of derivedContent) {
+    const parent = reconciledById.get(parentId);
+
+    if (parent === undefined) {
+      continue;
+    }
+    parent.content = mergeContentIds(parent.content, derivedIds, reconciledById);
+  }
+
   // Build a map of blocks by ID for quick lookup
   const blockMap = new Map<BlockId, OutputBlockData>();
 
-  for (const block of blocks) {
+  for (const block of reconciledBlocks) {
     if (block.id) {
       blockMap.set(block.id, block);
     }
   }
 
   // If no flat-model list, toggle, or callout blocks, just strip hierarchy fields and return
-  const hasFlatListBlocks = blocks.some(isFlatModelListBlock);
-  const hasFlatToggleBlocks = blocks.some(isFlatModelToggleBlock);
-  const hasFlatToggleableHeaders = blocks.some(b => isToggleableHeaderBlock(b) && !b.parent);
-  const hasFlatCalloutBlocks = blocks.some(isFlatModelCalloutBlock);
+  const hasFlatListBlocks = reconciledBlocks.some(isFlatModelListBlock);
+  const hasFlatToggleBlocks = reconciledBlocks.some(isFlatModelToggleBlock);
+  const hasFlatToggleableHeaders = reconciledBlocks.some(b => isToggleableHeaderBlock(b) && !b.parent);
+  const hasFlatCalloutBlocks = reconciledBlocks.some(isFlatModelCalloutBlock);
 
   if (!hasFlatListBlocks && !hasFlatToggleBlocks && !hasFlatToggleableHeaders && !hasFlatCalloutBlocks) {
-    return blocks.map(stripHierarchyFields);
+    return reconciledBlocks.map(stripHierarchyFields);
   }
 
   // Process blocks, converting root flat-model list blocks to legacy List blocks
   const result: OutputBlockData[] = [];
   const processedIds = new Set<BlockId>();
 
-  for (const block of blocks) {
+  for (const block of reconciledBlocks) {
     const alreadyProcessed = block.id && processedIds.has(block.id);
 
     if (alreadyProcessed) {

package/src/components/utils/hierarchy-invariant.ts

@@ -0,0 +1,137 @@
+import type { OutputBlockData } from '@/types';
+import type { BlockId } from '../../../types/data-formats/block-id';
+
+/**
+ * Hierarchy invariant validator.
+ *
+ * Every block with `parent: X` must appear in `X.content`, and every id in a
+ * block's `content[]` must resolve to a block whose `parent` points back. Any
+ * drift between the two representations is the signature of the callout paste
+ * ejection bug (and its siblings across toggle, toggleable header, list, and
+ * any future container block).
+ *
+ * This util exists so tests and saver-level assertions can detect drift at
+ * any point in the pipeline — load, save, collapse, or post-mutation — without
+ * hand-rolling the same loop. Treat it as the single source of truth for the
+ * parent/content invariant.
+ */
+
+export interface HierarchyViolation {
+  kind:
+    | 'child-parent-missing'
+    | 'child-not-in-parent-content'
+    | 'content-id-dangling'
+    | 'content-parent-mismatch'
+    | 'content-duplicate';
+  blockId: BlockId | undefined;
+  parentId?: BlockId;
+  childId?: BlockId;
+  message: string;
+}
+
+const pushViolation = (violations: HierarchyViolation[], v: HierarchyViolation): void => {
+  violations.push(v);
+};
+
+const checkParentLinks = (
+  block: OutputBlockData,
+  blockById: Map<BlockId, OutputBlockData>,
+  violations: HierarchyViolation[]
+): void => {
+  if (block.parent === undefined || block.parent === null) {
+    return;
+  }
+  const parent = blockById.get(block.parent);
+
+  if (parent === undefined) {
+    pushViolation(violations, {
+      kind: 'child-parent-missing',
+      blockId: block.id,
+      parentId: block.parent,
+      message: `Block ${String(block.id)} references missing parent ${String(block.parent)}`,
+    });
+
+    return;
+  }
+  if (block.id === undefined || !Array.isArray(parent.content) || !parent.content.includes(block.id)) {
+    pushViolation(violations, {
+      kind: 'child-not-in-parent-content',
+      blockId: block.id,
+      parentId: block.parent,
+      message: `Block ${String(block.id)} has parent=${String(block.parent)} but that parent's content[] does not include it`,
+    });
+  }
+};
+
+const checkContentArray = (
+  block: OutputBlockData,
+  blockById: Map<BlockId, OutputBlockData>,
+  violations: HierarchyViolation[]
+): void => {
+  if (!Array.isArray(block.content)) {
+    return;
+  }
+  const seen = new Set<BlockId>();
+
+  for (const childId of block.content) {
+    if (seen.has(childId)) {
+      pushViolation(violations, {
+        kind: 'content-duplicate',
+        blockId: block.id,
+        childId,
+        message: `Block ${String(block.id)}.content[] contains duplicate id ${String(childId)}`,
+      });
+      continue;
+    }
+    seen.add(childId);
+
+    const child = blockById.get(childId);
+
+    if (child === undefined) {
+      pushViolation(violations, {
+        kind: 'content-id-dangling',
+        blockId: block.id,
+        childId,
+        message: `Block ${String(block.id)}.content[] references missing child ${String(childId)}`,
+      });
+      continue;
+    }
+    if (child.parent !== block.id) {
+      pushViolation(violations, {
+        kind: 'content-parent-mismatch',
+        blockId: block.id,
+        childId,
+        message: `Block ${String(block.id)}.content[] includes ${String(childId)} but that child's parent is ${String(child.parent)}`,
+      });
+    }
+  }
+};
+
+export const validateHierarchy = (blocks: OutputBlockData[]): HierarchyViolation[] => {
+  const violations: HierarchyViolation[] = [];
+  const blockById = new Map<BlockId, OutputBlockData>();
+
+  for (const block of blocks) {
+    if (block.id !== undefined) {
+      blockById.set(block.id, block);
+    }
+  }
+
+  for (const block of blocks) {
+    checkParentLinks(block, blockById, violations);
+    checkContentArray(block, blockById, violations);
+  }
+
+  return violations;
+};
+
+export const assertHierarchy = (blocks: OutputBlockData[], context: string): void => {
+  const violations = validateHierarchy(blocks);
+
+  if (violations.length === 0) {
+    return;
+  }
+  const summary = violations.map(v => `  - ${v.message}`).join('\n');
+
+  throw new Error(`Hierarchy invariant violated at ${context}:\n${summary}`);
+};

package/src/styles/main.css

@@ -1306,6 +1306,11 @@
   @apply p-0 m-0 min-h-[1.6em];
 }
 
+/* List items inside table cells use tight 2px top/bottom spacing */
+[data-blok-table-cell-blocks] [data-blok-tool="list"] {
+  @apply py-0 mt-[2px] mb-[2px];
+}
+
 /* ─── Cell content placement ──────────────────────────────────── */
 
 [data-blok-cell-placement="top-center"] {

package/src/tools/callout/constants.ts

@@ -29,4 +29,3 @@ export const WRAPPER_STYLES = 'rounded-xl pl-8 pr-4 py-[5px] my-1 flex items-sta
 // h-[38px] = py-[7px]×2 + 1.5rem×1 = 14+24; explicit height prevents platform-specific emoji font metrics from inflating the button
 export const EMOJI_BUTTON_STYLES = 'text-[1.5rem] leading-[1] cursor-pointer bg-transparent border-0 px-0 py-[7px] h-[38px] flex-shrink-0 select-none';
 export const CHILDREN_STYLES = 'flex-1 min-w-0';
-export const DRAG_ZONE_STYLES = 'absolute left-0 top-0 h-full cursor-grab select-none';

package/src/tools/callout/dom-builder.ts

@@ -6,14 +6,12 @@ import {
   WRAPPER_STYLES,
   EMOJI_BUTTON_STYLES,
   CHILDREN_STYLES,
-  DRAG_ZONE_STYLES,
 } from './constants';
 
 export interface CalloutDOMRefs {
   wrapper: HTMLElement;
   emojiButton: HTMLButtonElement;
   childContainer: HTMLElement;
-  dragZone: HTMLElement;
 }
 
 export interface BuildCalloutDOMOptions {
@@ -53,13 +51,5 @@ export function buildCalloutDOM(options: BuildCalloutDOMOptions): CalloutDOMRefs
   wrapper.appendChild(emojiButton);
   wrapper.appendChild(childContainer);
 
-  // Drag zone — covers left padding area (x=[0,16px]) for drag handle,
-  // sits behind emoji button so emoji clicks pass through
-  const dragZone = document.createElement('span');
-  dragZone.className = DRAG_ZONE_STYLES;
-  dragZone.style.width = '32px'; // matches pl-8 left padding
-  dragZone.setAttribute('data-callout-drag-zone', '');
-  wrapper.prepend(dragZone);
-
-  return { wrapper, emojiButton, childContainer, dragZone };
+  return { wrapper, emojiButton, childContainer };
 }

package/src/tools/callout/index.ts

@@ -66,7 +66,6 @@ export class CalloutTool implements BlockTool {
   private _dom: CalloutDOMRefs | null = null;
   private _emojiPicker: EmojiPicker | null = null;
   private _colorPicker: ColorPickerHandle | null = null;
-  private _dragZone: HTMLElement | null = null;
   private blockId?: string;
 
   constructor({ data, api, readOnly, block }: BlockToolConstructorOptions<CalloutData, CalloutConfig>) {
@@ -121,7 +120,6 @@ export class CalloutTool implements BlockTool {
     });
 
     this._dom = dom;
-    this._dragZone = dom.dragZone;
     this.applyColors();
 
     if (!this.readOnly) {
@@ -262,10 +260,6 @@ export class CalloutTool implements BlockTool {
     }
   }
 
-  public get dragZone(): HTMLElement | null {
-    return this._dragZone;
-  }
-
   private syncPickerActiveColors(): void {
     if (this._colorPicker === null) {
       return;

package/src/tools/header/index.ts

@@ -23,7 +23,7 @@ import { PLACEHOLDER_CLASSES, setupPlaceholder } from '../../components/utils/pl
 import { twMerge } from '../../components/utils/tw';
 import { BODY_PLACEHOLDER_STYLES, TOGGLE_ATTR } from '../toggle/constants';
 import { buildArrow } from '../toggle/dom-builder';
-import { updateArrowState, updateBodyPlaceholderVisibility, updateChildrenVisibility } from '../toggle/toggle-lifecycle';
+import { updateArrowState, updateBodyPlaceholderVisibility, updateChildrenVisibility, updateToggleEmptyState } from '../toggle/toggle-lifecycle';
 import { handleHeaderToggleEnter, handleHeaderToggleBackspace } from './header-toggle-keyboard';
 
 /**
@@ -764,6 +764,7 @@ export class Header implements BlockTool {
    */
   private buildWrapper(): HTMLElement {
     const wrapper = document.createElement('div');
+    wrapper.setAttribute(TOGGLE_ATTR.toggleEmpty, 'true');
 
     // Inner row: positioning context for the arrow (only heading height, not children).
     const headerRow = document.createElement('div');
@@ -799,12 +800,21 @@ export class Header implements BlockTool {
     // Block DOM mutations inside the children container from triggering the header tool's
     // didMutated → syncBlockDataToYjs path (same rationale as the toggle list tool).
     childContainer.setAttribute('data-blok-mutation-free', 'true');
+    /**
+     * Listen for typing inside child blocks so the empty-state attribute
+     * (and the grayish arrow it drives) tracks what the user types in real time.
+     */
+    childContainer.addEventListener('input', this.handleChildContainerInput);
     this._childContainerElement = childContainer;
     wrapper.appendChild(childContainer);
 
     return wrapper;
   }
 
+  private handleChildContainerInput = (): void => {
+    updateToggleEmptyState(this._wrapper, this._childContainerElement);
+  };
+
   /**
    * Wrap the heading element in a new wrapper div containing the toggle arrow,
    * replacing the heading's current position in the DOM.
@@ -814,6 +824,7 @@ export class Header implements BlockTool {
     const parent = this._element.parentNode;
 
     this._wrapper = document.createElement('div');
+    this._wrapper.setAttribute(TOGGLE_ATTR.toggleEmpty, 'true');
 
     // Inner row: positioning context for the arrow (only heading height, not children).
     const headerRow = document.createElement('div');
@@ -916,6 +927,8 @@ export class Header implements BlockTool {
       this._isOpen,
       this.readOnly
     );
+
+    updateToggleEmptyState(this._wrapper, this._childContainerElement);
   }
 
   /**

package/src/tools/toggle/constants.ts

@@ -43,7 +43,7 @@ export const TOGGLE_WRAPPER_STYLES = 'flex items-center';
 /**
  * Styles for the toggle arrow button
  */
-export const ARROW_STYLES = 'flex-shrink-0 p-[8px] flex items-center justify-center cursor-pointer select-none rounded can-hover:hover:bg-item-hover-bg transition-colors duration-200 ease-in-out focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:outline-none';
+export const ARROW_STYLES = 'flex-shrink-0 p-[8px] flex items-center justify-center cursor-pointer select-none rounded can-hover:hover:bg-item-hover-bg transition-colors duration-200 ease-in-out focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:outline-none in-data-[blok-toggle-empty=true]:text-gray-text';
 
 /**
  * SVG icon for the toggle arrow
@@ -77,4 +77,5 @@ export const TOGGLE_ATTR = {
   toggleContent: 'data-blok-toggle-content',
   toggleBodyPlaceholder: 'data-blok-toggle-body-placeholder',
   toggleChildren: 'data-blok-toggle-children',
+  toggleEmpty: 'data-blok-toggle-empty',
 } as const;

package/src/tools/toggle/dom-builder.ts

@@ -73,6 +73,13 @@ export const buildToggleItem = (context: ToggleDOMBuilderContext): ToggleBuildRe
   wrapper.className = BASE_STYLES;
   wrapper.setAttribute(DATA_ATTR.tool, TOOL_NAME);
   wrapper.setAttribute(TOGGLE_ATTR.toggleOpen, String(isOpen));
+  /**
+   * Empty state default: assume no children until the tool syncs real state
+   * via updateToggleEmptyState() in its lifecycle methods. This drives the
+   * grayish arrow styling applied through the in-data-[blok-toggle-empty=true]
+   * Tailwind variant on ARROW_STYLES.
+   */
+  wrapper.setAttribute(TOGGLE_ATTR.toggleEmpty, 'true');
 
   const headerRow = document.createElement('div');
   headerRow.className = TOGGLE_WRAPPER_STYLES;

package/src/tools/toggle/index.ts

@@ -27,7 +27,7 @@ import {
 import { clean } from '../../components/utils/sanitizer';
 import { ARIA_LABEL_COLLAPSE_KEY, ARIA_LABEL_EXPAND_KEY, BODY_PLACEHOLDER_KEY, PLACEHOLDER_KEY, TOOL_NAME } from './constants';
 import { IconToggleList } from '../../components/icons';
-import { renderToggleItem, updateArrowState, updateChildrenVisibility, updateBodyPlaceholderVisibility } from './toggle-lifecycle';
+import { renderToggleItem, updateArrowState, updateChildrenVisibility, updateBodyPlaceholderVisibility, updateToggleEmptyState } from './toggle-lifecycle';
 import { handleToggleEnter, handleToggleBackspace } from './toggle-keyboard';
 import type { ToggleItemData, ToggleItemConfig } from './types';
 
@@ -127,9 +127,20 @@ export class ToggleItem implements BlockTool {
     this._bodyPlaceholderElement = result.bodyPlaceholderElement;
     this._childContainerElement = result.childContainerElement;
 
+    /**
+     * Listen for input events from child blocks so the empty-state attribute
+     * (and the grayish arrow it drives) tracks what the user is typing in
+     * real time.
+     */
+    this._childContainerElement.addEventListener('input', this.handleChildContainerInput);
+
     return this._element;
   }
 
+  private handleChildContainerInput = (): void => {
+    updateToggleEmptyState(this._element, this._childContainerElement);
+  };
+
   public rendered(): void {
     this.updateChildrenVisibility();
     this.updateBodyPlaceholderVisibility();
@@ -322,6 +333,8 @@ export class ToggleItem implements BlockTool {
       this._isOpen,
       this.readOnly
     );
+
+    updateToggleEmptyState(this._element, this._childContainerElement);
   }
 
   private handleBodyPlaceholderClick(): void {

package/src/tools/toggle/toggle-lifecycle.ts

@@ -13,6 +13,30 @@ import { TOGGLE_ATTR } from './constants';
 import { buildToggleItem } from './dom-builder';
 import type { ToggleDOMBuilderContext } from './dom-builder';
 
+/**
+ * Sync the wrapper's data-blok-toggle-empty attribute to reflect whether the
+ * toggle's body has any visible text. Reads `textContent` off the child
+ * container directly so the state updates live as the user types (or deletes).
+ * The attribute drives the grayish arrow styling via the
+ * in-data-[blok-toggle-empty=true] Tailwind variant on ARROW_STYLES.
+ *
+ * @param wrapper - The toggle wrapper element that receives the attribute
+ * @param childContainer - The element that hosts the child block holders
+ */
+export const updateToggleEmptyState = (
+  wrapper: HTMLElement | null,
+  childContainer: HTMLElement | null
+): void => {
+  if (wrapper === null) {
+    return;
+  }
+
+  const text = childContainer?.textContent ?? '';
+  const isEmpty = text.trim() === '';
+
+  wrapper.setAttribute(TOGGLE_ATTR.toggleEmpty, String(isEmpty));
+};
+
 /**
  * Context for rendering a toggle item
  */