@jackuait/blok 0.6.0-beta.9 → 0.7.0-beta.1

package/src/tools/index.ts

@@ -4,7 +4,7 @@
  *
  * @example
  * // Import specific tools
- * import { Paragraph, Header, List, Bold, Italic, Link } from '@jackuait/blok/tools';
+ * import { Paragraph, Header, List, Toggle, Bold, Italic, Link, Marker } from '@jackuait/blok/tools';
  *
  * // Use in Blok configuration (flat config style)
  * new Blok({
@@ -24,12 +24,14 @@ export { Paragraph } from './paragraph';
 export { Header } from './header';
 export { ListItem as List } from './list';
 export { Table } from './table';
+export { ToggleItem as Toggle } from './toggle';
 
 // Inline tools
 export { BoldInlineTool as Bold } from '../components/inline-tools/inline-tool-bold';
 export { ItalicInlineTool as Italic } from '../components/inline-tools/inline-tool-italic';
 export { LinkInlineTool as Link } from '../components/inline-tools/inline-tool-link';
 export { ConvertInlineTool as Convert } from '../components/inline-tools/inline-tool-convert';
+export { MarkerInlineTool as Marker } from '../components/inline-tools/inline-tool-marker';
 
 // Default tools configuration for convenience
 // Note: inlineToolbar defaults to true, so it doesn't need to be specified
@@ -38,10 +40,12 @@ export const defaultBlockTools = {
   header: {},
   list: {},
   table: {},
+  toggle: {},
 } as const;
 
 export const defaultInlineTools = {
   bold: {},
   italic: {},
   link: {},
+  marker: {},
 } as const;

package/src/tools/list/caret-manager.ts

@@ -7,8 +7,12 @@
 import type { API } from '../../../types';
 
 /**
- * Sets caret to the content element of a block after ensuring DOM is ready.
- * Uses requestAnimationFrame to wait for the browser to process DOM updates.
+ * Sets caret to the content element of a block.
+ * Operates synchronously so subsequent keystrokes land in the correct block
+ * (deferring via requestAnimationFrame causes a race where characters typed
+ * between the block split and the next animation frame go to the wrong element).
+ * Falls back to requestAnimationFrame only when the content element is not yet
+ * available (e.g. async rendering).
  *
  * @param api - The API instance
  * @param block - BlockAPI to set caret to
@@ -19,8 +23,7 @@ export const setCaretToBlockContent = (
   block: ReturnType<API['blocks']['insert']>,
   position: 'start' | 'end' = 'end'
 ): void => {
-  // Use requestAnimationFrame to ensure DOM has been updated
-  requestAnimationFrame(() => {
+  const applyFocus = (deferred: boolean): void => {
     const holder = block.holder;
     if (!holder) return;
 
@@ -29,8 +32,10 @@ export const setCaretToBlockContent = (
     if (!(contentEl instanceof HTMLElement)) {
       // Fallback to setToBlock if no content element found
       api.caret.setToBlock(block, position);
-      // Update the caret "after" position for undo/redo since we're in requestAnimationFrame
-      api.caret.updateLastCaretAfterPosition();
+
+      if (deferred) {
+        api.caret.updateLastCaretAfterPosition();
+      }
 
       return;
     }
@@ -55,8 +60,21 @@ export const setCaretToBlockContent = (
     selection.removeAllRanges();
     selection.addRange(range);
 
-    // Update the caret "after" position for undo/redo since we moved the caret
-    // asynchronously via requestAnimationFrame after the Yjs transaction committed
-    api.caret.updateLastCaretAfterPosition();
-  });
+    if (deferred) {
+      // Update the caret "after" position for undo/redo since we moved the caret
+      // asynchronously via requestAnimationFrame after the Yjs transaction committed
+      api.caret.updateLastCaretAfterPosition();
+    }
+  };
+
+  // Try synchronous focus first — the block is already in the DOM after insert()
+  const holder = block.holder;
+  const contentEl = holder?.querySelector('[contenteditable="true"]');
+
+  if (contentEl instanceof HTMLElement) {
+    applyFocus(false);
+  } else {
+    // Content element not available yet — fall back to next frame
+    requestAnimationFrame(() => applyFocus(true));
+  }
 }

package/src/tools/list/constants.ts

@@ -12,12 +12,12 @@ export const INDENT_PER_LEVEL = 24;
  *
  * Matches paragraph spacing: py-[3px] from blok-block + mt-[2px] mb-px
  */
-export const BASE_STYLES = 'outline-none py-[3px] mt-[2px] mb-px';
+export const BASE_STYLES = 'outline-hidden py-[3px] mt-[2px] mb-px';
 
 /**
  * Styles for standard list items (unordered, ordered)
  */
-export const ITEM_STYLES = 'outline-none pl-0.5 leading-[1.6em]';
+export const ITEM_STYLES = 'outline-hidden pl-0.5 leading-[1.6em]';
 
 /**
  * Styles for checklist items

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

@@ -176,7 +176,7 @@ export const buildStandardContent = (context: DOMBuilderContext): HTMLElement =>
 
   // Create content container
   const contentContainer = document.createElement('div');
-  contentContainer.className = twMerge('flex-1 min-w-0 outline-none', ...PLACEHOLDER_CLASSES);
+  contentContainer.className = twMerge('flex-1 min-w-0 outline-hidden', ...PLACEHOLDER_CLASSES);
   contentContainer.setAttribute('data-blok-testid', LIST_TEST_IDS.contentContainer);
   contentContainer.contentEditable = context.readOnly ? 'false' : 'true';
   contentContainer.innerHTML = data.text;
@@ -224,7 +224,7 @@ export const buildChecklistContent = (context: DOMBuilderContext): HTMLElement =
 
   const content = document.createElement('div');
   content.className = twMerge(
-    'flex-1 outline-none leading-[1.6em]',
+    'flex-1 outline-hidden leading-[1.6em]',
     data.checked ? 'line-through opacity-60' : '',
     ...PLACEHOLDER_CLASSES
   );
@@ -251,7 +251,7 @@ export const buildChecklistContent = (context: DOMBuilderContext): HTMLElement =
  */
 export const createMarker = (style: ListItemStyle, depth: number): HTMLElement => {
   const marker = document.createElement('span');
-  marker.className = 'flex-shrink-0 select-none';
+  marker.className = 'shrink-0 select-none';
   marker.setAttribute('aria-hidden', 'true');
   marker.contentEditable = 'false';
 

package/src/tools/list/static-configs.ts

@@ -21,7 +21,6 @@ export const getListSanitizeConfig = (): ToolSanitizerConfig => ({
     },
     b: true,
     i: true,
-    mark: true,
   },
 });
 

package/src/tools/paragraph/index.ts

@@ -19,7 +19,7 @@ import type {
 import { DATA_ATTR } from '../../components/constants';
 import { IconText } from '../../components/icons';
 import { stripFakeBackgroundElements } from '../../components/utils';
-import { PLACEHOLDER_FOCUS_ONLY_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
+import { PLACEHOLDER_EMPTY_EDITOR_CLASSES, PLACEHOLDER_FOCUS_ONLY_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
 import { twMerge } from '../../components/utils/tw';
 
 /**
@@ -200,7 +200,7 @@ export class Paragraph implements BlockTool {
    */
   private static readonly WRAPPER_CLASSES = [
     'leading-[1.6em]',
-    'outline-none',
+    'outline-hidden',
     'mt-[2px]',
     'mb-px',
     '[&>p:first-of-type]:mt-0',
@@ -239,7 +239,8 @@ export class Paragraph implements BlockTool {
     div.className = twMerge(
       this.api.styles.block,
       Paragraph.WRAPPER_CLASSES,
-      PLACEHOLDER_FOCUS_ONLY_CLASSES
+      PLACEHOLDER_FOCUS_ONLY_CLASSES,
+      PLACEHOLDER_EMPTY_EDITOR_CLASSES
     );
     div.setAttribute(DATA_ATTR.tool, 'paragraph');
     div.contentEditable = 'false';
@@ -255,14 +256,14 @@ export class Paragraph implements BlockTool {
 
     if (this._data.text) {
       div.innerHTML = this._data.text;
+    } else if (this.readOnly) {
+      div.innerHTML = '<br>';
     }
 
     if (!this.readOnly) {
       div.contentEditable = 'true';
       div.addEventListener('keyup', this.onKeyUp);
       setupPlaceholder(div, this.api.i18n.t(this._placeholder), 'data-blok-placeholder-active');
-    } else {
-      div.setAttribute('data-blok-placeholder-active', this.api.i18n.t(this._placeholder));
     }
 
     return div;
@@ -377,6 +378,9 @@ export class Paragraph implements BlockTool {
           src: true,
           style: true,
         },
+        p: true,
+        ul: true,
+        li: true,
       },
     };
   }

package/src/tools/table/core/table-commands.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed table commands — the sole input vocabulary for table mutations.
+ * Every mutation must be expressible as one of these commands.
+ */
+import type { TableData } from '../types';
+
+export interface InsertRowCommand {
+  readonly type: 'insert-row';
+  /** Row index to insert at */
+  readonly index: number;
+}
+
+export interface DeleteRowCommand {
+  readonly type: 'delete-row';
+  readonly index: number;
+}
+
+export interface MoveRowCommand {
+  readonly type: 'move-row';
+  readonly fromIndex: number;
+  readonly toIndex: number;
+}
+
+export interface InsertColumnCommand {
+  readonly type: 'insert-column';
+  readonly index: number;
+  readonly width?: number;
+}
+
+export interface DeleteColumnCommand {
+  readonly type: 'delete-column';
+  readonly index: number;
+}
+
+export interface MoveColumnCommand {
+  readonly type: 'move-column';
+  readonly fromIndex: number;
+  readonly toIndex: number;
+}
+
+export interface ToggleHeadingCommand {
+  readonly type: 'toggle-heading';
+}
+
+export interface ToggleHeadingColumnCommand {
+  readonly type: 'toggle-heading-column';
+}
+
+export interface SetStretchedCommand {
+  readonly type: 'set-stretched';
+  readonly value: boolean;
+}
+
+export interface AddBlockToCellCommand {
+  readonly type: 'add-block-to-cell';
+  readonly row: number;
+  readonly col: number;
+  readonly blockId: string;
+}
+
+export interface RemoveBlockFromCellCommand {
+  readonly type: 'remove-block-from-cell';
+  readonly row: number;
+  readonly col: number;
+  readonly blockId: string;
+}
+
+export interface SetCellBlocksCommand {
+  readonly type: 'set-cell-blocks';
+  readonly row: number;
+  readonly col: number;
+  readonly blockIds: readonly string[];
+}
+
+export interface SetColWidthsCommand {
+  readonly type: 'set-col-widths';
+  readonly widths: readonly number[] | undefined;
+}
+
+export interface ReplaceAllCommand {
+  readonly type: 'replace-all';
+  readonly data: TableData;
+}
+
+export type TableCommand =
+  | InsertRowCommand
+  | DeleteRowCommand
+  | MoveRowCommand
+  | InsertColumnCommand
+  | DeleteColumnCommand
+  | MoveColumnCommand
+  | ToggleHeadingCommand
+  | ToggleHeadingColumnCommand
+  | SetStretchedCommand
+  | AddBlockToCellCommand
+  | RemoveBlockFromCellCommand
+  | SetCellBlocksCommand
+  | SetColWidthsCommand
+  | ReplaceAllCommand;

package/src/tools/table/core/table-controller.ts

@@ -0,0 +1,231 @@
+import type { TableModel } from '../table-model';
+import type { TableData } from '../types';
+import type { TableCommand } from './table-commands';
+import type { TableDomainEvent } from './table-events';
+
+/**
+ * Listener callback for domain events emitted by the controller.
+ */
+export type TableEventListener = (event: TableDomainEvent) => void;
+
+/**
+ * Central command executor for table mutations.
+ *
+ * All model mutations flow through `execute()`, which:
+ * 1. Applies the command to the model
+ * 2. Emits a corresponding domain event
+ *
+ * This is the sole mutation entrypoint — no direct model mutation
+ * should happen outside of the controller in the final architecture.
+ */
+export class TableController {
+  private readonly model: TableModel;
+  private readonly listener: TableEventListener | undefined;
+
+  constructor(model: TableModel, listener?: TableEventListener) {
+    this.model = model;
+    this.listener = listener;
+  }
+
+  /**
+   * Execute a typed command against the model and emit the resulting event.
+   */
+  execute(command: TableCommand): void {
+    const event = this.applyCommand(command);
+
+    if (event !== null && this.listener) {
+      this.listener(event);
+    }
+  }
+
+  /**
+   * Apply a command to the model and return the domain event to emit.
+   * Returns null if the command was a no-op (e.g., out-of-bounds).
+   */
+  private applyCommand(command: TableCommand): TableDomainEvent | null {
+    switch (command.type) {
+      case 'insert-row':
+        return this.handleInsertRow(command.index);
+
+      case 'delete-row':
+        return this.handleDeleteRow(command.index);
+
+      case 'move-row':
+        return this.handleMoveRow(command.fromIndex, command.toIndex);
+
+      case 'insert-column':
+        return this.handleInsertColumn(command.index, command.width);
+
+      case 'delete-column':
+        return this.handleDeleteColumn(command.index);
+
+      case 'move-column':
+        return this.handleMoveColumn(command.fromIndex, command.toIndex);
+
+      case 'toggle-heading':
+        return this.handleToggleHeading();
+
+      case 'toggle-heading-column':
+        return this.handleToggleHeadingColumn();
+
+      case 'set-stretched':
+        return this.handleSetStretched(command.value);
+
+      case 'add-block-to-cell':
+        return this.handleAddBlockToCell(command.row, command.col, command.blockId);
+
+      case 'remove-block-from-cell':
+        return this.handleRemoveBlockFromCell(command.row, command.col, command.blockId);
+
+      case 'set-cell-blocks':
+        return this.handleSetCellBlocks(command.row, command.col, [...command.blockIds]);
+
+      case 'set-col-widths':
+        return this.handleSetColWidths(command.widths ? [...command.widths] : undefined);
+
+      case 'replace-all':
+        return this.handleReplaceAll(command.data);
+    }
+  }
+
+  // ─── Command handlers ──────────────────────────────────────────
+
+  private handleInsertRow(index: number): TableDomainEvent {
+    const result = this.model.addRow(index);
+
+    return {
+      type: 'row-inserted',
+      index: result.index,
+      cellsToPopulate: result.cellsToPopulate,
+    };
+  }
+
+  private handleDeleteRow(index: number): TableDomainEvent {
+    const result = this.model.deleteRow(index);
+
+    return {
+      type: 'row-deleted',
+      index: result.index,
+      blocksToDelete: result.blocksToDelete,
+    };
+  }
+
+  private handleMoveRow(fromIndex: number, toIndex: number): TableDomainEvent {
+    this.model.moveRow(fromIndex, toIndex);
+
+    return {
+      type: 'row-moved',
+      fromIndex,
+      toIndex,
+    };
+  }
+
+  private handleInsertColumn(index: number, width?: number): TableDomainEvent {
+    const result = this.model.addColumn(index, width);
+
+    return {
+      type: 'column-inserted',
+      index: result.index,
+      cellsToPopulate: result.cellsToPopulate,
+    };
+  }
+
+  private handleDeleteColumn(index: number): TableDomainEvent {
+    const result = this.model.deleteColumn(index);
+
+    return {
+      type: 'column-deleted',
+      index: result.index,
+      blocksToDelete: result.blocksToDelete,
+    };
+  }
+
+  private handleMoveColumn(fromIndex: number, toIndex: number): TableDomainEvent {
+    this.model.moveColumn(fromIndex, toIndex);
+
+    return {
+      type: 'column-moved',
+      fromIndex,
+      toIndex,
+    };
+  }
+
+  private handleToggleHeading(): TableDomainEvent {
+    const newValue = !this.model.withHeadings;
+
+    this.model.setWithHeadings(newValue);
+
+    return {
+      type: 'heading-toggled',
+      withHeadings: newValue,
+    };
+  }
+
+  private handleToggleHeadingColumn(): TableDomainEvent {
+    const newValue = !this.model.withHeadingColumn;
+
+    this.model.setWithHeadingColumn(newValue);
+
+    return {
+      type: 'heading-column-toggled',
+      withHeadingColumn: newValue,
+    };
+  }
+
+  private handleSetStretched(value: boolean): TableDomainEvent {
+    this.model.setStretched(value);
+
+    return {
+      type: 'stretched-changed',
+      stretched: value,
+    };
+  }
+
+  private handleAddBlockToCell(row: number, col: number, blockId: string): TableDomainEvent {
+    this.model.addBlockToCell(row, col, blockId);
+
+    return {
+      type: 'block-added-to-cell',
+      row,
+      col,
+      blockId,
+    };
+  }
+
+  private handleRemoveBlockFromCell(row: number, col: number, blockId: string): TableDomainEvent {
+    this.model.removeBlockFromCell(row, col, blockId);
+
+    return {
+      type: 'block-removed-from-cell',
+      row,
+      col,
+      blockId,
+    };
+  }
+
+  private handleSetCellBlocks(row: number, col: number, blockIds: string[]): TableDomainEvent {
+    this.model.setCellBlocks(row, col, blockIds);
+
+    return {
+      type: 'cell-blocks-set',
+      row,
+      col,
+      blockIds,
+    };
+  }
+
+  private handleSetColWidths(widths: number[] | undefined): TableDomainEvent {
+    this.model.setColWidths(widths);
+
+    return {
+      type: 'col-widths-changed',
+      widths,
+    };
+  }
+
+  private handleReplaceAll(data: TableData): TableDomainEvent {
+    this.model.replaceAll(data);
+
+    return { type: 'model-replaced' };
+  }
+}

package/src/tools/table/core/table-events.ts

@@ -0,0 +1,102 @@
+/**
+ * Domain events emitted after successful table mutations.
+ * Payloads contain ONLY serializable data (IDs, indices, counts).
+ * No HTMLElement references — ever.
+ */
+
+export interface RowInsertedEvent {
+  readonly type: 'row-inserted';
+  readonly index: number;
+  readonly cellsToPopulate: number;
+}
+
+export interface RowDeletedEvent {
+  readonly type: 'row-deleted';
+  readonly index: number;
+  readonly blocksToDelete: readonly string[];
+}
+
+export interface RowMovedEvent {
+  readonly type: 'row-moved';
+  readonly fromIndex: number;
+  readonly toIndex: number;
+}
+
+export interface ColumnInsertedEvent {
+  readonly type: 'column-inserted';
+  readonly index: number;
+  readonly cellsToPopulate: ReadonlyArray<{ row: number; col: number }>;
+}
+
+export interface ColumnDeletedEvent {
+  readonly type: 'column-deleted';
+  readonly index: number;
+  readonly blocksToDelete: readonly string[];
+}
+
+export interface ColumnMovedEvent {
+  readonly type: 'column-moved';
+  readonly fromIndex: number;
+  readonly toIndex: number;
+}
+
+export interface HeadingToggledEvent {
+  readonly type: 'heading-toggled';
+  readonly withHeadings: boolean;
+}
+
+export interface HeadingColumnToggledEvent {
+  readonly type: 'heading-column-toggled';
+  readonly withHeadingColumn: boolean;
+}
+
+export interface StretchedChangedEvent {
+  readonly type: 'stretched-changed';
+  readonly stretched: boolean;
+}
+
+export interface BlockAddedToCellEvent {
+  readonly type: 'block-added-to-cell';
+  readonly row: number;
+  readonly col: number;
+  readonly blockId: string;
+}
+
+export interface BlockRemovedFromCellEvent {
+  readonly type: 'block-removed-from-cell';
+  readonly row: number;
+  readonly col: number;
+  readonly blockId: string;
+}
+
+export interface CellBlocksSetEvent {
+  readonly type: 'cell-blocks-set';
+  readonly row: number;
+  readonly col: number;
+  readonly blockIds: readonly string[];
+}
+
+export interface ColWidthsChangedEvent {
+  readonly type: 'col-widths-changed';
+  readonly widths: readonly number[] | undefined;
+}
+
+export interface ModelReplacedEvent {
+  readonly type: 'model-replaced';
+}
+
+export type TableDomainEvent =
+  | RowInsertedEvent
+  | RowDeletedEvent
+  | RowMovedEvent
+  | ColumnInsertedEvent
+  | ColumnDeletedEvent
+  | ColumnMovedEvent
+  | HeadingToggledEvent
+  | HeadingColumnToggledEvent
+  | StretchedChangedEvent
+  | BlockAddedToCellEvent
+  | BlockRemovedFromCellEvent
+  | CellBlocksSetEvent
+  | ColWidthsChangedEvent
+  | ModelReplacedEvent;