@dxos/plugin-kanban 0.8.4-main.c85a9c8dae → 0.8.4-main.d9fc60f731

package/src/hooks/{useKanbanBoardModel.test.ts → useKanbanBoardModel.browser.test.ts}

@@ -7,13 +7,12 @@ 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 { DXN, Filter, JsonSchema, Obj, Query, Type, type View } from '@dxos/echo';
 import { Format, FormatAnnotation, PropertyMetaAnnotationId } from '@dxos/echo/internal';
-import { ObjectId } from '@dxos/keys';
+import { EntityId } from '@dxos/keys';
 import { ProjectionModel, ViewModel, createDirectChangeCallback } from '@dxos/schema';
 
-import { Kanban } from '../types';
+import { Kanban } from '#types';
 
 import { useKanbanBoardModel } from './useKanbanBoardModel';
 
@@ -36,14 +35,9 @@ const KanbanTaskSchema = Schema.Struct({
     }),
     Schema.optional,
   ),
-}).pipe(
-  Type.object({
-    typename: 'example.com/type/KanbanTask',
-    version: '0.1.0',
-  }),
-);
+}).pipe(Type.makeObject(DXN.make('com.example.type.kanbanTask', '0.1.0')));
 
-type KanbanTask = Schema.Schema.Type<typeof KanbanTaskSchema>;
+type KanbanTask = Type.InstanceType<typeof KanbanTaskSchema>;
 
 describe('useKanbanBoardModel', () => {
   let registry: Registry.Registry;
@@ -146,7 +140,7 @@ describe('useKanbanBoardModel', () => {
     expect(orderBefore).toEqual(['__uncategorized__', 'a', 'b']);
 
     act(() => {
-      Obj.change(kanban, (kanban) => {
+      Obj.update(kanban, (kanban) => {
         kanban.arrangement.order = ['b', 'a'];
       });
     });
@@ -160,15 +154,15 @@ describe('useKanbanBoardModel', () => {
 
   test('getItems returns items in column ordered by arrangement ids', ({ expect }) => {
     const item1 = Obj.make(KanbanTaskSchema, {
-      id: ObjectId.random(),
+      id: EntityId.random(),
       status: 'a',
     });
     const item2 = Obj.make(KanbanTaskSchema, {
-      id: ObjectId.random(),
+      id: EntityId.random(),
       status: 'a',
     });
     const item3 = Obj.make(KanbanTaskSchema, {
-      id: ObjectId.random(),
+      id: EntityId.random(),
       status: 'a',
     });
     const items: KanbanTask[] = [item1, item2, item3];
@@ -187,7 +181,7 @@ describe('useKanbanBoardModel', () => {
     });
 
     act(() => {
-      Obj.change(kanban, (kanban) => {
+      Obj.update(kanban, (kanban) => {
         kanban.arrangement.columns['a'] = {
           ids: [item3.id, item1.id, item2.id],
         };
@@ -201,11 +195,11 @@ describe('useKanbanBoardModel', () => {
 
   test('subscribing to one column items atom does not fire when another column changes', ({ expect }) => {
     const itemA = Obj.make(KanbanTaskSchema, {
-      id: ObjectId.random(),
+      id: EntityId.random(),
       status: 'a',
     });
     const itemB = Obj.make(KanbanTaskSchema, {
-      id: ObjectId.random(),
+      id: EntityId.random(),
       status: 'b',
     });
     const items: KanbanTask[] = [itemA, itemB];
@@ -225,7 +219,7 @@ describe('useKanbanBoardModel', () => {
     });
 
     act(() => {
-      Obj.change(kanban, (kanban) => {
+      Obj.update(kanban, (kanban) => {
         kanban.arrangement.columns['b'] = { ids: [itemB.id] };
       });
     });

package/src/hooks/useKanbanBoardModel.ts

@@ -10,7 +10,8 @@ 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 { type BaseKanbanItem, type ColumnStructure, type Kanban } from '#types';
+
 import {
   computeColumnStructure,
   getOrderByColumnFromArrangement,
@@ -37,14 +38,27 @@ export function useKanbanBoardModel<T extends BaseKanbanItem = BaseKanbanItem>(
   // 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?.view ? AtomObj.make(kanban.view) : Atom.make<undefined>(() => undefined)),
-    [kanban?.view],
+    () =>
+      kanban?.spec?.kind === 'view' && kanban.spec.view
+        ? AtomObj.make(kanban.spec.view)
+        : Atom.make<undefined>(() => undefined),
+    [kanban?.spec],
   );
 
-  /** Only changes when view.projection.pivotFieldId changes; keeps columns from firing on other view updates. */
+  /**
+   * 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) => get(viewSnapshotAtom)?.projection?.pivotFieldId as string | undefined),
-    [viewSnapshotAtom],
+    () =>
+      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.

package/src/hooks/useKanbanColumnEventHandler.ts

@@ -8,7 +8,7 @@ import type { BoardModel, MosaicEventHandler, MosaicTileData } from '@dxos/react
 import type { ProjectionModel } from '@dxos/schema';
 import { arrayMove } from '@dxos/util';
 
-import { type BaseKanbanItem, type ColumnStructure, type KanbanChangeCallback, UNCATEGORIZED_VALUE } from '../types';
+import { type BaseKanbanItem, type ColumnStructure, type KanbanChangeCallback, UNCATEGORIZED_VALUE } from '#types';
 
 /**
  * Builds the column drag-and-drop handler for the kanban board (reorder columns).

package/src/hooks/useKanbanItemEventHandler.ts

@@ -12,7 +12,7 @@ import {
   type ColumnStructure,
   type KanbanChangeCallback,
   UNCATEGORIZED_VALUE,
-} from '../types';
+} from '#types';
 
 function findColumn<T extends BaseKanbanItem>(
   id: string,

package/src/hooks/useProjectionModel.ts

@@ -10,7 +10,7 @@ import { log } from '@dxos/log';
 import { useAsyncEffect } from '@dxos/react-ui';
 import { ProjectionModel, createEchoChangeCallback } from '@dxos/schema';
 
-import { type Kanban } from '../types';
+import { type Kanban } from '#types';
 
 /**
  * Loads the kanban view and builds a ProjectionModel for field projections and pivot.
@@ -30,17 +30,17 @@ export const useProjectionModel = <S extends Type.AnyEntity>(
 
   useAsyncEffect(
     async (controller) => {
-      if (!schema || !kanban) {
+      if (!schema || !kanban || kanban.spec.kind !== 'view') {
         return;
       }
       try {
-        const view = await kanban.view.load();
+        const view = await kanban.spec.view.load();
         if (controller.signal.aborted) {
           return;
         }
 
-        const jsonSchema = Type.isMutable(schema) ? schema.jsonSchema : JsonSchema.toJsonSchema(schema);
-        const change = createEchoChangeCallback(view, Type.isMutable(schema) ? schema : undefined);
+        const jsonSchema = Type.getDatabase(schema) != null ? schema.jsonSchema : JsonSchema.toJsonSchema(schema);
+        const change = createEchoChangeCallback(view, Type.getDatabase(schema) != null ? schema : undefined);
 
         const projection = new ProjectionModel({ registry, view, baseSchema: jsonSchema, change });
         projection.normalizeView();

package/src/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './blueprints';
 export * from './meta';
-
-export * from './KanbanPlugin';
+export * from './operations';
+export * from './types';

package/src/meta.ts

@@ -2,18 +2,35 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Plugin } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/echo';
 import { trim } from '@dxos/util';
 
-export const meta: Plugin.Meta = {
-  id: 'dxos.org/plugin/kanban',
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.kanban'),
   name: 'Kanban',
+  author: 'DXOS',
   description: trim`
     Visual project management using customizable kanban boards to track workflow progress.
-    Organize table data into columns, drag and drop items between stages, and trigger automations based on status changes.
+    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, getTypenameFromQuery } 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.getTypename(t) === getTypenameFromQuery(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, getTypenameFromQuery } 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.getTypename(t) === getTypenameFromQuery(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/smoke.spec.ts

@@ -49,7 +49,7 @@ test.describe('Kanban MutableSchema', () => {
     expect(secondLabel).not.toBeNull();
 
     // Drag first item below the second item.
-    await column.item(0).dragTo(column.item(1).locator, { x: 0, y: 200 });
+    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);
@@ -71,8 +71,8 @@ test.describe('Kanban MutableSchema', () => {
     const draggedLabel = await col1.item(0).title().textContent();
     expect(draggedLabel).not.toBeNull();
 
-    // Drop above first item. Kanban cards are taller; use larger negative y so we land in top half.
-    await col1.item(0).dragTo(col2.item(0).locator, { x: 0, y: -30 });
+    // 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);

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

@@ -9,12 +9,14 @@ 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';
+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. */
+/**
+ * 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);
@@ -28,7 +30,7 @@ export const KanbanCardTileSimple = forwardRef<HTMLDivElement, KanbanCardProps>(
         onCardRemove
           ? [
               createMenuAction('remove', () => onCardRemove(data), {
-                label: t('remove card label'),
+                label: t('remove-card.label'),
                 icon: 'ph--trash--regular',
               }),
             ]
@@ -37,18 +39,18 @@ export const KanbanCardTileSimple = forwardRef<HTMLDivElement, KanbanCardProps>(
     );
 
     return (
-      <Mosaic.Tile
-        asChild
-        id={model.getItemId(data)}
-        data={data}
-        location={location}
-        debug={debug}
-        dragHandle={dragHandle}
-      >
-        <Focus.Group asChild>
-          <Menu.Root>
+      <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.Header>
                 <Card.DragHandle ref={dragHandleRef} />
                 <Card.Title>{Obj.getLabel(data)}</Card.Title>
                 {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
@@ -57,18 +59,22 @@ export const KanbanCardTileSimple = forwardRef<HTMLDivElement, KanbanCardProps>(
                     iconOnly
                     variant='ghost'
                     icon='ph--dots-three-vertical--regular'
-                    label={t('action menu label')}
+                    label={t('action-menu.label')}
                   />
                 </Menu.Trigger>
                 <Menu.Content items={menuItems} />
-              </Card.Toolbar>
-              <Card.Content>
-                <div className='p-2 text-sm text-fg'>{Obj.getLabel(data)}</div>
-              </Card.Content>
+              </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>
-          </Menu.Root>
-        </Focus.Group>
-      </Mosaic.Tile>
+          </Focus.Item>
+        </Mosaic.Tile>
+      </Menu.Root>
     );
   },
 );

package/src/translations.ts

@@ -5,38 +5,39 @@
 import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
-import { Kanban } from './types';
+import { meta } from '#meta';
+import { Kanban } from '#types';
 
 export const translations = [
   {
     'en-US': {
       [Type.getTypename(Kanban.Kanban)]: {
-        'typename label': 'Kanban',
-        'typename label_zero': 'Kanbans',
-        'typename label_one': 'Kanban',
-        'typename label_other': 'Kanbans',
-        'object name placeholder': 'New kanban',
-        'rename object label': 'Rename kanban',
-        'delete object label': 'Delete kanban',
-        'object deleted label': 'Kanban deleted',
+        '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]: {
-        '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.',
+        '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.',
       },
     },
   },