@dxos/plugin-kanban 0.8.4-main.fd6878d → 0.9.0

package/src/meta.ts

@@ -2,16 +2,35 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/echo';
+import { trim } from '@dxos/util';
 
-export const KANBAN_PLUGIN = 'dxos.org/plugin/kanban';
-
-export const meta: PluginMeta = {
-  id: KANBAN_PLUGIN,
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.kanban'),
   name: 'Kanban',
-  description:
-    'Kanban allows you to explore Table data in sorted columns defined by your custom schema. You can use Kanbans to track progress or trigger custom automations when cards are moved from one state to another.',
+  author: 'DXOS',
+  description: trim`
+    Visual project management using customizable kanban boards to track workflow progress.
+    Organize any ECHO type into drag-and-drop columns defined by a single-select field, move cards
+    between stages, and reorder both columns and cards — all changes are persisted to ECHO and
+    replicated to collaborators in real time.
+
+    Kanban boards come in two variants: view-variant boards source their cards through a linked
+    View query (any ECHO type can be pivoted on a single-select field), while items-variant boards
+    own their cards explicitly and are used by external sync integrations such as Linear or GitHub.
+    Both variants share the same arrangement storage and drag-and-drop mechanics.
+
+    Board settings let users choose which single-select field drives the column layout and
+    optionally hide the uncategorized column for items that have no pivot value.
+    Field-level undo support allows deleted card fields to be restored without data loss.
+
+    The plugin contributes a Kanban blueprint that exposes board creation and card management
+    to AI agents, enabling automated project tracking workflows.
+  `,
   icon: 'ph--kanban--regular',
+  iconHue: 'green',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-kanban',
+  spec: 'PLUGIN.mdl',
   screenshots: ['https://dxos.network/plugin-details-kanban-dark.png'],
-};
+});

package/src/operations/delete-card-field.ts

@@ -0,0 +1,42 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Obj, Type } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { ProjectionModel, createEchoChangeCallback, getTypeURIFromQuery } from '@dxos/schema';
+
+import { KanbanOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof KanbanOperation.DeleteCardField> = KanbanOperation.DeleteCardField.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ view, fieldId }) {
+      const registry = yield* Capability.get(Capabilities.AtomRegistry);
+      const db = Obj.getDatabase(view);
+      invariant(db, 'Database not found');
+      const types = yield* Effect.sync(() => db.graph.registry.list().filter(Type.isType));
+      const schema = types.find((t) => Type.getURI(t) === getTypeURIFromQuery(view.query.ast));
+      invariant(schema, 'Schema not found');
+
+      invariant(Type.isType(schema), 'expected stored Type.Type for card schema');
+      const projection = new ProjectionModel({
+        registry,
+        view,
+        baseSchema: schema.jsonSchema,
+        change: createEchoChangeCallback(view, schema),
+      });
+
+      const result = projection.deleteFieldProjection(fieldId);
+
+      return {
+        field: result.deleted.field,
+        props: result.deleted.props,
+        index: result.index,
+      };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/delete-card.ts

@@ -0,0 +1,23 @@
+// 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 { KanbanOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof KanbanOperation.DeleteCard> = KanbanOperation.DeleteCard.pipe(
+  Operation.withHandler(({ card }) =>
+    Effect.sync(() => {
+      const db = Obj.getDatabase(card);
+      invariant(db);
+      db.remove(card);
+
+      return { card };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2025 DXOS.org
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const KanbanOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./delete-card'),
+  () => import('./delete-card-field'),
+  () => import('./restore-card'),
+  () => import('./restore-card-field'),
+);

package/src/operations/restore-card-field.ts

@@ -0,0 +1,36 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Obj, Type } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { ProjectionModel, createEchoChangeCallback, getTypeURIFromQuery } from '@dxos/schema';
+
+import { KanbanOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof KanbanOperation.RestoreCardField> = KanbanOperation.RestoreCardField.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ view, field, props, index }) {
+      const registry = yield* Capability.get(Capabilities.AtomRegistry);
+      const db = Obj.getDatabase(view);
+      invariant(db, 'Database not found');
+      const types = db.graph.registry.list().filter(Type.isType);
+      const type = types.find((t) => Type.getURI(t) === getTypeURIFromQuery(view.query.ast));
+      invariant(type, 'Schema not found');
+
+      invariant(Type.isType(type), 'expected stored Type.Type for card schema');
+      const projection = new ProjectionModel({
+        registry,
+        view,
+        baseSchema: type.jsonSchema,
+        change: createEchoChangeCallback(view, type),
+      });
+
+      projection.setFieldProjection({ field, props }, index);
+    }),
+  ),
+);
+
+export default handler;

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 { KanbanOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof KanbanOperation.RestoreCard> = KanbanOperation.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/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const KanbanPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { KanbanOperationHandlerSet } from './operations';

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.Header>
+                <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.Header>
+              <Card.Body>
+                <Card.Row fullWidth>
+                  <pre className='p-2 text-xs text-description whitespace-pre-wrap'>
+                    {JSON.stringify(data, null, 2)}
+                  </pre>
+                </Card.Row>
+              </Card.Body>
+            </Card.Root>
+          </Focus.Item>
+        </Mosaic.Tile>
+      </Menu.Root>
+    );
+  },
+);
+
+KanbanCardTileSimple.displayName = KANBAN_CARD_TILE_SIMPLE_NAME;

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { KanbanCardTileSimple } from './KanbanCardTileSimple';

package/src/translations.ts

@@ -2,34 +2,42 @@
 // Copyright 2023 DXOS.org
 //
 
+import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
-import { KanbanView } from '@dxos/react-ui-kanban';
 
-import { meta } from './meta';
+import { meta } from '#meta';
+import { Kanban } from '#types';
 
 export const translations = [
   {
     'en-US': {
-      [KanbanView.typename]: {
-        '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',
       },
       [meta.id]: {
-        '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',
+        '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.',
       },
     },
   },

package/src/types/Kanban.ts

@@ -0,0 +1,134 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+// QueryAST is referenced indirectly through `Type.InstanceType<typeof ...Schema>`
+// (Ref.Ref(View.View) → View.View → QueryAST.Query) in the emitted .d.ts; the
+// namespace import keeps the inferred types portable.
+// eslint-disable-next-line unused-imports/no-unused-imports
+import { DXN, Annotation, Obj, QueryAST, Ref, Type, View } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
+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>;
+
+//
+// Mirrors the canonical DXOS pattern (see `Trigger.Spec` in
+// `@dxos/functions/src/types/Trigger.ts` and `Sequence.Source` in
+// `@dxos/plugin-zen`): the `Type.makeObject` 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(
+  LabelAnnotation.set(['name']),
+  ViewAnnotation.set(['spec', 'view']),
+  Annotation.IconAnnotation.set({ icon: 'ph--kanban--regular', hue: 'green' }),
+  Type.makeObject(DXN.make('org.dxos.type.kanban', '0.2.0')),
+);
+
+/**
+ * Instance type; narrow on `kanban.spec.kind` (or use the guards below).
+ */
+export interface Kanban extends Type.InstanceType<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 },
+  });
+};