@jackuait/blok 0.4.1-beta.17 → 0.4.1-beta.19

package/dist/chunks/{i18next-loader-CtUJZQir.mjs → i18next-loader-CI8T9PDi.mjs}

@@ -1,4 +1,4 @@
-import { e as i } from "./blok-BmQiBq7w.mjs";
+import { e as i } from "./blok-zaWxnlMM.mjs";
 const l = async (e, r) => {
   const n = (await import("./i18next-CugVlwWp.mjs")).default.createInstance(), s = {
     lng: e,

package/dist/chunks/{index-CvHTp5IA.mjs → index-D9haze7z.mjs}

@@ -1,4 +1,4 @@
-import { t as f, q as i } from "./inline-tool-convert-f0-Y0Vcm.mjs";
+import { t as f, q as i } from "./inline-tool-convert-CoQJYHI_.mjs";
 const a = {
   wrapper: i(
     "fixed z-[2] bottom-5 left-5",

package/dist/chunks/{inline-tool-convert-f0-Y0Vcm.mjs → inline-tool-convert-CoQJYHI_.mjs}

@@ -18,7 +18,7 @@ let nt = (o = 21) => {
   return t;
 };
 var ot = /* @__PURE__ */ ((o) => (o.VERBOSE = "VERBOSE", o.INFO = "INFO", o.WARN = "WARN", o.ERROR = "ERROR", o))(ot || {});
-const rt = () => "0.4.1-beta.17", Ct = {
+const rt = () => "0.4.1-beta.19", Ct = {
   BACKSPACE: 8,
   TAB: 9,
   ENTER: 13,

package/dist/full.mjs

@@ -10,10 +10,10 @@ var e = (a, l, o) => l in a ? n(a, l, { enumerable: !0, configurable: !0, writab
       d.call(l, o) && e(a, o, l[o]);
   return a;
 }, r = (a, l) => t(a, c(l));
-import { B as v, v as A } from "./chunks/blok-BmQiBq7w.mjs";
+import { B as v, v as A } from "./chunks/blok-zaWxnlMM.mjs";
 import { List as p, Header as f, Paragraph as I, Link as k, Italic as u, Bold as B } from "./tools.mjs";
 import { defaultBlockTools as H, defaultInlineTools as P } from "./tools.mjs";
-import { D as _ } from "./chunks/inline-tool-convert-f0-Y0Vcm.mjs";
+import { D as _ } from "./chunks/inline-tool-convert-CoQJYHI_.mjs";
 const m = {
   paragraph: {
     class: I,

package/dist/tools.mjs

@@ -10,8 +10,8 @@ var U = (f, t, e) => t in f ? nt(f, t, { enumerable: !0, configurable: !0, writa
       it.call(t, e) && U(f, e, t[e]);
   return f;
 }, P = (f, t) => rt(f, st(t));
-import { t as x, D as m, a9 as et, aa as at, ab as lt, A as ct, ac as dt, ad as ut, ae as ht, af as ft, ag as pt, ah as mt, ai as G, aj as j, ak as $, f as A, al as gt, am as Et, S as H, P as Tt, an as Ct, l as At, J as yt } from "./chunks/inline-tool-convert-f0-Y0Vcm.mjs";
-import { a0 as Dt } from "./chunks/inline-tool-convert-f0-Y0Vcm.mjs";
+import { t as x, D as m, a9 as et, aa as at, ab as lt, A as ct, ac as dt, ad as ut, ae as ht, af as ft, ag as pt, ah as mt, ai as G, aj as j, ak as $, f as A, al as gt, am as Et, S as H, P as Tt, an as Ct, l as At, J as yt } from "./chunks/inline-tool-convert-CoQJYHI_.mjs";
+import { a0 as Dt } from "./chunks/inline-tool-convert-CoQJYHI_.mjs";
 const W = [
   "empty:before:pointer-events-none",
   "empty:before:text-gray-text",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackuait/blok",
-  "version": "0.4.1-beta.17",
+  "version": "0.4.1-beta.19",
   "description": "Blok — headless, highly extensible rich text editor built for developers who need to implement a block-based editing experience (similar to Notion) without building it from scratch",
   "module": "dist/blok.mjs",
   "types": "./types/index.d.ts",

package/src/components/block/index.ts

@@ -79,6 +79,12 @@ interface BlockConstructorOptions {
    * References blocks that are children of this block.
    */
   contentIds?: string[];
+
+  /**
+   * Slot index within parent container (e.g., which column in a columns block).
+   * Used to organize children into specific slots for container blocks.
+   */
+  slot?: number;
 }
 
 /**
@@ -142,6 +148,12 @@ export class Block extends EventsDispatcher<BlockEvents> {
    */
   public contentIds: string[];
 
+  /**
+   * Slot index within parent container (e.g., which column in a columns block).
+   * Null if this block is not assigned to a specific slot.
+   */
+  public slot: number | null;
+
   /**
    * Block Tool`s name
    */
@@ -259,6 +271,7 @@ export class Block extends EventsDispatcher<BlockEvents> {
    * @param options.readOnly - Read-Only flag
    * @param [options.parentId] - parent block id for hierarchical structure
    * @param [options.contentIds] - array of child block ids
+   * @param [options.slot] - slot index within parent container
    * @param [eventBus] - Blok common event bus. Allows to subscribe on some Blok events. Could be omitted when "virtual" Block is created. See BlocksAPI@composeBlockData.
    */
   constructor({
@@ -269,6 +282,7 @@ export class Block extends EventsDispatcher<BlockEvents> {
     tunesData,
     parentId,
     contentIds,
+    slot,
   }: BlockConstructorOptions, eventBus?: EventsDispatcher<BlokEventMap>) {
     super();
     this.ready = new Promise((resolve) => {
@@ -278,6 +292,7 @@ export class Block extends EventsDispatcher<BlockEvents> {
     this.id = id;
     this.parentId = parentId ?? null;
     this.contentIds = contentIds ?? [];
+    this.slot = slot ?? null;
     this.settings = tool.settings;
     this.config = this.settings;
     this.blokEventBus = eventBus || null;

package/src/components/modules/api/blocks.ts

@@ -29,6 +29,8 @@ export class BlocksAPI extends Module {
       getBlockIndex: (id: string): number | undefined => this.getBlockIndex(id),
       getBlocksCount: (): number => this.getBlocksCount(),
       getBlockByElement: (element: HTMLElement) => this.getBlockByElement(element),
+      getChildren: (parentId: string): BlockAPIInterface[] => this.getChildren(parentId),
+      getChildrenInSlot: (parentId: string, slot: number): BlockAPIInterface[] => this.getChildrenInSlot(parentId, slot),
       insert: this.insert,
       insertMany: this.insertMany,
       update: this.update,
@@ -118,6 +120,31 @@ export class BlocksAPI extends Module {
     return new BlockAPI(block);
   }
 
+  /**
+   * Returns all child blocks of a parent container block
+   * @param parentId - id of the parent block
+   */
+  public getChildren(parentId: string): BlockAPIInterface[] {
+    const children = this.Blok.BlockManager.blocks.filter(
+      (block) => block.parentId === parentId
+    );
+
+    return children.map((block) => new BlockAPI(block));
+  }
+
+  /**
+   * Returns child blocks of a parent container block in a specific slot
+   * @param parentId - id of the parent block
+   * @param slot - slot index (e.g., column index for columns block)
+   */
+  public getChildrenInSlot(parentId: string, slot: number): BlockAPIInterface[] {
+    const children = this.Blok.BlockManager.blocks.filter(
+      (block) => block.parentId === parentId && block.slot === slot
+    );
+
+    return children.map((block) => new BlockAPI(block));
+  }
+
   /**
    * Move block from one index to another
    * @param {number} toIndex - index to move to

package/src/components/modules/blockManager.ts

@@ -235,6 +235,7 @@ export class BlockManager extends Module {
    * @param {BlockToolData} [options.data] - constructor params
    * @param {string} [options.parentId] - parent block id for hierarchical structure
    * @param {string[]} [options.contentIds] - array of child block ids
+   * @param {number} [options.slot] - slot index within parent container
    * @returns {Block}
    */
   public composeBlock({
@@ -244,6 +245,7 @@ export class BlockManager extends Module {
     tunes: tunesData = {},
     parentId,
     contentIds,
+    slot,
   }: {
     tool: string;
     id?: string;
@@ -251,6 +253,7 @@ export class BlockManager extends Module {
     tunes?: {[name: string]: BlockTuneData};
     parentId?: string;
     contentIds?: string[];
+    slot?: number;
   }): Block {
     const readOnly = this.Blok.ReadOnly.isEnabled;
     const tool = this.Blok.Tools.blockTools.get(name);
@@ -268,6 +271,7 @@ export class BlockManager extends Module {
       tunesData,
       parentId,
       contentIds,
+      slot,
     }, this.eventsDispatcher);
 
     if (!readOnly) {

package/src/components/modules/history/index.ts

@@ -0,0 +1,7 @@
+/**
+ * History module utilities
+ * @module History
+ */
+
+export { SmartGrouping } from './smart-grouping';
+export type { ActionType, MutationMetadata, ActionContext } from './types';

package/src/components/modules/history/smart-grouping.ts

@@ -0,0 +1,98 @@
+/**
+ * Smart grouping logic for history checkpoints
+ * @module History/SmartGrouping
+ */
+
+import type { ActionContext, ActionType, MutationMetadata } from './types';
+
+/**
+ * Actions that should create an immediate checkpoint (before the action)
+ */
+const IMMEDIATE_CHECKPOINT_ACTIONS: ActionType[] = [
+  'format',
+  'structural',
+  'paste',
+  'cut',
+];
+
+/**
+ * Determines when to create history checkpoints based on action patterns
+ *
+ * Creates checkpoints when:
+ * - Action type changes (e.g., typing → deleting)
+ * - Block changes
+ * - Immediate actions (format, structural, paste, cut)
+ */
+export class SmartGrouping {
+  /**
+   * Current action context
+   */
+  private currentContext: ActionContext | undefined;
+
+  /**
+   * Determines if a checkpoint should be created before recording this mutation
+   * @param metadata - mutation metadata with action type info
+   * @param blockId - ID of the block being mutated
+   * @returns true if a checkpoint should be created
+   */
+  public shouldCreateCheckpoint(
+    metadata: MutationMetadata,
+    blockId: string
+  ): boolean {
+    const actionType = metadata.actionType ?? 'insert';
+
+    // No current context means this is the first action - don't checkpoint
+    if (!this.currentContext) {
+      return false;
+    }
+
+    // Block changed - create checkpoint
+    if (this.currentContext.blockId !== blockId) {
+      return true;
+    }
+
+    // Action type changed (e.g., typing → deleting) - create checkpoint
+    if (this.currentContext.type !== actionType) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Checks if this action type should trigger an immediate checkpoint
+   * @param actionType - the action type to check
+   * @returns true if this action should create an immediate checkpoint
+   */
+  public isImmediateCheckpoint(actionType: ActionType): boolean {
+    return IMMEDIATE_CHECKPOINT_ACTIONS.includes(actionType);
+  }
+
+  /**
+   * Updates the current action context
+   * @param actionType - the new action type
+   * @param blockId - the block being edited
+   */
+  public updateContext(actionType: ActionType, blockId: string): void {
+    this.currentContext = {
+      type: actionType,
+      blockId,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Gets the current action context
+   * @returns the current context or undefined
+   */
+  public getCurrentContext(): ActionContext | undefined {
+    return this.currentContext;
+  }
+
+  /**
+   * Clears the current action context
+   */
+  public clearContext(): void {
+    this.currentContext = undefined;
+  }
+}

package/src/components/modules/history/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for smart history grouping
+ * @module History/Types
+ */
+
+/**
+ * Action types that can be detected from mutations
+ */
+export type ActionType =
+  | 'insert'       // Typing characters
+  | 'delete-back'  // Backspace deletion
+  | 'delete-fwd'   // Forward delete
+  | 'format'       // Inline formatting (bold, italic, etc.)
+  | 'structural'   // Block-level changes (split, merge)
+  | 'paste'        // Paste operation
+  | 'cut';         // Cut operation
+
+/**
+ * Metadata about a mutation for smart grouping decisions
+ */
+export interface MutationMetadata {
+  /**
+   * Type of action that caused this mutation
+   */
+  actionType?: ActionType;
+
+  /**
+   * Text that was inserted (captured by MutationDetector)
+   */
+  insertedText?: string;
+
+  /**
+   * Text that was deleted (captured by MutationDetector)
+   */
+  deletedText?: string;
+}
+
+/**
+ * Context about the current action sequence
+ */
+export interface ActionContext {
+  /**
+   * The type of action being performed
+   */
+  type: ActionType;
+
+  /**
+   * ID of the block being edited
+   */
+  blockId: string;
+
+  /**
+   * Timestamp when this context started
+   */
+  timestamp: number;
+}

package/src/components/modules/history.ts

@@ -9,6 +9,8 @@ import { BlockChanged, HistoryStateChanged } from '../events';
 import type { BlockMutationEvent } from '../../../types/events/block';
 import { Shortcuts } from '../utils/shortcuts';
 import type { Block } from '../block';
+import { SmartGrouping } from './history/smart-grouping';
+import type { ActionType } from './history/types';
 
 /**
  * Default maximum history stack size
@@ -117,6 +119,21 @@ export class History extends Module {
    */
   private initialStateCaptured = false;
 
+  /**
+   * Smart grouping logic for determining when to create checkpoints
+   */
+  private smartGrouping = new SmartGrouping();
+
+  /**
+   * Current action type being tracked (for detecting action type changes)
+   */
+  private currentActionType: ActionType = 'insert';
+
+  /**
+   * Keydown handler reference for cleanup
+   */
+  private keydownHandler: ((e: KeyboardEvent) => void) | null = null;
+
   /**
    * Maximum number of entries in history stack
    */
@@ -145,6 +162,7 @@ export class History extends Module {
   public async prepare(): Promise<void> {
     this.setupEventListeners();
     this.setupKeyboardShortcuts();
+    this.setupActionTypeTracking();
   }
 
   /**
@@ -310,6 +328,7 @@ export class History extends Module {
     this.undoStack = [];
     this.redoStack = [];
     this.initialStateCaptured = false;
+    this.smartGrouping.clearContext();
     this.emitStateChanged();
   }
 
@@ -433,11 +452,47 @@ export class History extends Module {
     return false;
   }
 
+  /**
+   * Sets up keydown tracking for action type detection
+   */
+  private setupActionTypeTracking(): void {
+    // Wait for UI to be ready
+    setTimeout(() => {
+      const redactor = this.Blok.UI?.nodes?.redactor;
+
+      if (!redactor) {
+        return;
+      }
+
+      this.keydownHandler = (e: KeyboardEvent): void => {
+        // Detect action type from key press
+        if (e.key === 'Backspace') {
+          this.currentActionType = 'delete-back';
+
+          return;
+        }
+
+        if (e.key === 'Delete') {
+          this.currentActionType = 'delete-fwd';
+
+          return;
+        }
+
+        // Single character key (typing)
+        if (e.key.length === 1 && !e.ctrlKey && !e.metaKey) {
+          this.currentActionType = 'insert';
+        }
+      };
+
+      redactor.addEventListener('keydown', this.keydownHandler);
+    }, 0);
+  }
+
   /**
    * Handles block mutation events
-   * Debounces rapid changes and records state snapshots
+   * Uses smart grouping to create checkpoints when action type changes
    */
-  private handleBlockMutation(_event: BlockMutationEvent): void {
+  private handleBlockMutation(event: BlockMutationEvent): void {
     // Mark this instance as active for global shortcuts
     History.activeInstance = this;
 
@@ -453,10 +508,39 @@ export class History extends Module {
       return;
     }
 
-    // Clear existing debounce timeout
-    this.clearDebounce();
+    // Get block ID from event
+    const blockId = event.detail.target.id;
+
+    // Check if we should create a checkpoint before this action
+    const shouldCheckpoint = this.smartGrouping.shouldCreateCheckpoint(
+      { actionType: this.currentActionType },
+      blockId
+    );
+
+    // Check if this is an immediate checkpoint action
+    const isImmediate = this.smartGrouping.isImmediateCheckpoint(this.currentActionType);
+
+    if (shouldCheckpoint || isImmediate) {
+      // Create checkpoint immediately (flush pending debounce)
+      this.clearDebounce();
+      void this.recordState().then(() => {
+        // Update context after recording
+        this.smartGrouping.updateContext(this.currentActionType, blockId);
+        // Start new debounce for continued editing
+        this.startDebounce();
+      });
+    } else {
+      // Update context and debounce normally
+      this.smartGrouping.updateContext(this.currentActionType, blockId);
+      this.clearDebounce();
+      this.startDebounce();
+    }
+  }
 
-    // Debounce to batch rapid changes
+  /**
+   * Starts the debounce timer for recording state
+   */
+  private startDebounce(): void {
     this.debounceTimeout = setTimeout(() => {
       void this.recordState();
     }, this.debounceTime);
@@ -491,6 +575,14 @@ export class History extends Module {
     // Capture caret position along with state
     const caretPosition = this.getCaretPosition();
 
+    // Check if this state is identical to the last entry (avoid duplicates)
+    const lastEntry = this.undoStack[this.undoStack.length - 1];
+
+    if (lastEntry && this.areStatesEqual(lastEntry.state, state)) {
+      // State hasn't changed, no need to record
+      return;
+    }
+
     // Clear redo stack when new changes are made
     this.redoStack = [];
 
@@ -561,6 +653,44 @@ export class History extends Module {
     }
   }
 
+  /**
+   * Compares two states for equality (ignoring timestamps)
+   * @param a - first state
+   * @param b - second state
+   * @returns true if the block content is identical
+   */
+  private areStatesEqual(a: OutputData, b: OutputData): boolean {
+    // Quick check: different number of blocks
+    if (a.blocks.length !== b.blocks.length) {
+      return false;
+    }
+
+    // Compare each block using every() for functional approach
+    return a.blocks.every((blockA, i) => {
+      const blockB = b.blocks[i];
+
+      // Check ID and type
+      if (blockA.id !== blockB.id || blockA.type !== blockB.type) {
+        return false;
+      }
+
+      // Compare data (deep comparison via JSON)
+      if (JSON.stringify(blockA.data) !== JSON.stringify(blockB.data)) {
+        return false;
+      }
+
+      // Compare tunes if present
+      const tunesA = JSON.stringify(blockA.tunes ?? {});
+      const tunesB = JSON.stringify(blockB.tunes ?? {});
+
+      if (tunesA !== tunesB) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+
   /**
    * Restores document to a given state using smart diffing
    * Only updates blocks that have changed to preserve DOM state
@@ -1085,14 +1215,23 @@ export class History extends Module {
     }
     this.registeredShortcuts = [];
 
+    // Remove keydown handler
+    const redactor = this.Blok.UI?.nodes?.redactor;
+
+    if (this.keydownHandler && redactor) {
+      redactor.removeEventListener('keydown', this.keydownHandler);
+    }
+    this.keydownHandler = null;
+
     // Clear active instance if it's this one
     if (History.activeInstance === this) {
       History.activeInstance = null;
     }
 
-    // Clear stacks
+    // Clear stacks and smart grouping
     this.undoStack = [];
     this.redoStack = [];
     this.initialStateCaptured = false;
+    this.smartGrouping.clearContext();
   }
 }

package/src/components/modules/paste.ts

@@ -270,14 +270,10 @@ export class Paste extends Module {
     const normalizedHtmlData = rawHtmlData;
 
     /**
-     * If Blok json is passed, insert it
+     * If Blok json is passed, check if we should try pattern matching first
      */
-    if (blokData) {
-      try {
-        this.insertBlokData(JSON.parse(blokData));
-
-        return;
-      } catch (_e) { } // Do nothing and continue execution as usual if error appears
+    if (blokData && await this.handleBlokDataPaste(blokData, plainData)) {
+      return;
     }
 
     /** Add all tags that can be substituted to sanitizer configuration */
@@ -307,6 +303,50 @@ export class Paste extends Module {
     }
   }
 
+  /**
+   * Handles pasting of Blok JSON data, with pattern matching priority.
+   * For plain text that might match a pattern (like URLs), tries pattern matching first.
+   * This handles the case where text is cut and pasted within the same editor -
+   * we want pattern matching to still work for things like embed URLs.
+   * @param blokData - serialized Blok JSON data
+   * @param plainData - plain text content from clipboard
+   * @returns true if paste was handled, false otherwise
+   */
+  private async handleBlokDataPaste(blokData: string, plainData: string): Promise<boolean> {
+    try {
+      const parsedBlokData = JSON.parse(blokData) as Pick<SavedData, 'id' | 'data' | 'tool'>[];
+      const shouldTryPatternMatch = plainData && this.toolsPatterns.length > 0;
+      const patternResult = shouldTryPatternMatch ? await this.processPattern(plainData) : undefined;
+
+      if (patternResult) {
+        await this.insertPatternMatch(patternResult);
+
+        return true;
+      }
+
+      this.insertBlokData(parsedBlokData);
+
+      return true;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  /**
+   * Inserts a matched pattern as a new block
+   * @param patternResult - the matched pattern with tool and event
+   */
+  private async insertPatternMatch(patternResult: { event: PasteEvent; tool: string }): Promise<void> {
+    const { BlockManager, Caret } = this.Blok;
+    const needToReplaceCurrentBlock = BlockManager.currentBlock &&
+      BlockManager.currentBlock.tool.isDefault &&
+      BlockManager.currentBlock.isEmpty;
+
+    const insertedBlock = await BlockManager.paste(patternResult.tool, patternResult.event, needToReplaceCurrentBlock);
+
+    Caret.setToBlock(insertedBlock, Caret.positions.END);
+  }
+
   /**
    * Process pasted text and divide them into Blocks
    * @param {string} data - text to process. Can be HTML or plain.

package/src/components/modules/renderer.ts

@@ -52,7 +52,7 @@ export class Renderer extends Module {
          * Create Blocks instances
          */
         const blocks = processedBlocks.map((blockData: OutputBlockData) => {
-          const { tunes, id, parent, content } = blockData;
+          const { tunes, id, parent, content, slot } = blockData;
           const originalTool = blockData.type;
           const availabilityResult = (() => {
             if (Tools.available.has(originalTool)) {
@@ -79,6 +79,7 @@ export class Renderer extends Module {
                 tunes,
                 parentId: parent,
                 contentIds: content,
+                slot,
               });
             } catch (error) {
               log(`Block «${tool}» skipped because of plugins error`, 'error', {
@@ -98,6 +99,7 @@ export class Renderer extends Module {
                 tunes,
                 parentId: parent,
                 contentIds: content,
+                slot,
               });
             }
           };

package/types/api/blocks.d.ts

@@ -71,6 +71,21 @@ export interface Blocks {
    */
   getBlockByElement(element: HTMLElement): BlockAPI | undefined;
 
+  /**
+   * Returns all child blocks of a parent container block
+   *
+   * @param parentId - id of the parent block
+   */
+  getChildren(parentId: string): BlockAPI[];
+
+  /**
+   * Returns child blocks of a parent container block in a specific slot
+   *
+   * @param parentId - id of the parent block
+   * @param slot - slot index (e.g., column index for columns block)
+   */
+  getChildrenInSlot(parentId: string, slot: number): BlockAPI[];
+
   /**
    * Returns Blocks count
    * @return {number}