@dxos/plugin-kanban 0.8.4-main.9735255 → 0.8.4-main.abd8ff62ef

package/src/hooks/useItemsProjection.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { useMemo } from 'react';
+
+import type { ProjectionModel } from '@dxos/schema';
+
+import { type Kanban } from '#types';
+
+/**
+ * Minimal `ProjectionModel` for `spec.kind === 'items'` (no View). Supplies `pivotField`
+ * and column options from `arrangement.columns` keys—written by sync so columns exist
+ * before refs hydrate. Stubs `getFieldProjections` / `getHiddenProperties` for shared
+ * board/card UI; hides the pivot on the card body (column shows it); Expando cards render title only.
+ */
+export const useItemsProjection = (kanban: Kanban.KanbanItems): ProjectionModel => {
+  return useMemo(() => {
+    const pivotField = kanban.spec.pivotField;
+
+    const optionIds = Object.keys(kanban.arrangement?.columns ?? {});
+    const options = optionIds.map((id) => ({ id, title: id, color: 'neutral' as const }));
+
+    const fieldProjection: any = {
+      field: { id: pivotField, path: pivotField },
+      props: { property: pivotField, options },
+    };
+
+    const fields = Atom.make(() => [fieldProjection.field]);
+
+    const stub: Pick<ProjectionModel, 'tryGetFieldProjection' | 'getFieldProjections' | 'getHiddenProperties'> & {
+      fields: typeof fields;
+    } = {
+      fields,
+      tryGetFieldProjection: (id: string) => (id === pivotField ? fieldProjection : undefined),
+      getFieldProjections: () => [],
+      getHiddenProperties: () => [pivotField],
+    };
+
+    // TODO(wittjosiah): Refactor ProjectionModel to be an interface that we can fulfill.
+    return stub as unknown as ProjectionModel;
+  }, [kanban.arrangement?.columns, kanban.spec.pivotField]);
+};

package/src/hooks/useKanbanBoardModel.browser.test.ts

@@ -0,0 +1,235 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, Registry } from '@effect-atom/atom-react';
+import { act, renderHook } from '@testing-library/react';
+import * as Schema from 'effect/Schema';
+import { beforeEach, describe, test } from 'vitest';
+
+import { Filter, JsonSchema, Obj, Query, Type } from '@dxos/echo';
+import { type View } from '@dxos/echo';
+import { Format, FormatAnnotation, PropertyMetaAnnotationId } from '@dxos/echo/internal';
+import { ObjectId } from '@dxos/keys';
+import { ProjectionModel, ViewModel, createDirectChangeCallback } from '@dxos/schema';
+
+import { Kanban } from '#types';
+
+import { useKanbanBoardModel } from './useKanbanBoardModel';
+
+// TODO(wittjosiah): Consider adding single-select to TestSchema.Task and using that instead.
+const KanbanTaskSchema = Schema.Struct({
+  title: Schema.optional(Schema.String),
+  status: Schema.Literal('__uncategorized__', 'a', 'b').pipe(
+    FormatAnnotation.set(Format.TypeFormat.SingleSelect),
+    Schema.annotations({
+      title: 'Status',
+      [PropertyMetaAnnotationId]: {
+        singleSelect: {
+          options: [
+            { id: '__uncategorized__', title: 'Uncategorized', color: 'neutral' },
+            { id: 'a', title: 'A', color: 'blue' },
+            { id: 'b', title: 'B', color: 'green' },
+          ],
+        },
+      },
+    }),
+    Schema.optional,
+  ),
+}).pipe(
+  Type.object({
+    typename: 'com.example.type.kanban-task',
+    version: '0.1.0',
+  }),
+);
+
+type KanbanTask = Schema.Schema.Type<typeof KanbanTaskSchema>;
+
+describe('useKanbanBoardModel', () => {
+  let registry: Registry.Registry;
+  let view: View.View;
+  let kanban: Kanban.Kanban;
+  let projection: ProjectionModel;
+
+  beforeEach(() => {
+    registry = Registry.make();
+    const jsonSchema = JsonSchema.toJsonSchema(KanbanTaskSchema) as Parameters<typeof createDirectChangeCallback>[1];
+    view = ViewModel.make({
+      query: Query.select(Filter.type(KanbanTaskSchema)),
+      jsonSchema,
+      pivotFieldName: 'status',
+    });
+    kanban = Kanban.make({
+      view: view,
+      arrangement: {
+        order: ['a', 'b'],
+        columns: { a: { ids: [] }, b: { ids: [] } },
+      },
+    });
+    projection = new ProjectionModel({
+      registry,
+      view,
+      baseSchema: jsonSchema,
+      change: createDirectChangeCallback(view.projection, jsonSchema),
+    });
+  });
+
+  test('returns model with getColumns and getItems', ({ expect }) => {
+    const itemA = Obj.make(KanbanTaskSchema, { status: 'a' });
+    const itemB = Obj.make(KanbanTaskSchema, { status: 'b' });
+    const initialItems: KanbanTask[] = [itemA, itemB];
+    const itemsAtom = Atom.make<KanbanTask[]>(() => initialItems);
+
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    const model = result.current;
+    expect(model.getColumnId).toBeDefined();
+    expect(model.getItemId).toBeDefined();
+    expect(model.isColumn).toBeDefined();
+    expect(model.isItem).toBeDefined();
+
+    const columns = model.getColumns();
+    expect(columns.length).toBeGreaterThanOrEqual(1);
+    const columnValues = columns.map((col) => col.columnValue);
+    expect(columnValues).toContain('a');
+    expect(columnValues).toContain('b');
+
+    const colA = columns.find((c) => c.columnValue === 'a');
+    const colB = columns.find((c) => c.columnValue === 'b');
+    expect(colA).toBeDefined();
+    expect(colB).toBeDefined();
+
+    const itemsA = model.getItems(colA!);
+    const itemsB = model.getItems(colB!);
+    expect(itemsA.map((i) => i.id)).toContain(itemA.id);
+    expect(itemsB.map((i) => i.id)).toContain(itemB.id);
+  });
+
+  test('getItems updates when itemsAtom source changes', ({ expect }) => {
+    const initialItem = Obj.make(KanbanTaskSchema, { status: 'a' });
+    const initialItems: KanbanTask[] = [initialItem];
+    const initialItemsAtom = Atom.make<KanbanTask[]>(() => initialItems);
+
+    const { result, rerender } = renderHook(
+      ({ itemsAtom }) => useKanbanBoardModel(kanban, projection, itemsAtom, registry),
+      { initialProps: { itemsAtom: initialItemsAtom } },
+    );
+
+    const columns = result.current.getColumns();
+    const colA = columns.find((c) => c.columnValue === 'a');
+    expect(colA).toBeDefined();
+    expect(result.current.getItems(colA!).length).toBe(1);
+    expect(result.current.getItems(colA!).map((i) => i.id)).toEqual([initialItem.id]);
+
+    const secondItem = Obj.make(KanbanTaskSchema, { status: 'a' });
+    const newItems: KanbanTask[] = [initialItem, secondItem];
+    const newItemsAtom = Atom.make<KanbanTask[]>(() => newItems);
+    act(() => {
+      rerender({ itemsAtom: newItemsAtom });
+    });
+
+    expect(result.current.getItems(colA!).length).toBe(2);
+    expect(result.current.getItems(colA!).map((i) => i.id)).toEqual([initialItem.id, secondItem.id]);
+  });
+
+  test('columns atom updates when kanban arrangement changes', ({ expect }) => {
+    const itemsAtom = Atom.make<KanbanTask[]>(() => []);
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    let columnsUpdateCount = 0;
+    registry.subscribe(result.current.columns, () => {
+      columnsUpdateCount++;
+    });
+
+    const columnsBefore = result.current.getColumns();
+    const orderBefore = columnsBefore.map((c) => c.columnValue);
+    expect(orderBefore).toEqual(['__uncategorized__', 'a', 'b']);
+
+    act(() => {
+      Obj.update(kanban, (kanban) => {
+        kanban.arrangement.order = ['b', 'a'];
+      });
+    });
+
+    const columnsAfter = registry.get(result.current.columns) ?? [];
+    const orderAfter = columnsAfter.map((c) => c.columnValue);
+    expect(orderAfter).toEqual(['__uncategorized__', 'b', 'a']);
+    // TODO(wittjosiah): Try to reduce to 1.
+    expect(columnsUpdateCount).toBe(2);
+  });
+
+  test('getItems returns items in column ordered by arrangement ids', ({ expect }) => {
+    const item1 = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const item2 = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const item3 = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const items: KanbanTask[] = [item1, item2, item3];
+    const itemsAtom = Atom.make<KanbanTask[]>(() => items);
+
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    const columns = result.current.getColumns();
+    const colA = columns.find((c) => c.columnValue === 'a');
+    expect(colA).toBeDefined();
+    expect(result.current.getItems(colA!).length).toBe(3);
+
+    let itemsColAUpdateCount = 0;
+    registry.subscribe(result.current.items(colA!), () => {
+      itemsColAUpdateCount++;
+    });
+
+    act(() => {
+      Obj.update(kanban, (kanban) => {
+        kanban.arrangement.columns['a'] = {
+          ids: [item3.id, item1.id, item2.id],
+        };
+      });
+    });
+
+    const itemsAfter = result.current.getItems(colA!);
+    expect(itemsAfter.map((i) => i.id)).toEqual([item3.id, item1.id, item2.id]);
+    expect(itemsColAUpdateCount).toBe(1);
+  });
+
+  test('subscribing to one column items atom does not fire when another column changes', ({ expect }) => {
+    const itemA = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const itemB = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'b',
+    });
+    const items: KanbanTask[] = [itemA, itemB];
+    const itemsAtom = Atom.make<KanbanTask[]>(() => items);
+
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    const columns = result.current.getColumns();
+    const colA = columns.find((c) => c.columnValue === 'a');
+    const colB = columns.find((c) => c.columnValue === 'b');
+    expect(colA).toBeDefined();
+    expect(colB).toBeDefined();
+
+    let itemsColAUpdateCount = 0;
+    registry.subscribe(result.current.items(colA!), () => {
+      itemsColAUpdateCount++;
+    });
+
+    act(() => {
+      Obj.update(kanban, (kanban) => {
+        kanban.arrangement.columns['b'] = { ids: [itemB.id] };
+      });
+    });
+
+    expect(itemsColAUpdateCount).toBe(0);
+  });
+});

package/src/hooks/useKanbanBoardModel.ts

@@ -0,0 +1,157 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, type Registry } from '@effect-atom/atom-react';
+import { useMemo } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { AtomObj } from '@dxos/echo-atom';
+import type { BoardModel } from '@dxos/react-ui-mosaic';
+import type { ProjectionModel } from '@dxos/schema';
+
+import { type BaseKanbanItem, type ColumnStructure, type Kanban } from '#types';
+
+import {
+  computeColumnStructure,
+  getOrderByColumnFromArrangement,
+  getOrderFromArrangement,
+  orderItemsInColumn,
+} from '../util';
+
+/**
+ * Builds a board model that maps kanban arrangement and projection onto columns and per-column items.
+ *
+ * @template T - Item type (must have id; defaults to BaseKanbanItem).
+ * @param kanban - Kanban object (arrangement, view).
+ * @param projection - ProjectionModel for pivot field and options.
+ * @param itemsAtom - Atom holding the full item list.
+ * @param registry - Registry for reading atom values.
+ * @returns BoardModel with columns atom, items family, and getColumns/getItems.
+ */
+export function useKanbanBoardModel<T extends BaseKanbanItem = BaseKanbanItem>(
+  kanban: Kanban.Kanban,
+  projection: ProjectionModel,
+  itemsAtom: Atom.Atom<T[]>,
+  registry: Registry.Registry,
+): BoardModel<ColumnStructure, T> {
+  // Source atoms: reactive reads from the kanban object; items come from the passed-in atom (e.g. AtomQuery or in-memory).
+  const arrangementAtom = useMemo(() => AtomObj.makeProperty(kanban, 'arrangement'), [kanban]);
+  const viewSnapshotAtom = useMemo(
+    () =>
+      kanban?.spec?.kind === 'view' && kanban.spec.view
+        ? AtomObj.make(kanban.spec.view)
+        : Atom.make<undefined>(() => undefined),
+    [kanban?.spec],
+  );
+
+  /**
+   * Only changes when the discriminator-relevant pivot input changes.
+   * View-variant: derived from `view.projection.pivotFieldId`.
+   * Items-variant: the kanban's `spec.pivotField` (the property name itself acts as the field id).
+   */
+  const pivotFieldIdAtom = useMemo(
+    () =>
+      Atom.make((get) => {
+        if (kanban?.spec.kind === 'items') {
+          return kanban.spec.pivotField;
+        }
+        return get(viewSnapshotAtom)?.projection?.pivotFieldId as string | undefined;
+      }),
+    [kanban?.spec, viewSnapshotAtom],
+  );
+
+  // Effective per-column ids: from kanban.arrangement.columns; empty when arrangement has no columns.
+  const effectiveByColumnAtom = useMemo(
+    () => Atom.make((get) => getOrderByColumnFromArrangement(get(arrangementAtom))),
+    [arrangementAtom],
+  );
+
+  // Column structure: depends on pivotFieldId (not full view), arrangement, and projection so columns only fire when pivot or arrangement changes.
+  const columnsAtom = useMemo(
+    () =>
+      Atom.make((get) => {
+        const pivotFieldId = get(pivotFieldIdAtom);
+        if (pivotFieldId === undefined) {
+          return [];
+        }
+
+        get(projection.fields);
+        const fieldProj = projection.tryGetFieldProjection(pivotFieldId);
+        if (!fieldProj) {
+          return [];
+        }
+
+        const selectOptions = fieldProj.props.options ?? [];
+        if (selectOptions.length === 0) {
+          return [];
+        }
+
+        const arrangement = get(arrangementAtom);
+        const order = getOrderFromArrangement(arrangement);
+        const byColumn = getOrderByColumnFromArrangement(arrangement);
+        return computeColumnStructure(order, byColumn, selectOptions);
+      }),
+    [pivotFieldIdAtom, arrangementAtom, projection],
+  );
+
+  // Per-column slice of arrangement so each column’s items atom only depends on that column’s ids.
+  const columnArrangementAtomFamily = useMemo(
+    () =>
+      Atom.family<string, Atom.Atom<ColumnStructure>>((columnValue: string) =>
+        Atom.make((get) => {
+          const byColumn = get(effectiveByColumnAtom);
+          return {
+            columnValue,
+            ids: [...(byColumn[columnValue]?.ids ?? [])],
+          };
+        }),
+      ),
+    [effectiveByColumnAtom],
+  );
+
+  // Items for a single column: filter all items by pivot field, sort by this column’s ids, then append new items.
+  const itemsAtomFamily = useMemo(
+    () =>
+      Atom.family<string, Atom.Atom<T[]>>((columnValue: string) =>
+        Atom.make((get) => {
+          const columnArr = get(columnArrangementAtomFamily(columnValue));
+          const allItems = get(itemsAtom);
+          const pivotFieldId = get(pivotFieldIdAtom);
+
+          if (pivotFieldId === undefined) {
+            return [];
+          }
+
+          // TODO(wittjosiah): Try to narrow this down further.
+          get(projection.fields);
+          const fieldProj = projection.tryGetFieldProjection(pivotFieldId);
+          if (!fieldProj) {
+            return [];
+          }
+
+          const selectOptions = fieldProj.props.options ?? [];
+          const pivotPath = fieldProj.props.property;
+          const validColumnValues = new Set(selectOptions.map((opt) => opt.id));
+          return orderItemsInColumn(allItems, columnArr.ids, columnValue, pivotPath, validColumnValues);
+        }),
+      ),
+    [columnArrangementAtomFamily, itemsAtom, pivotFieldIdAtom, projection],
+  );
+
+  return useMemo(
+    () => ({
+      getColumnId: (data) => data.columnValue,
+      getItemId: (data) => (data as T).id,
+      isColumn: (obj): obj is ColumnStructure =>
+        typeof obj === 'object' && obj !== null && 'columnValue' in obj && 'ids' in obj,
+      // TODO(wittjosiah): This should be restricted to objects of the type of the kanban view.
+      isItem: (obj): obj is T => Obj.isObject(obj),
+      columns: columnsAtom,
+      items: (column) => itemsAtomFamily(column.columnValue),
+      getColumns: () => registry.get(columnsAtom) ?? [],
+      getItems: (column) => registry.get(itemsAtomFamily(column.columnValue)) ?? [],
+    }),
+    [columnsAtom, itemsAtomFamily, registry],
+  );
+}

package/src/hooks/useKanbanColumnEventHandler.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import type { BoardModel, MosaicEventHandler, MosaicTileData } from '@dxos/react-ui-mosaic';
+import type { ProjectionModel } from '@dxos/schema';
+import { arrayMove } from '@dxos/util';
+
+import { type BaseKanbanItem, type ColumnStructure, type KanbanChangeCallback, UNCATEGORIZED_VALUE } from '#types';
+
+/**
+ * Builds the column drag-and-drop handler for the kanban board (reorder columns).
+ *
+ * @template T - Item type (extends BaseKanbanItem).
+ * @param id - Handler id.
+ * @param model - Board model for getColumns / getColumnId.
+ * @param projection - ProjectionModel for pivot field options (column order).
+ * @param pivotFieldId - Pivot field id; undefined disables drop.
+ * @param change - Callback to persist kanban.arrangement.order.
+ * @returns MosaicEventHandler for column tiles.
+ */
+export function useKanbanColumnEventHandler<T extends BaseKanbanItem>({
+  id,
+  model,
+  projection,
+  pivotFieldId,
+  change,
+}: {
+  id: string;
+  model: BoardModel<ColumnStructure, T>;
+  projection: ProjectionModel | undefined;
+  pivotFieldId: string | undefined;
+  change: KanbanChangeCallback<T>;
+}): MosaicEventHandler<ColumnStructure> {
+  return useMemo<MosaicEventHandler<ColumnStructure>>(
+    () => ({
+      id,
+      canDrop: ({ source }) => {
+        if (!projection) {
+          return false;
+        }
+        const data = source.data as ColumnStructure;
+        const columnValue = model.getColumnId(data);
+        return (
+          model.isColumn(source.data) &&
+          columnValue !== UNCATEGORIZED_VALUE &&
+          (source as MosaicTileData<ColumnStructure>).id !== UNCATEGORIZED_VALUE
+        );
+      },
+      onDrop: ({ source, target }) => {
+        if (!projection || pivotFieldId === undefined) {
+          return;
+        }
+        const sourceColumnData = source.data as ColumnStructure;
+        const sourceColumnId = model.getColumnId(sourceColumnData);
+        if (sourceColumnId === UNCATEGORIZED_VALUE) {
+          return;
+        }
+
+        // 1. Current column order from model; find source index.
+        const currentColumns = model.getColumns();
+        const sourceIndex = currentColumns.findIndex((c) => model.getColumnId(c) === sourceColumnId);
+        if (sourceIndex === -1) {
+          return;
+        }
+
+        // 2. Resolve drop target to an index in the column list.
+        let targetIndex: number;
+        if (target?.type === 'tile' || target?.type === 'placeholder') {
+          targetIndex = typeof target.location === 'number' ? Math.floor(target.location) : -1;
+        } else if (target?.type === 'container') {
+          targetIndex = currentColumns.length;
+        } else {
+          return;
+        }
+        if (targetIndex < 0) {
+          return;
+        }
+
+        // 3. New column order after move.
+        const currentColumnIds = currentColumns.map((c) => model.getColumnId(c));
+        const reorderedColumnIds = arrayMove([...currentColumnIds], sourceIndex, targetIndex);
+
+        // 4. Persist reordered options to projection (pivot field options = column order).
+        const fieldProjection = projection.getFieldProjection(pivotFieldId);
+        const currentOptions = [...(fieldProjection.props.options ?? [])];
+        const optionsInNewOrder = reorderedColumnIds
+          .map((columnId) => currentOptions.find((o) => o.id === columnId))
+          .filter((o): o is NonNullable<typeof o> => o != null);
+
+        projection.setFieldProjection({
+          ...fieldProjection,
+          props: { ...fieldProjection.props, options: optionsInNewOrder },
+        });
+
+        // Persist column order to kanban.arrangement so the board UI reflects the new order.
+        change.kanban((kanban) => {
+          kanban.arrangement.order = reorderedColumnIds.filter((columnId) => columnId !== UNCATEGORIZED_VALUE);
+        });
+      },
+    }),
+    [id, model, projection, pivotFieldId, change],
+  );
+}

package/src/hooks/useKanbanItemEventHandler.ts

@@ -0,0 +1,133 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import type { BoardModel, MosaicEventHandler, MosaicTileData } from '@dxos/react-ui-mosaic';
+
+import {
+  type ArrangedCards,
+  type BaseKanbanItem,
+  type ColumnStructure,
+  type KanbanChangeCallback,
+  UNCATEGORIZED_VALUE,
+} from '#types';
+
+function findColumn<T extends BaseKanbanItem>(
+  id: string,
+  arrangement: ArrangedCards<T>,
+): { columnValue: string; cards: T[] } | undefined {
+  return arrangement.find(({ columnValue, cards }) => columnValue === id || cards.some((card) => card.id === id));
+}
+
+/**
+ * Builds the item drag-and-drop handler for a single column (reorder and move between columns).
+ *
+ * @template T - Item type (extends BaseKanbanItem).
+ * @param column - Column structure for this tile.
+ * @param columnFieldPath - Item property path for the pivot field (used when moving to another column).
+ * @param model - Board model for getColumns / getItems.
+ * @param change - Callback to persist arrangement and item field updates.
+ * @returns MosaicEventHandler for item tiles in this column.
+ */
+export function useKanbanItemEventHandler<T extends BaseKanbanItem>({
+  column,
+  columnFieldPath,
+  model,
+  change,
+}: {
+  column: ColumnStructure;
+  columnFieldPath: string | undefined;
+  model: BoardModel<ColumnStructure, T>;
+  change: KanbanChangeCallback<T>;
+}): MosaicEventHandler<T> {
+  return useMemo<MosaicEventHandler<T>>(
+    () => ({
+      id: column.columnValue,
+      canDrop: ({ source }) => model.isItem(source.data),
+      onTake: ({ source }, cb) => {
+        void cb(source.data as T);
+      },
+      onDrop: ({ source, target }) => {
+        // 1. Snapshot current arrangement from model (read-only).
+        const columns = model.getColumns();
+        const currentArrangement: ArrangedCards<T> = columns.map((col) => ({
+          columnValue: col.columnValue,
+          cards: model.getItems(col) ?? [],
+        }));
+        const sourceColumnInSnapshot = findColumn(source.id, currentArrangement);
+        if (!sourceColumnInSnapshot) {
+          return;
+        }
+
+        // 2. Working copy to mutate, then persist.
+        const workingArrangement = currentArrangement.map((col) => ({
+          columnValue: col.columnValue,
+          cards: [...col.cards],
+        }));
+        const sourceColumnInWorking = workingArrangement.find(
+          (c) => c.columnValue === sourceColumnInSnapshot.columnValue || c.cards.some((card) => card.id === source.id),
+        );
+        const targetColumnInWorking = workingArrangement.find((c) => c.columnValue === column.columnValue);
+        if (!sourceColumnInWorking || !targetColumnInWorking) {
+          return;
+        }
+
+        // 3. Remove card from source column in working copy.
+        const sourceIndex = sourceColumnInWorking.cards.findIndex((card) => card.id === source.id);
+        if (sourceIndex === -1) {
+          return;
+        }
+        const [movedCard] = sourceColumnInWorking.cards.splice(sourceIndex, 1);
+
+        // 4. Update card's pivot field to target column value.
+        if (columnFieldPath !== undefined) {
+          const newValue =
+            targetColumnInWorking.columnValue === UNCATEGORIZED_VALUE ? undefined : targetColumnInWorking.columnValue;
+          change.setItemField(movedCard, columnFieldPath, newValue);
+        }
+
+        // 5. Compute insert index in target column, then insert.
+        const existingTargetIndex =
+          target?.type === 'tile'
+            ? targetColumnInWorking.cards.findIndex(
+                (card) => model.getItemId(card) === (target as MosaicTileData<T>).id,
+              )
+            : -1;
+        const closestEdge: 'top' | 'bottom' =
+          target?.type === 'placeholder' && typeof target.location === 'number'
+            ? target.location <= targetColumnInWorking.cards.length / 2
+              ? 'top'
+              : 'bottom'
+            : 'bottom';
+
+        let insertIndex: number;
+        if (target?.type === 'placeholder' && typeof target.location === 'number') {
+          insertIndex = Math.max(0, Math.min(targetColumnInWorking.cards.length, Math.floor(target.location)));
+        } else if (target?.type === 'container' || existingTargetIndex === -1) {
+          insertIndex = targetColumnInWorking.cards.length;
+        } else if (sourceColumnInWorking.columnValue === targetColumnInWorking.columnValue) {
+          insertIndex = closestEdge === 'bottom' ? existingTargetIndex + 1 : existingTargetIndex;
+          if (sourceIndex < existingTargetIndex) {
+            insertIndex -= 1;
+          }
+        } else {
+          insertIndex = closestEdge === 'bottom' ? existingTargetIndex + 1 : existingTargetIndex;
+        }
+        targetColumnInWorking.cards.splice(insertIndex, 0, movedCard);
+
+        // 6. Persist arrangement to kanban.
+        change.kanban((kanban) => {
+          kanban.arrangement = {
+            order: workingArrangement.map(({ columnValue }) => columnValue),
+            columns: Object.fromEntries(
+              workingArrangement.map(({ columnValue, cards }) => [columnValue, { ids: cards.map((c) => c.id) }]),
+            ),
+          };
+        });
+      },
+    }),
+    [column, columnFieldPath, model, change],
+  );
+}