@jackuait/blok 0.13.2 → 0.14.0

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

@@ -1197,7 +1197,18 @@ export class Toolbar extends Module<ToolbarNodes> {
       const currentBlock = this.Blok.BlockManager.currentBlock;
 
       if (currentBlock && currentBlock.inputs.length > 0) {
-        this.Blok.Caret.setToBlock(currentBlock, this.Blok.Caret.positions.END);
+        // If a freshly inserted tool already placed the caret inside its own
+        // subtree (e.g. a column_list focusing its FIRST column), keep it.
+        // Restore focus only when it has actually fallen outside the block —
+        // to document.body on non-keyboard close paths — which is what this
+        // branch defends against. Restoring to END would otherwise jump a
+        // multi-input container like columns to its LAST input.
+        const active = document.activeElement;
+        const focusAlreadyInBlock = active instanceof Node && currentBlock.holder.contains(active);
+
+        if (!focusAlreadyInBlock) {
+          this.Blok.Caret.setToBlock(currentBlock, this.Blok.Caret.positions.END);
+        }
       }
     });
 

package/src/components/modules/uiControllers/controllers/blockHover.ts

@@ -137,6 +137,15 @@ export class BlockHoverController extends Controller {
         return;
       }
 
+      /**
+       * Columns are structural containers, not selectable blocks. Skip the
+       * event so neither the column nor its column_list ever gets a toolbar —
+       * only the blocks inside a column are selectable (Notion-style).
+       */
+      if (BlockHoverController.isColumnContainer(block)) {
+        return;
+      }
+
       /**
        * For multi-block selection, still emit 'block-hovered' event so toolbar can follow the hovered block.
        * The toolbar module will handle the logic of whether to move or not.
@@ -189,6 +198,17 @@ export class BlockHoverController extends Controller {
     });
   }
 
+  /**
+   * Columns are structural containers, not independent blocks: neither a
+   * `column` nor its `column_list` may own a drag handle, settings menu, or
+   * "convert to" option. Only the blocks inside a column are selectable.
+   * @param block - a hovered or candidate block
+   * @returns true when the block is a column layout container
+   */
+  private static isColumnContainer(block: Block): boolean {
+    return block.name === 'column' || block.name === 'column_list';
+  }
+
   /**
    * Emits a BlockHovered event for the nearest block, but only if the cursor
    * is within the extended hover zone (HOVER_ZONE_SIZE px from content edges).
@@ -198,7 +218,8 @@ export class BlockHoverController extends Controller {
   private emitNearestBlockHoveredInZone(clientX: number, clientY: number): void {
     const blocks = this.Blok.BlockManager.blocks;
     const topLevelBlocks = blocks.filter(block =>
-      block.holder.closest('[data-blok-table-cell-blocks], [data-blok-toggle-children]') === null
+      !BlockHoverController.isColumnContainer(block)
+      && block.holder.closest('[data-blok-table-cell-blocks], [data-blok-toggle-children]') === null
     );
 
     if (topLevelBlocks.length === 0) {
@@ -246,7 +267,8 @@ export class BlockHoverController extends Controller {
      * This matches the direct-hit path which also resolves nested blocks to their parent.
      */
     const topLevelBlocks = blocks.filter(block =>
-      block.holder.closest('[data-blok-table-cell-blocks], [data-blok-toggle-children]') === null
+      !BlockHoverController.isColumnContainer(block)
+      && block.holder.closest('[data-blok-table-cell-blocks], [data-blok-toggle-children]') === null
     );
 
     if (topLevelBlocks.length === 0) {

package/src/components/modules/uiControllers/controllers/selection.ts

@@ -33,11 +33,51 @@ export class SelectionController extends Controller {
     this.wrapperElement = element;
   }
 
+  /**
+   * Whether a pointer is currently pressed (an in-progress drag selection).
+   * While true, the inline toolbar is kept hidden so it doesn't pop up mid-drag;
+   * it appears the moment the pointer is released.
+   */
+  private isPointerDown = false;
+
+  /**
+   * Remember that a drag may be starting so the inline toolbar stays hidden
+   * until the pointer is released.
+   */
+  private handlePointerDown = (): void => {
+    this.isPointerDown = true;
+  };
+
+  /**
+   * Show the inline toolbar the moment a pointer drag-selection is released.
+   *
+   * While the pointer is down the debounced selectionchange handler suppresses
+   * the toolbar (see handleSelectionChange), so it never flickers mid-drag.
+   * Clearing the flag and running the handler synchronously here makes the
+   * toolbar appear instantly on release.
+   */
+  private handlePointerUp = (): void => {
+    this.isPointerDown = false;
+    this.handleSelectionChange();
+  };
+
+  /**
+   * A cancelled pointer interaction (e.g. the gesture is taken over by the
+   * browser) never fires pointerup, so clear the flag to avoid stranding the
+   * toolbar in a permanently-suppressed state.
+   */
+  private handlePointerCancel = (): void => {
+    this.isPointerDown = false;
+  };
+
   /**
    * Enable selection change listeners
    */
   public override enable(): void {
     this.listeners.on(document, 'selectionchange', this.selectionChangeDebounced);
+    this.listeners.on(document, 'pointerdown', this.handlePointerDown);
+    this.listeners.on(document, 'pointerup', this.handlePointerUp);
+    this.listeners.on(document, 'pointercancel', this.handlePointerCancel);
   }
 
   /**
@@ -137,6 +177,16 @@ export class SelectionController extends Controller {
       this.Blok.BlockManager.setCurrentBlockByChildNode(focusedElement);
     }
 
+    /**
+     * While the pointer is held down the user is still dragging out the
+     * selection. Keep the toolbar hidden until they release (handlePointerUp),
+     * so it appears in one motion at the final selection rather than popping up
+     * mid-drag.
+     */
+    if (this.isPointerDown) {
+      return;
+    }
+
     void this.Blok.InlineToolbar.tryToShow(true);
   }
 

package/src/components/utils/blocks.ts

@@ -191,20 +191,34 @@ export const getConvertibleToolsForBlocks = async (blocks: BlockAPI[], allBlockT
   }
 
   /**
-   * Check that all blocks have export conversion config
+   * Only the "roots" of the selection constrain the conversion targets:
+   *
+   * - A block nested under another selected block rides with its container
+   *   (e.g. the contents of a selected column_list) and must NOT be converted
+   *   on its own — so it's ignored here.
+   * - A block whose tool has no «export» rule (e.g. container blocks like
+   *   column_list/column) cannot convert and is left untouched — ignored too,
+   *   NOT used to suppress every target for the whole selection.
    */
-  for (const block of blocks) {
+  const selectedIds = new Set(blocks.map((block) => block.id));
+  const convertibleBlocks = blocks.filter((block) => {
+    if (block.parentId !== null && selectedIds.has(block.parentId)) {
+      return false;
+    }
+
     const blockTool = allBlockTools.find((tool) => tool.name === block.name);
 
-    if (blockTool !== undefined && !isToolConvertable(blockTool, 'export')) {
-      return [];
-    }
+    return blockTool === undefined || isToolConvertable(blockTool, 'export');
+  });
+
+  if (convertibleBlocks.length === 0) {
+    return [];
   }
 
   /**
-   * Get the set of tool names that all blocks currently use
+   * Get the set of tool names that the convertible blocks currently use
    */
-  const blockToolNames = new Set(blocks.map((block) => block.name));
+  const blockToolNames = new Set(convertibleBlocks.map((block) => block.name));
 
   /**
    * Filter tools that have import conversion config and valid toolbox

package/src/styles/colors.css

@@ -241,6 +241,9 @@
   /* Small UI surfaces that can't reach a var via Tailwind arbitrary syntax. */
   --blok-button-focus-bg-hover: #fbfcfe;
   --blok-dnd-drop-indicator-bg: #d4e3fc;
+  /* Drop-line geometry shared by the horizontal (top/bottom) and vertical
+     (left/right) indicators so both bars render identically. */
+  --blok-dnd-drop-indicator-thickness: 6px;
 
   /* Direct-usage surface tokens extracted in B1.6. Light-theme values match
      the dark overrides below; they are rarely applied outside the dark theme. */

package/src/styles/columns.css

@@ -0,0 +1,105 @@
+/*
+ * Columns layout tool — responsive stacking.
+ *
+ * The flex children of a column_list are the block-holder wrappers
+ * ([data-blok-element]), not the [data-blok-column] elements the Column tool
+ * renders. Target the holders directly so flex-wrap forces vertical stacking
+ * on narrow viewports and restores side-by-side distribution above the
+ * project's mobile breakpoint (651px, matching the `not-mobile` variant).
+ */
+[data-blok-columns] > [data-blok-element] {
+  flex-basis: 100%;
+  flex-shrink: 0;
+}
+
+@media (min-width: 651px) {
+  [data-blok-columns] > [data-blok-element] {
+    flex-basis: 0;
+    flex-shrink: 1;
+  }
+}
+
+/*
+ * New-column entry animation (Notion-style): a freshly added column slides in by
+ * growing its flex share from 0 while fading in, so the existing columns reflow
+ * to make room. The trigger attribute is set on the column holder when the
+ * column is created and stripped on animationend — see playColumnEnterAnimation.
+ */
+@keyframes blok-column-enter {
+  from {
+    flex-grow: 0;
+    opacity: 0;
+  }
+
+  to {
+    flex-grow: 1;
+    opacity: 1;
+  }
+}
+
+[data-blok-columns] > [data-blok-element][data-blok-column-enter] {
+  animation: blok-column-enter 200ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-blok-columns] > [data-blok-element][data-blok-column-enter] {
+    animation: none;
+  }
+}
+
+/*
+ * Resize separator — a fixed-width flex item that forms the gutter between two
+ * columns. The visible bar is hidden until the gutter is hovered or dragged,
+ * matching Notion. The bar is wider than its hit feel via the full-width
+ * col-resize cursor zone.
+ */
+[data-blok-column-resizer] {
+  flex: 0 0 1.5rem;
+  align-self: stretch;
+  position: relative;
+  cursor: col-resize;
+  touch-action: none;
+}
+
+[data-blok-column-resizer]::before {
+  content: '';
+  position: absolute;
+  inset-block: 0.25rem;
+  left: 50%;
+  width: 3px;
+  border-radius: 9999px;
+  /* Theme-aware so the handle stays visible on both light and dark surfaces. */
+  background-color: var(--blok-border-strong);
+  transform: translateX(-50%);
+  opacity: 0;
+  transition: opacity 120ms ease, background-color 120ms ease;
+}
+
+[data-blok-column-resizer]:hover::before,
+[data-blok-column-resizer][data-dragging]::before {
+  opacity: 1;
+}
+
+/* Accent the handle while actively dragging for clear feedback. */
+[data-blok-column-resizer][data-dragging]::before {
+  background-color: var(--blok-active-icon);
+}
+
+/*
+ * While a block is being dragged, suppress the gutter handle entirely. Otherwise
+ * the cursor passing over a separator triggers :hover and reveals the gray handle
+ * bar right next to the blue drop indicator — reading as two drop targets in the
+ * gutter. Higher specificity than the :hover rule (three attributes), so it wins
+ * without !important. A real resize drag sets [data-dragging] on the resizer, not
+ * data-blok-dragging on the interface, so this never hides the active resize.
+ */
+[data-blok-interface][data-blok-dragging="true"] [data-blok-column-resizer]::before {
+  opacity: 0;
+}
+
+/* Columns stack vertically below the breakpoint, so the gutter handle hides. */
+@media (max-width: 650px) {
+  [data-blok-column-resizer] {
+    display: none;
+  }
+}

package/src/styles/main.css

@@ -170,11 +170,29 @@
   @apply relative;
 }
 
+/*
+ * Shared drop-line look for every orientation. The bar is a rounded rule whose
+ * colour and thickness come from the design tokens, so the horizontal
+ * (top/bottom) and vertical (left/right) indicators are visually identical;
+ * each orientation rule below only sets which axis the thickness applies to and
+ * where the bar is pinned.
+ */
 [data-drop-indicator]::before {
-  @apply content-[''] absolute h-1.5 rounded-xs pointer-events-none z-10;
+  @apply content-[''] absolute rounded-xs pointer-events-none z-10;
   background-color: var(--blok-dnd-drop-indicator-bg);
-  left: calc(var(--drop-indicator-depth, 0) * var(--blok-space-3));
-  right: 0;
+}
+
+/*
+ * Horizontal drop indicator: a rule across the top or bottom edge of the block.
+ */
+[data-drop-indicator="top"]::before,
+[data-drop-indicator="bottom"]::before {
+  height: var(--blok-dnd-drop-indicator-thickness);
+  /* Confine the line to the content box: the holder spans the editor gutters,
+   * so the side offsets pull the line in to the visible content width. The
+   * depth indent (list nesting) is added on top of the content-left offset. */
+  left: calc(var(--drop-indicator-side-left, 0px) + var(--drop-indicator-depth, 0) * var(--blok-space-3));
+  right: var(--drop-indicator-side-right, 0px);
 }
 
 [data-drop-indicator="bottom"]::before {
@@ -187,6 +205,32 @@
   transform: translateY(-50%);
 }
 
+/*
+ * Vertical drop indicator: a bar on the left or right edge of the holder,
+ * signalling a column-layout drop. Same look as the horizontal rule, only the
+ * thickness applies to the width and the bar is pinned to a side edge.
+ */
+[data-drop-indicator="left"]::before,
+[data-drop-indicator="right"]::before {
+  width: var(--blok-dnd-drop-indicator-thickness);
+  /* Span the full column-row height when the target sits in a column_list: the
+   * controller sets these to the row's top/bottom offset (negative, so the bar
+   * grows past the single block). Default 0/0 → the bar matches the block. */
+  top: var(--drop-indicator-side-top, 0);
+  bottom: var(--drop-indicator-side-bottom, 0);
+}
+
+[data-drop-indicator="left"]::before {
+  /* Pull the bar out into the gutter so it sits clear of the content edge. */
+  left: calc(var(--drop-indicator-side-left, 0px) - var(--blok-space-2));
+  transform: translateX(-50%);
+}
+
+[data-drop-indicator="right"]::before {
+  right: calc(var(--drop-indicator-side-right, 0px) - var(--blok-space-2));
+  transform: translateX(50%);
+}
+
 /* Spring-loaded: flash selection highlight on toggle after it auto-expands */
 [data-blok-spring-loaded] [data-blok-element-content] {
   animation: spring-loaded-flash 700ms ease-out forwards;
@@ -296,6 +340,7 @@
 @import './emoji-picker.css';
 @import './database.css';
 @import './image.css';
+@import './columns.css';
 
 /*
   Image tool — selectors audited by unit tests (no backdrop-filter regression,

package/src/styles/popover-animation.css

@@ -26,6 +26,14 @@
   transform: scale(0.98);
 }
 
+/* Inline toolbar appears instantly — no entrance animation.
+   Direct child only, so nested inline popovers keep their animation. */
+[data-blok-popover-inline] > [data-blok-popover-container],
+[data-blok-popover-inline]:not([data-blok-popover-opened='true']) > [data-blok-popover-container] {
+  transition: none;
+  transform: none;
+}
+
 @media (prefers-reduced-motion: reduce) {
   [data-blok-popover-container] {
     transition: none;

package/src/tools/column/index.ts

@@ -0,0 +1,189 @@
+import type {
+  API,
+  BlockTool,
+  BlockToolConstructorOptions,
+} from '../../../types';
+import { COLUMN_ATTR, unwrapColumnListIfCollapsed } from '../columns-shared';
+import { mountChildBlocks } from '../nested-blocks';
+import { DATA_ATTR } from '../../components/constants/data-attributes';
+import { twMerge } from '../../components/utils/tw';
+import type { ColumnData } from './types';
+
+/**
+ * Column block — a single vertical column inside a column_list.
+ * Hosts arbitrary user blocks as nested children and seeds an empty
+ * paragraph when created so it is never empty.
+ */
+export class Column implements BlockTool {
+  private readonly api: API;
+  private _data: ColumnData;
+  private readonly blockId: string;
+  private readonly block: BlockToolConstructorOptions<ColumnData>['block'];
+  private childContainer: HTMLElement | null = null;
+  // Latched once the column has ever held content (mounted children or a seed).
+  // Distinguishes a fresh empty column (first render → seed) from one emptied
+  // later by a drag-out (re-render → self-delete).
+  private populated = false;
+
+  constructor({ data, api, block }: BlockToolConstructorOptions<ColumnData>) {
+    this.api = api;
+    this._data = { ...data };
+    this.blockId = block.id;
+    this.block = block;
+  }
+
+  public render(): HTMLElement {
+    const wrapper = document.createElement('div');
+
+    // `break-words` lets long unbreakable words reflow so a column can be
+    // resized arbitrarily thin instead of being held open at its min-content
+    // width. overflow-wrap is inherited, so descendant text picks it up.
+    wrapper.className = twMerge('flex', 'flex-col', 'min-w-0', 'break-words');
+    wrapper.setAttribute(COLUMN_ATTR, '');
+
+    const childContainer = document.createElement('div');
+
+    childContainer.setAttribute(DATA_ATTR.nestedBlocks, '');
+    wrapper.appendChild(childContainer);
+
+    this.childContainer = childContainer;
+
+    return wrapper;
+  }
+
+  public rendered(): void {
+    if (this.childContainer === null) {
+      return;
+    }
+
+    // The flex item is the block holder, not the rendered wrapper, and the
+    // holder only exists once the block is composed (post-render). Grow it so
+    // sibling columns split the row evenly; widthRatio biases the split.
+    this.block.holder.style.flexGrow = String(this._data.widthRatio ?? 1);
+    // A flex item defaults to min-width:auto (its min-content), which would
+    // floor the column at the width of its widest content. Allow it to shrink
+    // freely so the resizer has no min-width restriction.
+    this.block.holder.style.minWidth = '0';
+
+    const children = this.api.blocks.getChildren(this.blockId);
+
+    if (children.length > 0) {
+      this.populated = true;
+      mountChildBlocks(this.childContainer, children);
+
+      return;
+    }
+
+    // Empty AFTER having held content: the column's last block was dragged out,
+    // which re-fires rendered(). A column is pure layout, never standalone — so
+    // it removes itself rather than lingering as a dead, uninteractable box.
+    if (this.populated) {
+      this.deleteSelf();
+
+      return;
+    }
+
+    // Empty on the FIRST render. noSeed is a one-shot creation hint: a column-list
+    // wrap / add-column fills the column explicitly right afterwards, so suppress
+    // the seed this once and let the follow-up render mount the moved-in blocks.
+    if (this._data.noSeed === true) {
+      this._data.noSeed = false;
+
+      return;
+    }
+
+    // A fresh, unseeded column (e.g. a slash-menu preset): seed it so it is
+    // never empty.
+    this.seedParagraph();
+    this.populated = true;
+  }
+
+  /**
+   * Remove this now-childless column from its column_list. Deferred to a
+   * microtask because rendered() runs inside the drop's affected-parents loop;
+   * an index-based delete fired synchronously would splice the flat array
+   * mid-iteration. Re-check emptiness at fire time so a column refilled before
+   * the microtask runs is spared. Deleting the column triggers its own removed()
+   * hook, which unwraps the column_list if this leaves a single survivor.
+   */
+  private deleteSelf(): void {
+    queueMicrotask(() => {
+      if (this.api.blocks.getChildren(this.blockId).length > 0) {
+        return;
+      }
+
+      const index = this.api.blocks.getBlockIndex(this.blockId);
+
+      if (index !== undefined) {
+        void this.api.blocks.delete(index);
+      }
+    });
+  }
+
+  /**
+   * Seed the empty column with a paragraph. The first seeded column of a freshly
+   * created column_list claims the caret; siblings carry noFocus so the
+   * asynchronous last column never steals it (see {@link ColumnData}).
+   */
+  private seedParagraph(): void {
+    const blockIndex = this.api.blocks.getBlockIndex(this.blockId);
+
+    if (blockIndex === undefined || this.childContainer === null) {
+      return;
+    }
+
+    const paragraph = this.api.blocks.insertInsideParent(this.blockId, blockIndex + 1);
+
+    this.childContainer.appendChild(paragraph.holder);
+
+    if (this._data.noFocus !== true) {
+      this.api.caret.setToBlock(paragraph.id, 'start');
+    }
+  }
+
+  public save(): ColumnData {
+    // The resizer mutates the holder's flex-grow live, so the holder is the
+    // source of truth once rendered. Fall back to the seeded data before the
+    // holder exists. An even-split grow of 1 is the default — omit it.
+    const liveGrow = this.block.holder?.style.flexGrow;
+    const ratio = liveGrow !== undefined && liveGrow !== ''
+      ? Number(liveGrow)
+      : this._data.widthRatio;
+
+    return ratio !== undefined && ratio !== 1
+      ? { widthRatio: ratio }
+      : {};
+  }
+
+  public validate(_data: ColumnData): boolean {
+    return true;
+  }
+
+  public removed(): void {
+    // removed() runs INSIDE blocksStore.remove, BEFORE this block is spliced
+    // out of the flat array. The unwrap below issues index-based deletes
+    // (deleteById) of the surviving column + the column_list; running them now
+    // would splice the array mid-removal, shifting indices so the outer splice
+    // hits the wrong slot — the storm that drops innocent blocks when an empty
+    // column collapses. Defer to a microtask so the triggering removal finishes
+    // its splice first and every nested delete runs on a stable array.
+    //
+    // Read the LIVE parent id (off the block) at fire time, not the id captured
+    // at construction: a column detached to root before deletion must skip.
+    queueMicrotask(() => {
+      const parentId = this.block.parentId;
+
+      if (parentId !== null) {
+        // Pass blockId as excludeId so a not-yet-spliced self is excluded from
+        // the surviving-column count.
+        void unwrapColumnListIfCollapsed(this.api, parentId, this.blockId);
+      }
+    });
+  }
+
+  public static get isReadOnlySupported(): boolean {
+    return true;
+  }
+}
+
+export type { ColumnData };

package/src/tools/column/types.ts

@@ -0,0 +1,26 @@
+import type { BlockToolData } from '../../../types';
+
+export interface ColumnData extends BlockToolData {
+  /**
+   * Width of this column relative to its siblings, applied as flex-grow.
+   * Omitted means equal width (flex-grow: 1). Set by the resize sub-project.
+   */
+  widthRatio?: number;
+
+  /**
+   * Transient flag set when a column is created programmatically (e.g. by a
+   * drag-beside drop) and will be populated by reparenting existing blocks.
+   * Suppresses the empty-paragraph seed in rendered(). Never persisted — not
+   * returned from save().
+   */
+  noSeed?: boolean;
+
+  /**
+   * Transient flag: seed the empty paragraph but do NOT move the caret into it.
+   * Columns render asynchronously, so when a column_list seeds several columns
+   * the LAST one's self-focus would otherwise win the race. Setting this on
+   * every column except the first lets only the first column claim the caret.
+   * Never persisted — not returned from save().
+   */
+  noFocus?: boolean;
+}