@jackuait/blok 0.7.0-beta.3 → 0.7.0

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

@@ -1,22 +1,25 @@
 /**
- * Toggle Shortcuts - Manages the collapse/expand-all keyboard shortcut (CMD+ALT+T).
+ * Toggle Shortcuts - Manages keyboard shortcuts for toggle blocks.
  *
- * Iterates all blocks in the editor and toggles all collapsible blocks
- * (toggle blocks and toggle headings):
- * - If any collapsible block is collapsed, expands all
- * - If all collapsible blocks are expanded, collapses all
+ * CMD+ALT+T: Collapse/expand all toggle blocks on the page.
+ * CMD+SHIFT+[: Collapse/expand the toggle block that currently has focus
+ *   (or its parent toggle if the focused block is a child).
+ * CMD+ALT+SHIFT+T: Collapse/expand all descendant toggles of the current toggle.
+ *   Falls back to page-wide CMD+ALT+T behavior when cursor is not inside any toggle.
  */
 
-import type { API } from '../../../types';
+import type { API, BlockAPI } from '../../../types';
 
 import { Shortcuts } from '../../components/utils/shortcuts';
 
-import { TOGGLE_ATTR } from './constants';
+import { TOGGLE_ATTR, TOOL_NAME } from './constants';
 
 const COLLAPSE_EXPAND_ALL_SHORTCUT = 'CMD+ALT+T';
+const COLLAPSE_EXPAND_CURRENT_SHORTCUT = 'CMD+SHIFT+[';
+const COLLAPSE_EXPAND_SCOPED_SHORTCUT = 'CMD+ALT+SHIFT+T';
 
 /**
- * Manages the collapse/expand-all shortcut for toggle blocks.
+ * Manages the collapse/expand shortcuts for toggle blocks.
  */
 export class ToggleShortcuts {
   private readonly api: API;
@@ -29,8 +32,8 @@ export class ToggleShortcuts {
   }
 
   /**
-   * Register the CMD+ALT+T shortcut on the document.
-   * Pre-clears any stale registration to handle cases where a previous editor
+   * Register all toggle shortcuts on the document.
+   * Pre-clears any stale registrations to handle cases where a previous editor
    * instance was not fully destroyed (e.g. Storybook story switching).
    */
   public register(): void {
@@ -39,6 +42,8 @@ export class ToggleShortcuts {
     }
 
     Shortcuts.remove(document, COLLAPSE_EXPAND_ALL_SHORTCUT);
+    Shortcuts.remove(document, COLLAPSE_EXPAND_CURRENT_SHORTCUT);
+    Shortcuts.remove(document, COLLAPSE_EXPAND_SCOPED_SHORTCUT);
 
     Shortcuts.add({
       name: COLLAPSE_EXPAND_ALL_SHORTCUT,
@@ -53,11 +58,37 @@ export class ToggleShortcuts {
       },
     });
 
+    Shortcuts.add({
+      name: COLLAPSE_EXPAND_CURRENT_SHORTCUT,
+      on: document,
+      handler: (event: KeyboardEvent) => {
+        if (!this.shouldHandle(event)) {
+          return;
+        }
+
+        event.preventDefault();
+        this.toggleCurrent();
+      },
+    });
+
+    Shortcuts.add({
+      name: COLLAPSE_EXPAND_SCOPED_SHORTCUT,
+      on: document,
+      handler: (event: KeyboardEvent) => {
+        if (!this.shouldHandle(event)) {
+          return;
+        }
+
+        event.preventDefault();
+        this.toggleScoped();
+      },
+    });
+
     this.registered = true;
   }
 
   /**
-   * Unregister the shortcut.
+   * Unregister all shortcuts.
    */
   public unregister(): void {
     if (!this.registered) {
@@ -65,6 +96,8 @@ export class ToggleShortcuts {
     }
 
     Shortcuts.remove(document, COLLAPSE_EXPAND_ALL_SHORTCUT);
+    Shortcuts.remove(document, COLLAPSE_EXPAND_CURRENT_SHORTCUT);
+    Shortcuts.remove(document, COLLAPSE_EXPAND_SCOPED_SHORTCUT);
     this.registered = false;
   }
 
@@ -82,6 +115,169 @@ export class ToggleShortcuts {
    * If any is collapsed, expand all. If all are expanded, collapse all.
    */
   private toggleAll(): void {
+    const toggleBlocks = this.collectAllToggleBlocks();
+
+    if (toggleBlocks.length === 0) {
+      return;
+    }
+
+    const anyCollapsed = toggleBlocks.some((b) => !b.isOpen);
+    const method = anyCollapsed ? 'expand' : 'collapse';
+
+    for (const block of toggleBlocks) {
+      block.call(method);
+    }
+  }
+
+  /**
+   * Toggle the current block if it is a toggle, or its nearest toggle ancestor
+   * if the current block is a child inside a toggle.
+   * Does nothing if neither applies.
+   */
+  private toggleCurrent(): void {
+    const currentIndex = this.api.blocks.getCurrentBlockIndex();
+    const currentBlock = this.api.blocks.getBlockByIndex(currentIndex);
+
+    if (currentBlock === undefined) {
+      return;
+    }
+
+    const targetBlock = this.findToggleBlockForCurrent(currentBlock);
+
+    if (targetBlock === undefined) {
+      return;
+    }
+
+    const toggleWrapper = targetBlock.holder.querySelector(`[${TOGGLE_ATTR.toggleOpen}]`);
+
+    if (toggleWrapper === null) {
+      return;
+    }
+
+    const isOpen = toggleWrapper.getAttribute(TOGGLE_ATTR.toggleOpen) === 'true';
+
+    targetBlock.call(isOpen ? 'collapse' : 'expand');
+  }
+
+  /**
+   * Toggle all descendant toggles of the root toggle ancestor for the current block.
+   * If the current block is not inside any toggle, falls back to page-wide toggleAll().
+   */
+  private toggleScoped(): void {
+    const currentIndex = this.api.blocks.getCurrentBlockIndex();
+    const currentBlock = this.api.blocks.getBlockByIndex(currentIndex);
+
+    if (currentBlock === undefined) {
+      return;
+    }
+
+    const rootToggle = this.findRootToggleAncestor(currentBlock);
+
+    if (rootToggle === undefined) {
+      this.toggleAll();
+      return;
+    }
+
+    const descendants = this.collectDescendantToggleBlocks(rootToggle.id);
+
+    if (descendants.length === 0) {
+      return;
+    }
+
+    const anyCollapsed = descendants.some((b) => !b.isOpen);
+    const method = anyCollapsed ? 'expand' : 'collapse';
+
+    for (const block of descendants) {
+      block.call(method);
+    }
+  }
+
+  /**
+   * Returns the toggle block to act on for the current block:
+   * - If the current block itself is a toggle, return it.
+   * - If it has a parentId pointing to a toggle block, return the parent.
+   * - Otherwise return undefined.
+   */
+  private findToggleBlockForCurrent(block: BlockAPI): BlockAPI | undefined {
+    if (this.isToggleBlock(block)) {
+      return block;
+    }
+
+    if (block.parentId !== null) {
+      const parent = this.api.blocks.getById(block.parentId);
+
+      if (parent !== null && this.isToggleBlock(parent)) {
+        return parent;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Walks up the parentId chain to find the root-level toggle ancestor of the
+   * given block. Returns the root toggle if found, or undefined if the block is
+   * not inside any toggle.
+   */
+  private findRootToggleAncestor(block: BlockAPI): BlockAPI | undefined {
+    if (this.isToggleBlock(block) && block.parentId === null) {
+      return block;
+    }
+
+    return this.walkToRootToggle(block.parentId, undefined);
+  }
+
+  private walkToRootToggle(parentId: string | null, best: BlockAPI | undefined): BlockAPI | undefined {
+    if (parentId === null) {
+      return best;
+    }
+
+    const parent = this.api.blocks.getById(parentId);
+
+    if (parent === null) {
+      return best;
+    }
+
+    return this.walkToRootToggle(parent.parentId, this.isToggleBlock(parent) ? parent : best);
+  }
+
+  /**
+   * Recursively collects all descendant toggle blocks of the given parent id.
+   * Returns items with call/isOpen so they can be expanded or collapsed.
+   */
+  private collectDescendantToggleBlocks(parentId: string): { call: (method: string) => void; isOpen: boolean }[] {
+    const children = this.api.blocks.getChildren(parentId);
+    const result: { call: (method: string) => void; isOpen: boolean }[] = [];
+
+    for (const child of children) {
+      const info = this.isToggleBlock(child) ? this.extractToggleBlockInfo(child) : null;
+
+      if (info !== null) {
+        result.push(info);
+      }
+
+      result.push(...this.collectDescendantToggleBlocks(child.id));
+    }
+
+    return result;
+  }
+
+  private extractToggleBlockInfo(child: BlockAPI): { call: (method: string) => void; isOpen: boolean } | null {
+    const toggleWrapper = child.holder.querySelector(`[${TOGGLE_ATTR.toggleOpen}]`);
+
+    if (toggleWrapper === null) {
+      return null;
+    }
+
+    const isOpen = toggleWrapper.getAttribute(TOGGLE_ATTR.toggleOpen) === 'true';
+
+    return { call: (method: string) => child.call(method), isOpen };
+  }
+
+  /**
+   * Collect all toggle-capable blocks across the entire document.
+   */
+  private collectAllToggleBlocks(): { call: (method: string) => void; isOpen: boolean }[] {
     const blockCount = this.api.blocks.getBlocksCount();
     const toggleBlocks: { call: (method: string) => void; isOpen: boolean }[] = [];
 
@@ -103,15 +299,13 @@ export class ToggleShortcuts {
       toggleBlocks.push({ call: (method: string) => block.call(method), isOpen });
     }
 
-    if (toggleBlocks.length === 0) {
-      return;
-    }
-
-    const anyCollapsed = toggleBlocks.some((b) => !b.isOpen);
-    const method = anyCollapsed ? 'expand' : 'collapse';
+    return toggleBlocks;
+  }
 
-    for (const block of toggleBlocks) {
-      block.call(method);
-    }
+  /**
+   * Returns true if the given block is a toggle block (by tool name).
+   */
+  private isToggleBlock(block: BlockAPI): boolean {
+    return block.name === TOOL_NAME;
   }
 }

package/src/tools/toggle/types.ts

@@ -10,6 +10,8 @@ import type { BlockToolData } from '../../../types';
 export interface ToggleItemData extends BlockToolData {
   /** Toggle item text content (can include HTML) */
   text: string;
+  /** Whether the toggle is open (expanded). Persisted on save so state is restored on reload. */
+  isOpen?: boolean;
 }
 
 /**

package/src/types-internal/blok-modules.d.ts

@@ -16,6 +16,7 @@ import { StylesAPI } from '../components/modules/api/styles';
 import { ToolbarAPI } from '../components/modules/api/toolbar';
 import { TooltipAPI } from '../components/modules/api/tooltip';
 import { UiAPI } from '../components/modules/api/ui';
+import { WidthAPI } from '../components/modules/api/width';
 /** ./toolbar */
 import { BlockSettings } from '../components/modules/toolbar/blockSettings';
 import { Toolbar } from '../components/modules/toolbar/index';
@@ -38,6 +39,7 @@ import { Tools } from '../components/modules/tools';
 import { UI } from '../components/modules/ui';
 import { ToolsAPI } from '../components/modules/api/tools';
 import { I18n } from '../components/modules/i18n';
+import { WidthManager } from '../components/modules/widthManager';
 import { YjsManager } from '../components/modules/yjs';
 
 export interface BlokModules {
@@ -60,6 +62,7 @@ export interface BlokModules {
   ToolbarAPI: ToolbarAPI,
   TooltipAPI: TooltipAPI,
   UiAPI: UiAPI,
+  WidthAPI: WidthAPI,
 
   // Toolbar Modules
   BlockSettings: BlockSettings,
@@ -82,5 +85,6 @@ export interface BlokModules {
   Saver: Saver,
   Tools: Tools,
   UI: UI,
+  WidthManager: WidthManager,
   YjsManager: YjsManager,
 }

package/types/api/block.d.ts

@@ -26,6 +26,11 @@ export interface BlockAPI {
    */
   readonly holder: HTMLElement;
 
+  /**
+   * Id of the parent block, or null if this block has no parent
+   */
+  readonly parentId: string | null;
+
   /**
    * True if Block content is empty
    */

package/types/api/blocks.d.ts

@@ -182,6 +182,17 @@ export interface Blocks {
     insertIndex: number,
   ): BlockAPI;
 
+  /**
+   * Insert a new paragraph block as a child of the given parent block, atomically.
+   * The block creation and parent assignment are grouped into a single undo entry,
+   * so a single CMD+Z removes the new block completely.
+   *
+   * @param parentId - id of the parent block
+   * @param insertIndex - flat block index where the new block should appear
+   * @returns BlockAPI for the newly created child block
+   */
+  insertInsideParent(parentId: string, insertIndex: number): BlockAPI;
+
   /**
    * Execute a function within a transaction.
    * All block operations (insert, delete, move) within fn are grouped
@@ -191,4 +202,22 @@ export interface Blocks {
    * @param fn - The function containing block operations to group
    */
   transact?(fn: () => void): void;
+
+  /**
+   * Execute a function without recording any block operations in the undo history.
+   * Use this for auto-repair operations (e.g. ensuring empty cells always have a block)
+   * that should never appear as undoable entries in the history.
+   *
+   * @param fn - The function containing block operations to execute without undo capture
+   */
+  transactWithoutCapture?(fn: () => void): void;
+
+  /**
+   * Notify BlockManager that a pointer drag interaction has started or ended.
+   * While active, DOM-mutation-triggered Yjs syncs are suppressed to prevent
+   * cross-cell browser DOM mutations from corrupting Yjs state.
+   *
+   * @param active - true when a drag starts, false when it ends
+   */
+  setPointerDragActive?(active: boolean): void;
 }

package/types/api/index.d.ts

@@ -16,3 +16,4 @@ export * from './readonly';
 export * from './i18n';
 export * from './ui';
 export * from './tools';
+export * from './width';

package/types/api/width.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Describes the editor-level width mode API
+ */
+export interface Width {
+  /**
+   * Returns the current width mode
+   */
+  get(): 'narrow' | 'full';
+
+  /**
+   * Sets the width mode
+   */
+  set(mode: 'narrow' | 'full'): void;
+
+  /**
+   * Toggles between 'narrow' and 'full'
+   */
+  toggle(): void;
+}

package/types/configs/blok-config.d.ts

@@ -152,5 +152,38 @@ export interface BlokConfig {
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce
      */
     nonce?: string;
+
+    /**
+     * Custom font family for the entire editor UI (content area, toolbars, popovers).
+     * Accepts any valid CSS font-family value.
+     * @example 'Inter, sans-serif'
+     */
+    fontFamily?: string;
   }
+
+  /**
+   * Initial width mode. Defaults to 'narrow'.
+   */
+  defaultWidth?: 'narrow' | 'full';
+
+  /**
+   * CSS max-width value for narrow mode.
+   * Any valid CSS length (e.g. '650px', '800px', '60ch').
+   * Defaults to '650px'.
+   */
+  narrowWidth?: string;
+
+  /**
+   * CSS max-width value for full width mode.
+   * Any valid CSS length, or 'none' for no constraint.
+   * Defaults to 'none'.
+   */
+  fullWidth?: string;
+
+  /**
+   * Called when the editor width mode changes.
+   * @param mode - the new mode ('narrow' or 'full')
+   * @param value - the resolved CSS max-width value
+   */
+  onWidthChange?: (mode: 'narrow' | 'full', value: string) => void;
 }

package/types/index.d.ts

@@ -30,6 +30,7 @@ import {
   I18n,
   Ui,
   Tools,
+  Width,
 } from './api';
 
 import { OutputData } from './data-formats';
@@ -105,6 +106,7 @@ export {
   I18n,
   Ui,
   Tools,
+  Width,
 } from './api';
 export {
   BlockMutationType,
@@ -142,6 +144,7 @@ export interface API {
   i18n: I18n;
   readOnly: ReadOnly;
   ui: Ui;
+  width: Width;
   rectangleSelection: {
     cancelActiveSelection: () => void;
     isRectActivated: () => boolean;
@@ -176,6 +179,7 @@ export class Blok {
   public inlineToolbar: InlineToolbar;
   public tooltip: Tooltip;
   public readOnly: ReadOnly;
+  public width: Width;
   constructor(configuration?: BlokConfig|string);
 
   /**

package/types/react.d.ts

@@ -0,0 +1,58 @@
+import type { BlokConfig } from './index';
+import type { Blok } from './index';
+import type React from 'react';
+
+/**
+ * Configuration for the useBlok hook.
+ * Accepts all BlokConfig properties except `holder`, which is managed by BlokContent.
+ *
+ * Reactive props (sync after mount without recreation):
+ * - `readOnly` — calls `editor.readOnly.set(value)`
+ * - `autofocus` — calls `editor.focus()` when changed to true
+ *
+ * All other config is consumed once at editor creation.
+ */
+export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {}
+
+/**
+ * Props for the BlokContent component.
+ * Renders a `<div>` that becomes the Blok editor's DOM mount point.
+ * Passes through all standard HTML div attributes.
+ */
+export interface BlokContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The Blok editor instance from useBlok. Null during SSR or before initialization. */
+  editor: Blok | null;
+}
+
+/**
+ * React hook that creates and manages a Blok editor instance.
+ *
+ * @param config - Editor configuration (all BlokConfig props except `holder`)
+ * @param deps - Optional dependency array. When any dep changes, the editor is destroyed and recreated.
+ * @returns The Blok editor instance, or null during SSR / before initialization.
+ *
+ * @example
+ * ```tsx
+ * const editor = useBlok({
+ *   tools: defaultTools,
+ *   data: savedData,
+ *   readOnly: false,
+ *   onChange: (api, event) => console.log(event),
+ * });
+ * ```
+ */
+export function useBlok(
+  config: UseBlokConfig,
+  deps?: React.DependencyList
+): Blok | null;
+
+/**
+ * Component that provides the DOM mount point for a Blok editor.
+ * Renders a `<div>` and adopts the editor's DOM tree into it.
+ *
+ * @example
+ * ```tsx
+ * <BlokContent editor={editor} className="my-editor" />
+ * ```
+ */
+export declare const BlokContent: React.ForwardRefExoticComponent<BlokContentProps & React.RefAttributes<HTMLDivElement>>;

package/types/utils/popover/popover.d.ts

@@ -86,6 +86,13 @@ export interface PopoverParams {
    * block content area rather than to the plus button.
    */
   leftAlignElement?: HTMLElement;
+
+  /**
+   * When true, the first item is focused when the popover opens (default behavior).
+   * When false, no item is pre-focused — focus only appears after keyboard navigation.
+   * Defaults to true. Has no effect when a search field is present (search receives focus instead).
+   */
+  autoFocusFirstItem?: boolean;
 }