@dxos/plugin-kanban 0.8.3 → 0.8.4-main.1c7ec43d41

package/src/operations/restore-card.ts

@@ -0,0 +1,21 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+
+import { RestoreCard } from './definitions';
+
+const handler: Operation.WithHandler<typeof RestoreCard> = RestoreCard.pipe(
+  Operation.withHandler(({ card }) =>
+    Effect.sync(() => {
+      const db = Obj.getDatabase(card);
+      invariant(db);
+      db.add(card);
+    }),
+  ),
+);
+
+export default handler;

package/src/playwright/board-manager.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { BoardManager as MosaicBoardManager } from '@dxos/react-ui-mosaic/playwright';
+
+export class BoardManager extends MosaicBoardManager {
+  async waitUntilReady(): Promise<void> {
+    await this.columns().first().waitFor({ state: 'visible' });
+    await this.columns().nth(2).waitFor({ state: 'visible' });
+    await this.column(1).items().first().waitFor({ state: 'visible' });
+  }
+}

package/src/playwright/playwright.config.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { defineConfig } from '@playwright/test';
+
+import { e2ePreset } from '@dxos/test-utils/playwright';
+
+export default defineConfig({
+  ...e2ePreset(import.meta.dirname),
+  // TODO(wittjosiah): Stories are slow to start up.
+  timeout: 60_000,
+  // TODO(wittjosiah): Avoid hard-coding ports.
+  webServer: {
+    command: 'pnpm storybook dev --ci --quiet --port=9011 --config-dir=.storybook',
+    port: 9011,
+    reuseExistingServer: false,
+  },
+});

package/src/playwright/smoke.spec.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Page, expect, test } from '@playwright/test';
+
+import { setupPage, storybookUrl } from '@dxos/test-utils/playwright';
+
+import { BoardManager } from './board-manager';
+
+const PORT = 9011;
+const STORY_URL = storybookUrl('plugins-plugin-kanban-containers-kanban--mutable-schema', PORT);
+
+test.describe('Kanban MutableSchema', () => {
+  let page: Page;
+  let board: BoardManager;
+
+  test.beforeEach(async ({ browser }) => {
+    // Larger viewport to avoid triggering scroll-assist behaviour on simple drag operations.
+    ({ page } = await setupPage(browser, { url: STORY_URL, viewportSize: { width: 1920, height: 1080 } }));
+    board = new BoardManager(page.locator('body'));
+    await board.waitUntilReady();
+  });
+
+  test.afterEach(async () => {
+    await page.close();
+  });
+
+  test('rearrange columns', async () => {
+    const col1Label = await board.column(1).title().textContent();
+    const col2Label = await board.column(2).title().textContent();
+    expect(col1Label).not.toBeNull();
+    expect(col2Label).not.toBeNull();
+
+    await board.column(1).dragTo(board.column(2).header());
+
+    await expect(board.column(1).title()).toHaveText(col2Label!);
+    await expect(board.column(2).title()).toHaveText(col1Label!);
+  });
+
+  test('rearrange within column', async () => {
+    // Column 0 is uncategorized (empty). Use column 1 (first status column).
+    const column = board.column(1);
+    const countBefore = await column.items().count();
+
+    const firstLabel = await column.item(0).title().textContent();
+    const secondLabel = await column.item(1).title().textContent();
+    expect(firstLabel).not.toBeNull();
+    expect(secondLabel).not.toBeNull();
+
+    // Drag first item below the second item.
+    await column.item(0).dragTo(column.item(1).locator, { x: 0, y: 200 }, 'bottom');
+
+    // Item count should stay the same.
+    await expect(column.items()).toHaveCount(countBefore);
+
+    // The first item should now be what was previously the second item.
+    await expect(column.item(0).title()).toHaveText(secondLabel!);
+
+    // The original first item should now be at index 1.
+    await expect(column.item(1).title()).toHaveText(firstLabel!);
+  });
+
+  test('drag to beginning of another column', async () => {
+    // Column 0 is uncategorized (empty). Use columns 1 and 2 (both have items).
+    const col1 = board.column(1);
+    const col2 = board.column(2);
+
+    const col1CountBefore = await col1.items().count();
+    const col2CountBefore = await col2.items().count();
+    const draggedLabel = await col1.item(0).title().textContent();
+    expect(draggedLabel).not.toBeNull();
+
+    // Drop above first item.
+    await col1.item(0).dragTo(col2.item(0).locator, { x: 0, y: -30 }, 'top');
+
+    await expect(col1.items()).toHaveCount(col1CountBefore - 1);
+    await expect(col2.items()).toHaveCount(col2CountBefore + 1);
+    await expect(col2.item(0).title()).toHaveText(draggedLabel!);
+  });
+
+  test('drag into empty column', async () => {
+    // Uncategorized is column 0 (empty); first populated column is at index 1.
+    const emptyColumn = board.column(0);
+    const sourceColumn = board.column(1);
+
+    const sourceCountBefore = await sourceColumn.items().count();
+    const draggedLabel = await sourceColumn.item(0).title().textContent();
+    expect(draggedLabel).not.toBeNull();
+
+    await sourceColumn.item(0).dragTo(emptyColumn.header(), { x: 0, y: 40 });
+
+    await expect(sourceColumn.items()).toHaveCount(sourceCountBefore - 1);
+    await expect(emptyColumn.items()).toHaveCount(1);
+    await expect(emptyColumn.item(0).title()).toHaveText(draggedLabel!);
+  });
+
+  test('create new item', async () => {
+    // Use first populated column.
+    const column = board.column(1);
+    const countBefore = await column.items().count();
+
+    await column.addItem();
+
+    await expect(column.items()).toHaveCount(countBefore + 1);
+  });
+});

package/src/testing/KanbanCardTileSimple.tsx

@@ -0,0 +1,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { forwardRef, useCallback, useMemo, useState } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { Card, Toolbar, useTranslation } from '@dxos/react-ui';
+import { Menu, createMenuAction } from '@dxos/react-ui-menu';
+import { Focus, Mosaic, useBoard } from '@dxos/react-ui-mosaic';
+
+import { type KanbanCardProps, useKanbanBoard } from '#components';
+import { meta } from '#meta';
+
+const KANBAN_CARD_TILE_SIMPLE_NAME = 'KanbanCardTileSimple';
+
+/**
+ * Card tile without Surface; for stories and tests when plugin manager is not available.
+ */
+export const KanbanCardTileSimple = forwardRef<HTMLDivElement, KanbanCardProps>(
+  ({ data, location, debug }, forwardedRef) => {
+    const { t } = useTranslation(meta.id);
+    const { model } = useBoard(KANBAN_CARD_TILE_SIMPLE_NAME);
+    const { onCardRemove } = useKanbanBoard(KANBAN_CARD_TILE_SIMPLE_NAME);
+    const [dragHandle, setDragHandle] = useState<HTMLButtonElement | null>(null);
+    const dragHandleRef = useCallback((el: HTMLButtonElement | null) => setDragHandle(el), []);
+
+    const menuItems = useMemo(
+      () =>
+        onCardRemove
+          ? [
+              createMenuAction('remove', () => onCardRemove(data), {
+                label: t('remove-card.label'),
+                icon: 'ph--trash--regular',
+              }),
+            ]
+          : [],
+      [onCardRemove, data, t],
+    );
+
+    return (
+      <Menu.Root>
+        <Mosaic.Tile
+          asChild
+          id={model.getItemId(data)}
+          data={data}
+          location={location}
+          debug={debug}
+          dragHandle={dragHandle}
+        >
+          <Focus.Item asChild>
+            <Card.Root ref={forwardedRef} data-testid='board-item'>
+              <Card.Toolbar>
+                <Card.DragHandle ref={dragHandleRef} />
+                <Card.Title>{Obj.getLabel(data)}</Card.Title>
+                {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
+                <Menu.Trigger asChild disabled={!menuItems?.length}>
+                  <Toolbar.IconButton
+                    iconOnly
+                    variant='ghost'
+                    icon='ph--dots-three-vertical--regular'
+                    label={t('action-menu.label')}
+                  />
+                </Menu.Trigger>
+                <Menu.Content items={menuItems} />
+              </Card.Toolbar>
+              <Card.Content>
+                <Card.Section>
+                  <pre className='p-2 text-xs text-description whitespace-pre-wrap'>
+                    {JSON.stringify(data, null, 2)}
+                  </pre>
+                </Card.Section>
+              </Card.Content>
+            </Card.Root>
+          </Focus.Item>
+        </Mosaic.Tile>
+      </Menu.Root>
+    );
+  },
+);
+
+KanbanCardTileSimple.displayName = KANBAN_CARD_TILE_SIMPLE_NAME;

package/src/testing/index.ts

@@ -1,6 +1,5 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-export * from './kanban-manager';
-export * from './initialize-kanban';
+export { KanbanCardTileSimple } from './KanbanCardTileSimple';

package/src/translations.ts

@@ -3,34 +3,42 @@
 //
 
 import { Type } from '@dxos/echo';
-import { KanbanType } from '@dxos/react-ui-kanban';
+import { type Resource } from '@dxos/react-ui';
 
-import { KANBAN_PLUGIN } from './meta';
+import { meta } from '#meta';
+import { Kanban } from '#types';
 
-export default [
+export const translations = [
   {
     'en-US': {
-      [Type.getTypename(KanbanType)]: {
-        'typename label': 'Kanban',
-        'typename label_zero': 'Kanbans',
-        'typename label_one': 'Kanban',
-        'typename label_other': 'Kanbans',
-        'object name placeholder': 'New kanban',
+      [Type.getTypename(Kanban.Kanban)]: {
+        'typename.label': 'Kanban',
+        'typename.label_zero': 'Kanbans',
+        'typename.label_one': 'Kanban',
+        'typename.label_other': 'Kanbans',
+        'object-name.placeholder': 'New kanban',
+        'add-object.label': 'Add kanban',
+        'rename-object.label': 'Rename kanban',
+        'delete-object.label': 'Delete kanban',
+        'object-deleted.label': 'Kanban deleted',
       },
-      [KANBAN_PLUGIN]: {
-        'plugin name': 'Kanban',
-        'kanban title label': 'Title',
-        'column title label': 'Column title',
-        'column title placeholder': 'New column',
-        'item title label': 'Item title',
-        'item title placeholder': 'New item',
-        'add column label': 'Add column',
-        'add item label': 'Add card',
-        'delete column label': 'Delete column',
-        'delete item label': 'Delete card',
-        'card field deleted label': 'Card field deleted',
-        'card deleted label': 'Card deleted',
+      [meta.id]: {
+        'action-menu.label': 'Actions',
+        'plugin.name': 'Kanban',
+        'kanban-title.label': 'Title',
+        'column-title.label': 'Column title',
+        'column-title.placeholder': 'New column',
+        'add-column.label': 'Add column',
+        'add-card.label': 'Add card',
+        'new-column-name.label': 'New column name',
+        'remove-card.label': 'Remove card',
+        'remove-empty-column.label': 'Remove empty column',
+        'column-drag-handle.label': 'Drag to rearrange',
+        'delete-column.label': 'Delete column',
+        'card-field-deleted.label': 'Card field deleted',
+        'card-deleted.label': 'Card deleted',
+        'select-pivot.placeholder': 'Select a pivot column in board settings to display columns.',
       },
     },
   },
-];
+] as const satisfies Resource[];

package/src/types/Kanban.ts

@@ -0,0 +1,151 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Obj, Ref, Type } from '@dxos/echo';
+import { View } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
+import { ViewAnnotation } from '@dxos/schema';
+
+/**
+ * Per-column entry: ordered card ids plus an optional `hidden` flag that
+ * removes the column from the rendered board (and from the model's column
+ * list). Today only the uncategorized column is exposed in settings, but
+ * the data structure supports per-column hiding generally.
+ */
+const ArrangementColumnEntry = Schema.Struct({
+  ids: Schema.Array(Obj.ID),
+  hidden: Schema.Boolean.pipe(Schema.optional),
+});
+
+/** Keyed by columnValue. */
+const ArrangementColumns = Schema.Record({
+  key: Schema.String,
+  value: ArrangementColumnEntry,
+}).pipe(FormInputAnnotation.set(false));
+
+/** Column order and per-column card ids. */
+export const Arrangement = Schema.Struct({
+  order: Schema.Array(Schema.String).pipe(FormInputAnnotation.set(false)),
+  columns: ArrangementColumns,
+}).pipe(FormInputAnnotation.set(false));
+
+export type Arrangement = Schema.Schema.Type<typeof Arrangement>;
+
+/**
+ * v1: pre-existing Kanban shape. Retained as the source for the v1→v2 migration.
+ */
+export const KanbanV1 = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
+  arrangement: Arrangement,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.kanban',
+    version: '0.1.0',
+  }),
+);
+
+//
+// v2 — `spec` is a discriminated union of how items are sourced.
+//
+// Mirrors the canonical DXOS pattern (see `Trigger.Spec` in
+// `@dxos/functions/src/types/Trigger.ts` and `Sequence.Source` in
+// `@dxos/plugin-zen`): the `Type.object` schema is a flat `Schema.Struct`,
+// and the discriminated union lives one level down as a single field whose
+// variants are tagged with a `kind` literal.
+//
+
+/** View-variant: items come from running the View's query (the original behaviour). */
+export const KanbanViewSpec = Schema.Struct({
+  kind: Schema.Literal('view').pipe(FormInputAnnotation.set(false)),
+  view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
+});
+export type KanbanViewSpec = Schema.Schema.Type<typeof KanbanViewSpec>;
+
+/** Items-variant: kanban owns its items as an explicit ref array (used by externally-synced kanbans). */
+export const KanbanItemsSpec = Schema.Struct({
+  kind: Schema.Literal('items').pipe(FormInputAnnotation.set(false)),
+  /** Property path on each item that drives column membership (e.g. `'listName'`). */
+  pivotField: Schema.String,
+  /** Items owned directly by the kanban. */
+  items: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(FormInputAnnotation.set(false)),
+});
+export type KanbanItemsSpec = Schema.Schema.Type<typeof KanbanItemsSpec>;
+
+/** Discriminated union of source specs. Distinguished by `kind`. */
+export const KanbanSpec = Schema.Union(KanbanViewSpec, KanbanItemsSpec);
+export type KanbanSpec = Schema.Schema.Type<typeof KanbanSpec>;
+
+export const Kanban = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  arrangement: Arrangement,
+  /** How this kanban sources its items. Discriminated by `spec.kind`. */
+  spec: KanbanSpec,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.kanban',
+    version: '0.2.0',
+  }),
+  LabelAnnotation.set(['name']),
+  ViewAnnotation.set(['spec', 'view']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--kanban--regular',
+    hue: 'green',
+  }),
+);
+
+/** Instance type; narrow on `kanban.spec.kind` (or use the guards below). */
+export interface Kanban extends Schema.Schema.Type<typeof Kanban> {}
+
+/** Narrowed view-variant kanban. */
+export type KanbanView = Kanban & { spec: KanbanViewSpec };
+
+/** Narrowed items-variant kanban. */
+export type KanbanItems = Kanban & { spec: KanbanItemsSpec };
+
+export const isKanbanView = (kanban: Kanban): kanban is KanbanView => kanban.spec.kind === 'view';
+export const isKanbanItems = (kanban: Kanban): kanban is KanbanItems => kanban.spec.kind === 'items';
+
+type MakeViewProps = {
+  name?: string;
+  view: View.View;
+  arrangement?: Arrangement;
+};
+
+/**
+ * Make a view-variant kanban (items sourced via the View's query).
+ */
+export const make = (props: MakeViewProps): Kanban => {
+  const { name, view, arrangement } = props;
+  const order = arrangement?.order ?? [];
+  const columns = arrangement?.columns ?? {};
+  return Obj.make(Kanban, {
+    name,
+    arrangement: { order, columns },
+    spec: { kind: 'view' as const, view: Ref.make(view) },
+  });
+};
+
+type MakeItemsProps = {
+  name?: string;
+  arrangement?: Arrangement;
+  pivotField: string;
+  items?: ReadonlyArray<Ref.Ref<Obj.Unknown>>;
+};
+
+/**
+ * Make an items-variant kanban (items list owned by the kanban itself, e.g. populated by a sync integration).
+ */
+export const makeItems = (props: MakeItemsProps): Kanban => {
+  const { name, arrangement, pivotField, items = [] } = props;
+  const order = arrangement?.order ?? [];
+  const columns = arrangement?.columns ?? {};
+  return Obj.make(Kanban, {
+    name,
+    arrangement: { order, columns },
+    spec: { kind: 'items' as const, pivotField, items },
+  });
+};

package/src/types/constants.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const UNCATEGORIZED_VALUE = '__uncategorized__' as const;
+export const UNCATEGORIZED_ATTRIBUTES = {
+  title: 'Uncategorized',
+  color: 'neutral',
+} as const;

package/src/types/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './constants';
+export * as Kanban from './Kanban';
+export * from './schema';
+export type * from './types';

package/src/types/migrations.test.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { defineObjectMigration } from '@dxos/client/echo';
+import { Filter, JsonSchema, Obj, Query, Ref, Type, View } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { ViewModel } from '@dxos/schema';
+
+import { Kanban } from './Kanban';
+import { KanbanV1 } from './Kanban';
+
+const TestCardSchema = Schema.Struct({ id: Schema.String }).pipe(
+  Type.object({ typename: 'com.example/TestCard', version: '0.1.0' }),
+);
+
+/**
+ * v0.1.0 → v0.2.0 migration: nests `view` under `spec: { kind: 'view', view }`.
+ *
+ * Mirrors the migration registered in `capabilities/migrations.ts`. Running it
+ * here against a real ECHO database verifies that the transform produces a
+ * v0.2.0-shaped object that's queryable as `Kanban.Kanban`.
+ */
+describe('Kanban migration v1 → v2', () => {
+  let builder: EchoTestBuilder;
+
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  const migration = defineObjectMigration({
+    from: KanbanV1,
+    to: Kanban,
+    transform: async (from) => ({
+      name: from.name,
+      arrangement: from.arrangement,
+      spec: { kind: 'view' as const, view: from.view },
+    }),
+    onMigration: async () => {},
+  });
+
+  test('migrates a v1 Kanban into the v2 view-variant shape', async ({ expect }) => {
+    const { db, graph } = await builder.createDatabase();
+    await graph.schemaRegistry.register([KanbanV1, Kanban, View.View]);
+
+    // Build a real View object so the v1 Kanban has a valid ref to migrate.
+    const view = ViewModel.make({
+      query: Query.select(Filter.type(TestCardSchema)),
+      jsonSchema: JsonSchema.toJsonSchema(TestCardSchema),
+    });
+    db.add(view);
+
+    db.add(
+      Obj.make(KanbanV1, {
+        name: 'My Board',
+        view: Ref.make(view),
+        arrangement: { order: ['todo'], columns: { todo: { ids: [] } } },
+      }),
+    );
+    await db.flush();
+
+    await db.runMigrations([migration]);
+
+    const results = await db.query(Filter.type(Kanban)).run();
+    expect(results).toHaveLength(1);
+
+    const migrated = results[0];
+    expect(migrated.name).toBe('My Board');
+    expect(migrated.arrangement.order).toEqual(['todo']);
+    expect(migrated.spec.kind).toBe('view');
+    if (migrated.spec.kind === 'view') {
+      expect(migrated.spec.view.dxn.toString()).toBe(Ref.make(view).dxn.toString());
+    }
+    expect(Type.getVersion(Obj.getSchema(migrated)!)).toBe('0.2.0');
+  });
+});

package/src/types/schema.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { TypeInputOptionsAnnotation } from '@dxos/plugin-space/types';
+
+/**
+ * Kanban data model.
+ * A Kanban board is a collection of columns, each of which contains a collection of items.
+ * The layout of columns and items is controlled by models.
+ * The underlying data model may be represented by direct object relationships
+ * (e.g., a column object containing an array of ordered items) or projections constructed
+ * by the model (e.g., a query of items based on metadata within a column object).
+ */
+
+// TODO(wittjosiah): Factor out?
+export const PivotColumnAnnotationId = Symbol.for('@dxos/plugin-kanban/annotation/PivotColumn');
+
+/**
+ * Settings common to every Kanban (view or items). Rendered as form fields
+ * by `KanbanSettings`.
+ */
+export const KanbanSettingsSchema = Schema.Struct({
+  hideUncategorized: Schema.Boolean.annotations({
+    title: 'Hide uncategorized column',
+    description: 'When enabled, items without a pivot value won’t be shown as a column.',
+  }).pipe(Schema.optional),
+});
+
+/**
+ * Settings for view-variant Kanbans only. Spreads {@link KanbanSettingsSchema}'s
+ * fields and adds a column-field picker that binds the View’s pivot field.
+ * Items-variant kanbans use a hardcoded `spec.pivotField` and don’t expose
+ * this control.
+ */
+export const KanbanViewSettingsSchema = Schema.Struct({
+  columnFieldId: Schema.String.annotations({
+    title: 'Column field',
+  }),
+  ...KanbanSettingsSchema.fields,
+});
+
+export const CreateKanbanSchema = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  // TODO(wittjosiah): This should be a query input instead.
+  typename: Schema.String.pipe(
+    Schema.annotations({ title: 'Select card type' }),
+    TypeInputOptionsAnnotation.set({
+      location: ['database', 'runtime'],
+      kind: ['user'],
+    }),
+    Schema.optional,
+  ),
+  initialPivotColumn: Schema.optional(
+    Schema.String.annotations({
+      [PivotColumnAnnotationId]: true,
+      title: 'Pivot column',
+    }),
+  ),
+});

package/src/types/types.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Obj } from '@dxos/echo';
+
+import { type Kanban } from './Kanban';
+
+export type Location = {
+  idx?: number;
+};
+
+/** Snapshot shape used when reading kanban arrangement from atoms. */
+export type KanbanArrangementSnapshot = Kanban | Obj.Snapshot<Kanban>;
+
+/** Minimal item shape for arrangement; Obj.Unknown satisfies this. */
+export type BaseKanbanItem = { id: string };
+
+/** Column structure without cards; used for board model column type and derived atoms. */
+export type ColumnStructure = {
+  columnValue: string;
+  ids: string[];
+};
+
+export type KanbanColumn<T extends BaseKanbanItem = BaseKanbanItem> = {
+  columnValue: string;
+  cards: T[];
+};
+
+export type ArrangedCards<T extends BaseKanbanItem = BaseKanbanItem> = KanbanColumn<T>[];
+
+/**
+ * Callback type for wrapping mutations in Obj.update().
+ * Contains separate callbacks for kanban object and item mutations.
+ */
+export type KanbanChangeCallback<T extends BaseKanbanItem> = {
+  /** Callback to wrap kanban object mutations. */
+  kanban: (mutate: (mutableKanban: Obj.Mutable<Kanban>) => void) => void;
+
+  /** Sets a field on an item, wrapping in Obj.update() if needed. */
+  setItemField: (item: T, field: string, value: unknown) => void;
+};