@jackuait/blok 0.13.2 → 0.14.1

package/src/tools/column-drop.ts

@@ -0,0 +1,273 @@
+import type { API } from '../../types';
+import {
+  COLUMNS_ATTR,
+  COLUMN_LIST_TOOL,
+  COLUMN_TOOL,
+  buildColumnResizers,
+  playColumnEnterAnimation,
+  resetColumnsToEvenWidth,
+} from './columns-shared';
+
+/**
+ * Rebuild the resize separators of an already-rendered column_list. The list's
+ * rendered() hook fires only once, so adding a column to a live list never
+ * re-triggers it — the separators must be rebuilt here or the new column lands
+ * without a handle. The columns row is the element carrying COLUMNS_ATTR; reach
+ * it from any child column holder.
+ */
+const rebuildColumnResizers = (api: API, columnListId: string): void => {
+  const holders = api.blocks.getChildren(columnListId).map(column => column.holder);
+  const container = holders[0]?.closest(`[${COLUMNS_ATTR}]`);
+
+  if (container instanceof HTMLElement) {
+    buildColumnResizers(container, holders, api.readOnly.isEnabled, api, columnListId);
+  }
+};
+
+export type ColumnDropSide = 'left' | 'right';
+
+/**
+ * Run `fn` as a single undo entry when the host supports transactions, else
+ * run it directly. `transact` is optional on the public API, so guard it.
+ */
+const runTransacted = (api: API, fn: () => void): void => {
+  if (api.blocks.transact !== undefined) {
+    api.blocks.transact(fn);
+
+    return;
+  }
+
+  fn();
+};
+
+/**
+ * Wrap a top-level `targetId` block and the dragged `sourceIds` into a brand
+ * new `column_list` with two columns: one holds the target, the other holds
+ * the sources stacked in document order.
+ *
+ * - side 'left'  -> column order = [sources column, target column]
+ * - side 'right' -> column order = [target column, sources column]
+ *
+ * The target's subtree follows automatically because children track their
+ * parent. All work runs in a single undo entry via `transact`.
+ *
+ * Aborts (returns null, no mutation) when:
+ * - sources is empty, or includes the target (self-drop),
+ * - the target or any source is stale (no flat index),
+ * - the target is already inside a container (use addColumnToList instead).
+ */
+export const wrapInNewColumnList = (
+  api: API,
+  targetId: string,
+  sourceIds: string[],
+  side: ColumnDropSide
+): string | null => {
+  if (sourceIds.length === 0 || sourceIds.includes(targetId)) {
+    return null;
+  }
+
+  const targetIndex = api.blocks.getBlockIndex(targetId);
+
+  if (targetIndex === undefined) {
+    return null;
+  }
+
+  for (const sourceId of sourceIds) {
+    if (api.blocks.getBlockIndex(sourceId) === undefined) {
+      return null;
+    }
+  }
+
+  // Wrapping is only for top-level targets; a target with a parent should be
+  // dropped beside an existing column via addColumnToList.
+  if (api.blocks.getById(targetId)?.parentId !== null) {
+    return null;
+  }
+
+  const created: { listId: string | null; sourcesColumnId: string | null } = {
+    listId: null,
+    sourcesColumnId: null,
+  };
+
+  runTransacted(api, () => {
+    // The column_list opts out of its default auto-seed; we fill it with
+    // explicit columns below. Columns are typed blocks, so they are created
+    // with `insert(COLUMN_TOOL, ...)` + setBlockParent (insertInsideParent only
+    // ever creates the default paragraph block).
+    const list = api.blocks.insert(COLUMN_LIST_TOOL, { noSeed: true }, {}, targetIndex, false, false);
+
+    created.listId = list.id;
+
+    const firstColumn = api.blocks.insert(COLUMN_TOOL, { noSeed: true }, {}, targetIndex + 1, false, false);
+    const secondColumn = api.blocks.insert(COLUMN_TOOL, { noSeed: true }, {}, targetIndex + 2, false, false);
+
+    api.blocks.setBlockParent(firstColumn.id, list.id);
+    api.blocks.setBlockParent(secondColumn.id, list.id);
+
+    const targetColumn = side === 'left' ? secondColumn : firstColumn;
+    const sourcesColumn = side === 'left' ? firstColumn : secondColumn;
+
+    created.sourcesColumnId = sourcesColumn.id;
+
+    api.blocks.setBlockParent(targetId, targetColumn.id);
+
+    for (const sourceId of sourceIds) {
+      api.blocks.setBlockParent(sourceId, sourcesColumn.id);
+    }
+  });
+
+  // Slide the new column in once the tree has settled; the target column reflows
+  // from full width to its share for free as the new column's grow animates up.
+  if (created.sourcesColumnId !== null) {
+    const holder = api.blocks.getById(created.sourcesColumnId)?.holder;
+
+    if (holder !== undefined) {
+      playColumnEnterAnimation(holder);
+    }
+  }
+
+  return created.listId;
+};
+
+/**
+ * Wrap the top-level `blockIds` into a brand new `column_list`, one block per
+ * column, preserving selection order. Each block keeps its subtree (children
+ * track their parent), so a selected `column_list` rides into a single column
+ * as a nested list. All work runs in a single undo entry via `transact`.
+ *
+ * Non-top-level ids are IGNORED, not rejected: a cross-block selection that
+ * spans a container also marks the container's descendants selected (the
+ * selection walks the flat block array), and those descendants ride along
+ * inside their container — wrapping them again would tear the subtree apart.
+ *
+ * Aborts (returns null, no mutation) when fewer than 2 top-level, non-stale
+ * blocks remain after filtering.
+ */
+export const wrapBlocksInColumns = (
+  api: API,
+  blockIds: string[]
+): string | null => {
+  const topLevelIds = blockIds.filter((blockId) => {
+    if (api.blocks.getBlockIndex(blockId) === undefined) {
+      return false;
+    }
+
+    return api.blocks.getById(blockId)?.parentId === null;
+  });
+
+  if (topLevelIds.length < 2) {
+    return null;
+  }
+
+  const baseIndex = api.blocks.getBlockIndex(topLevelIds[0]);
+
+  if (baseIndex === undefined) {
+    return null;
+  }
+
+  const created: { listId: string | null } = { listId: null };
+
+  runTransacted(api, () => {
+    const list = api.blocks.insert(COLUMN_LIST_TOOL, { noSeed: true }, {}, baseIndex, false, false);
+
+    created.listId = list.id;
+
+    const columns = topLevelIds.map((_, i) =>
+      api.blocks.insert(COLUMN_TOOL, { noSeed: true }, {}, baseIndex + 1 + i, false, false)
+    );
+
+    for (const column of columns) {
+      api.blocks.setBlockParent(column.id, list.id);
+    }
+
+    topLevelIds.forEach((blockId, i) => {
+      api.blocks.setBlockParent(blockId, columns[i].id);
+    });
+
+    // New list: rendered() already fired with zero children, so it never built
+    // separators — rebuild the N-1 set and even the widths.
+    resetColumnsToEvenWidth(api, list.id);
+    rebuildColumnResizers(api, list.id);
+  });
+
+  return created.listId;
+};
+
+/**
+ * Add ONE new `column` beside an existing `neighborColumnId` inside its
+ * `column_list`, then move the dragged `sourceIds` into it (in order).
+ *
+ * - side 'left'  -> new column inserted before the neighbor
+ * - side 'right' -> new column inserted after the neighbor
+ *
+ * All work runs in a single undo entry via `transact`. Aborts (returns null,
+ * no mutation) when sources is empty or the neighbor is stale.
+ */
+export const addColumnToList = (
+  api: API,
+  neighborColumnId: string,
+  sourceIds: string[],
+  side: ColumnDropSide
+): string | null => {
+  if (sourceIds.length === 0) {
+    return null;
+  }
+
+  const neighborIndex = api.blocks.getBlockIndex(neighborColumnId);
+
+  if (neighborIndex === undefined) {
+    return null;
+  }
+
+  for (const sourceId of sourceIds) {
+    if (api.blocks.getBlockIndex(sourceId) === undefined) {
+      return null;
+    }
+  }
+
+  const neighbor = api.blocks.getById(neighborColumnId);
+  const columnListId = neighbor?.parentId;
+
+  if (columnListId === undefined || columnListId === null) {
+    return null;
+  }
+
+  const insertIndex = side === 'left' ? neighborIndex : neighborIndex + 1;
+
+  const created: { columnId: string | null } = { columnId: null };
+
+  runTransacted(api, () => {
+    // A column is a typed block, so it is created with insert(COLUMN_TOOL) +
+    // setBlockParent. Columns are ordered among the list's children by relative
+    // flat index, so neighborIndex (left) / neighborIndex+1 (right) places the
+    // new column on the correct side after the nested re-sort.
+    const column = api.blocks.insert(COLUMN_TOOL, { noSeed: true }, {}, insertIndex, false, false);
+
+    created.columnId = column.id;
+
+    api.blocks.setBlockParent(column.id, columnListId);
+
+    for (const sourceId of sourceIds) {
+      api.blocks.setBlockParent(sourceId, column.id);
+    }
+
+    // A column was added, so the row re-splits evenly — the only non-resize
+    // case where widths recalculate.
+    resetColumnsToEvenWidth(api, columnListId);
+
+    // The list was already rendered, so its rendered() hook won't fire again to
+    // build a separator for the new column — rebuild the full N-1 set here.
+    rebuildColumnResizers(api, columnListId);
+  });
+
+  // Slide the new column in; siblings reflow to make room as its grow animates.
+  if (created.columnId !== null) {
+    const holder = api.blocks.getById(created.columnId)?.holder;
+
+    if (holder !== undefined) {
+      playColumnEnterAnimation(holder);
+    }
+  }
+
+  return created.columnId;
+};

package/src/tools/column-list/index.ts

@@ -0,0 +1,142 @@
+import type {
+  API,
+  BlockTool,
+  BlockToolConstructorOptions,
+  ToolboxConfig,
+} from '../../../types';
+import {
+  COLUMNS_ATTR,
+  COLUMN_TOOL,
+  buildColumnResizers,
+} from '../columns-shared';
+import { mountChildBlocks } from '../nested-blocks';
+import { DATA_ATTR } from '../../components/constants/data-attributes';
+import { twMerge } from '../../components/utils/tw';
+import { buildIconColumnsCount } from '../../components/icons';
+import type { ColumnListData } from './types';
+
+/**
+ * ColumnList block — horizontal container that hosts column children.
+ * Created via slash-menu presets carrying a transient `columnCount` seed.
+ */
+export class ColumnList implements BlockTool {
+  private readonly api: API;
+  private _data: ColumnListData;
+  private readonly blockId: string;
+  private readonly readOnly: boolean;
+  private container: HTMLElement | null = null;
+
+  constructor({ data, api, block, readOnly }: BlockToolConstructorOptions<ColumnListData>) {
+    this.api = api;
+    this._data = { ...data };
+    this.blockId = block.id;
+    this.readOnly = readOnly;
+  }
+
+  public render(): HTMLElement {
+    const container = document.createElement('div');
+
+    // Horizontal gutter comes from the resizer elements, not flex gap, so a
+    // separator can live in the space between columns. Keep a vertical gap for
+    // the responsive stacked layout.
+    container.className = twMerge('flex', 'flex-row', 'flex-wrap', 'gap-y-4', 'w-full');
+    container.setAttribute(COLUMNS_ATTR, '');
+    container.setAttribute('data-blok-testid', 'column-list');
+    container.setAttribute(DATA_ATTR.nestedBlocks, '');
+
+    this.container = container;
+
+    return container;
+  }
+
+  public rendered(): void {
+    if (this.container === null) {
+      return;
+    }
+
+    const children = this.api.blocks.getChildren(this.blockId);
+
+    if (children.length === 0) {
+      // Drag-beside inserts the list and then fills it with explicit columns,
+      // so it opts out of the default auto-seed via the transient noSeed flag.
+      if (this._data.noSeed !== true) {
+        this.seedColumns();
+      }
+
+      return;
+    }
+
+    mountChildBlocks(this.container, children);
+    buildColumnResizers(this.container, children.map(child => child.holder), this.readOnly, this.api, this.blockId);
+  }
+
+  private seedColumns(): void {
+    const container = this.container;
+
+    if (container === null) {
+      return;
+    }
+
+    const count = this._data.columnCount ?? 2;
+    const baseIndex = this.api.blocks.getBlockIndex(this.blockId);
+
+    if (baseIndex === undefined) {
+      return;
+    }
+
+    // Clear the transient seed so a later re-render never re-seeds.
+    this._data = { ...this._data, columnCount: undefined };
+
+    const columns = Array.from({ length: count }).map((_, i) => {
+      // Columns render asynchronously, so each column's rendered() hook seeds
+      // and focuses its paragraph after this loop returns — the LAST one would
+      // win the focus race. Tag every column except the first with noFocus so
+      // only the first column claims the caret, deterministically.
+      const column = this.api.blocks.insert(
+        COLUMN_TOOL,
+        { noFocus: i !== 0 },
+        {},
+        baseIndex + 1 + i,
+        false,
+        false
+      );
+
+      this.api.blocks.setBlockParent(column.id, this.blockId);
+      container.appendChild(column.holder);
+
+      return column;
+    });
+
+    buildColumnResizers(container, columns.map(column => column.holder), this.readOnly, this.api, this.blockId);
+  }
+
+  public save(): ColumnListData {
+    return {};
+  }
+
+  public validate(_data: ColumnListData): boolean {
+    return true;
+  }
+
+  public static get toolbox(): ToolboxConfig {
+    const base = {
+      searchTerms: ['columns', 'cols', 'layout', 'grid'],
+      searchTermKeys: ['columns', 'layout'],
+    };
+
+    return [2, 3, 4, 5].map(count => ({
+      ...base,
+      icon: buildIconColumnsCount(count),
+      titleKey: `tools.columns.col${count}`,
+      name: `column_list-${count}`,
+      data: { columnCount: count },
+      searchTerms: [...base.searchTerms, `${count}c`, `c${count}`],
+    }));
+  }
+
+  public static get isReadOnlySupported(): boolean {
+    return true;
+  }
+}
+
+export type { ColumnListData };

package/src/tools/column-list/types.ts

@@ -0,0 +1,17 @@
+import type { BlockToolData } from '../../../types';
+
+export interface ColumnListData extends BlockToolData {
+  /**
+   * Transient seed hint: how many columns to create on first render.
+   * Set only by toolbox presets; never persisted. The real structure
+   * lives in the block's contentIds (the column children).
+   */
+  columnCount?: number;
+
+  /**
+   * Transient flag: suppress the default column auto-seed on first render.
+   * Set by drag-beside (which inserts the column_list and then fills it with
+   * explicit columns); never persisted.
+   */
+  noSeed?: boolean;
+}

package/src/tools/columns/index.ts

@@ -0,0 +1,21 @@
+import type { BaseToolConstructable } from '../../../types/tools';
+import { Column } from '../column';
+import { ColumnList } from '../column-list';
+
+/**
+ * Registration handle for the columns feature. Registering `Columns` under a
+ * single tool key (e.g. `columns`) expands to the two real block tools that
+ * back columns — `column_list` (the row container) and `column` (one slot).
+ *
+ * `Columns` is never instantiated as a block: no block has `type: 'columns'`.
+ * Saved JSON still contains `column_list` and `column` blocks. See
+ * docs/superpowers/specs/2026-06-08-single-key-columns-registration-design.md.
+ */
+export class Columns {
+  public static get provides(): { [blockType: string]: BaseToolConstructable } {
+    return {
+      column_list: ColumnList as unknown as BaseToolConstructable,
+      column: Column as unknown as BaseToolConstructable,
+    };
+  }
+}