@dxos/plugin-kanban 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/types/KanbanOperation.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { View } from '@dxos/echo';
+
+import { meta } from '#meta';
+
+const KANBAN_OPERATION = `${meta.id}.operation`;
+
+export const DeleteCardFieldOutput = Schema.Struct({
+  field: View.FieldSchema.annotations({ description: 'The deleted field schema.' }),
+  props: Schema.Any.annotations({ description: 'The deleted field properties.' }),
+  index: Schema.Number.annotations({ description: 'The index the field was at.' }),
+});
+
+export type DeleteCardFieldOutput = Schema.Schema.Type<typeof DeleteCardFieldOutput>;
+
+export const DeleteCardField = Operation.make({
+  meta: { key: `${KANBAN_OPERATION}.delete-card-field`, name: 'Delete Card Field' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    view: View.View,
+    fieldId: Schema.String,
+  }),
+  output: DeleteCardFieldOutput,
+});
+
+export const DeleteCardOutput = Schema.Struct({
+  card: Schema.Any.annotations({ description: 'The deleted card.' }),
+});
+
+export type DeleteCardOutput = Schema.Schema.Type<typeof DeleteCardOutput>;
+
+export const DeleteCard = Operation.make({
+  meta: { key: `${KANBAN_OPERATION}.delete-card`, name: 'Delete Card' },
+  input: Schema.Struct({
+    card: Schema.Any,
+  }),
+  output: DeleteCardOutput,
+});
+
+export const RestoreCardField = Operation.make({
+  meta: { key: `${KANBAN_OPERATION}.restore-card-field`, name: 'Restore Card Field' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    view: View.View.annotations({ description: 'The view to restore the field to.' }),
+    field: View.FieldSchema.annotations({ description: 'The field schema to restore.' }),
+    props: Schema.Any.annotations({ description: 'The field properties to restore.' }),
+    index: Schema.Number.annotations({ description: 'The index to restore the field at.' }),
+  }),
+  output: Schema.Void,
+});
+
+export const RestoreCard = Operation.make({
+  meta: { key: `${KANBAN_OPERATION}.restore-card`, name: 'Restore Card' },
+  input: Schema.Struct({
+    card: Schema.Any.annotations({ description: 'The card to restore.' }),
+  }),
+  output: Schema.Void,
+});

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

@@ -2,5 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './constants';
 export * from './schema';
 export type * from './types';
+
+export * as Kanban from './Kanban';
+export * as KanbanOperation from './KanbanOperation';

package/src/types/migrations.test.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { Filter, JsonSchema, Migration, 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 = Migration.define({
+    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

@@ -4,10 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { SpaceSchema } from '@dxos/react-client/echo';
-import { DataType, FieldSchema, TypenameAnnotationId } from '@dxos/schema';
-
-import { meta } from '../meta';
+import { TypeInputOptionsAnnotation } from '@dxos/plugin-space';
 
 /**
  * Kanban data model.
@@ -21,13 +18,40 @@ import { meta } from '../meta';
 // 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),
-  typename: Schema.optional(
-    Schema.String.annotations({
-      [TypenameAnnotationId]: ['used-static', 'dynamic'],
-      title: 'Select card record type (leave empty to start fresh)',
+  // 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({
@@ -36,39 +60,3 @@ export const CreateKanbanSchema = Schema.Struct({
     }),
   ),
 });
-
-export namespace KanbanAction {
-  const KANBAN_ACTION = `${meta.id}/action`;
-
-  export class Create extends Schema.TaggedClass<Create>()(`${KANBAN_ACTION}/create`, {
-    input: Schema.extend(Schema.Struct({ space: SpaceSchema }), CreateKanbanSchema),
-    output: Schema.Struct({
-      object: DataType.View,
-    }),
-  }) {}
-
-  export class DeleteCardField extends Schema.TaggedClass<DeleteCardField>()(`${KANBAN_ACTION}/delete-card-field`, {
-    input: Schema.Struct({
-      view: DataType.View,
-      fieldId: Schema.String,
-      // TODO(wittjosiah): Separate fields for undo data?
-      deletionData: Schema.optional(
-        Schema.Struct({
-          field: FieldSchema,
-          // TODO(wittjosiah): This creates a type error.
-          // props: PropertySchema,
-          props: Schema.Any,
-          index: Schema.Number,
-        }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class DeleteCard extends Schema.TaggedClass<DeleteCard>()(`${KANBAN_ACTION}/delete-card`, {
-    input: Schema.Struct({
-      card: Schema.Any, // The card object to delete
-    }),
-    output: Schema.Void,
-  }) {}
-}

package/src/types/types.ts

@@ -2,6 +2,41 @@
 // 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;
+};

package/src/util/arrangement.test.ts

@@ -0,0 +1,217 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { beforeEach, describe, test } from 'vitest';
+
+import { Filter, JsonSchema, Query, Type, type View } from '@dxos/echo';
+import { ObjectId } from '@dxos/keys';
+import { ViewModel } from '@dxos/schema';
+
+import { Kanban, UNCATEGORIZED_VALUE } from '#types';
+
+import {
+  computeColumnStructure,
+  computeItemArrangement,
+  getOrderByColumnFromArrangement,
+  getOrderFromArrangement,
+} from './arrangement';
+
+const selectOptions = [
+  { id: UNCATEGORIZED_VALUE, title: 'Uncategorized', color: 'neutral' },
+  { id: 'a', title: 'A', color: 'blue' },
+  { id: 'b', title: 'B', color: 'green' },
+];
+
+const MinimalSchema = Schema.Struct({ id: Schema.String }).pipe(
+  Type.object({ typename: 'test/Minimal', version: '0.1.0' }),
+);
+
+describe('arrangement utils', () => {
+  let view: View.View;
+
+  beforeEach(() => {
+    view = ViewModel.make({
+      query: Query.select(Filter.type(MinimalSchema)),
+      jsonSchema: JsonSchema.toJsonSchema(MinimalSchema),
+    });
+  });
+
+  describe('getOrderFromArrangement', () => {
+    test('returns copy of order when present', ({ expect }) => {
+      const arrangement = { order: ['a', 'b'], columns: {} };
+      expect(getOrderFromArrangement(arrangement)).toEqual(['a', 'b']);
+    });
+
+    test('returns copy of order from kanban arrangement', ({ expect }) => {
+      const kanban = Kanban.make({
+        view,
+        arrangement: { order: ['b', 'a'], columns: {} },
+      });
+      const order = getOrderFromArrangement(kanban.arrangement);
+      expect(order).toEqual(['b', 'a']);
+      order.push('x');
+      expect(getOrderFromArrangement(kanban.arrangement)).toEqual(['b', 'a']);
+    });
+
+    test('returns empty when arrangement or order missing or empty', ({ expect }) => {
+      expect(getOrderFromArrangement(undefined)).toEqual([]);
+      expect(getOrderFromArrangement({ order: [], columns: {} })).toEqual([]);
+      const kanbanEmptyOrder = Kanban.make({
+        view,
+        arrangement: { order: [], columns: {} },
+      });
+      expect(getOrderFromArrangement(kanbanEmptyOrder.arrangement)).toEqual([]);
+    });
+  });
+
+  describe('getOrderByColumnFromArrangement', () => {
+    test('returns per-column data with mutable id arrays', ({ expect }) => {
+      const arrangement = {
+        order: [],
+        columns: { a: { ids: ['i1'] } },
+      };
+      const byColumn = getOrderByColumnFromArrangement(arrangement);
+      expect(byColumn.a.ids).toEqual(['i1']);
+      byColumn.a.ids.push('i2');
+      expect(getOrderByColumnFromArrangement(arrangement).a.ids).toEqual(['i1']);
+    });
+
+    test('returns per-column ids and preserves hidden from kanban arrangement', ({ expect }) => {
+      const id1 = ObjectId.random();
+      const id2 = ObjectId.random();
+      const id3 = ObjectId.random();
+      const kanban = Kanban.make({
+        view,
+        arrangement: {
+          order: [],
+          columns: {
+            a: { ids: [id1, id2], hidden: true },
+            b: { ids: [id3] },
+          },
+        },
+      });
+      const byColumn = getOrderByColumnFromArrangement(kanban.arrangement);
+      expect(byColumn.a).toEqual({ ids: [id1, id2], hidden: true });
+      expect(byColumn.b).toEqual({ ids: [id3] });
+      expect(byColumn.b.hidden).toBeUndefined();
+    });
+
+    test('treats non-array ids as empty (Automerge / corrupt layout)', ({ expect }) => {
+      const arrangement = {
+        order: [],
+        columns: { a: { ids: {} as unknown as string[] }, b: { ids: ['ok'] } },
+      };
+      const byColumn = getOrderByColumnFromArrangement(arrangement);
+      expect(byColumn.a.ids).toEqual([]);
+      expect(byColumn.b.ids).toEqual(['ok']);
+    });
+
+    test('returns mutable copies', ({ expect }) => {
+      const idX = ObjectId.random();
+      const kanban = Kanban.make({
+        view,
+        arrangement: { order: [], columns: { a: { ids: [idX] } } },
+      });
+      const byColumn = getOrderByColumnFromArrangement(kanban.arrangement);
+      byColumn.a.ids.push(ObjectId.random());
+      expect(getOrderByColumnFromArrangement(kanban.arrangement).a.ids).toEqual([idX]);
+    });
+
+    test('returns empty object when arrangement or columns missing', ({ expect }) => {
+      expect(getOrderByColumnFromArrangement(undefined)).toEqual({});
+      expect(getOrderByColumnFromArrangement({ order: [], columns: {} })).toEqual({});
+      const kanbanEmpty = Kanban.make({
+        view,
+        arrangement: { order: [], columns: {} },
+      });
+      expect(getOrderByColumnFromArrangement(kanbanEmpty.arrangement)).toEqual({});
+    });
+  });
+
+  describe('computeColumnStructure', () => {
+    test('uncategorized first, then effectiveOrder, then missing selectOptions', ({ expect }) => {
+      const effectiveOrder = ['b'];
+      const effectiveByColumn = { [UNCATEGORIZED_VALUE]: { ids: ['x'] }, b: { ids: ['y'] } };
+      const result = computeColumnStructure(effectiveOrder, effectiveByColumn, selectOptions);
+      expect(result.map((col) => col.columnValue)).toEqual([UNCATEGORIZED_VALUE, 'b', 'a']);
+      expect(result[0].ids).toEqual(['x']);
+      expect(result[1].ids).toEqual(['y']);
+      expect(result[2].ids).toEqual([]);
+    });
+
+    test('does not duplicate uncategorized when already in effectiveOrder', ({ expect }) => {
+      const effectiveOrder = [UNCATEGORIZED_VALUE, 'a'];
+      const effectiveByColumn = {};
+      const result = computeColumnStructure(effectiveOrder, effectiveByColumn, selectOptions);
+      expect(result.map((col) => col.columnValue)).toEqual([UNCATEGORIZED_VALUE, 'a', 'b']);
+    });
+  });
+
+  describe('computeItemArrangement', () => {
+    test('distributes items by pivotPath and preserves saved order within column', ({ expect }) => {
+      const idUc1 = ObjectId.random();
+      const idA1 = ObjectId.random();
+      const idA2 = ObjectId.random();
+      const idA3 = ObjectId.random();
+      const kanban = Kanban.make({
+        view,
+        arrangement: {
+          order: ['a', 'b'],
+          columns: {
+            [UNCATEGORIZED_VALUE]: { ids: [idUc1] },
+            a: { ids: [idA2, idA1] },
+            b: { ids: [] },
+          },
+        },
+      });
+      const items = [{ id: idA1, status: 'a' }, { id: idA2, status: 'a' }, { id: idA3, status: 'a' }, { id: idUc1 }];
+      const result = computeItemArrangement({
+        object: kanban,
+        items,
+        pivotPath: 'status',
+        selectOptions,
+      });
+      const colUncat = result.find((c) => c.columnValue === UNCATEGORIZED_VALUE);
+      const colA = result.find((c) => c.columnValue === 'a');
+      const colB = result.find((c) => c.columnValue === 'b');
+      expect(colUncat?.cards.map((c) => c.id)).toEqual([idUc1]);
+      expect(colA?.cards.map((c) => c.id)).toEqual([idA2, idA1, idA3]);
+      expect(colB?.cards.map((c) => c.id)).toEqual([]);
+    });
+
+    test('when pivotPath undefined all items go to uncategorized', ({ expect }) => {
+      const kanban = Kanban.make({
+        view,
+        arrangement: { order: ['a', 'b'], columns: { a: { ids: [] }, b: { ids: [] } } },
+      });
+      const items = [
+        { id: '1', status: 'a' },
+        { id: '2', status: 'b' },
+      ];
+      const result = computeItemArrangement({
+        object: kanban,
+        items,
+        selectOptions,
+      });
+      const colUncat = result.find((c) => c.columnValue === UNCATEGORIZED_VALUE);
+      const colA = result.find((c) => c.columnValue === 'a');
+      expect(colUncat?.cards.length).toBe(2);
+      expect(colA?.cards.length).toBe(0);
+    });
+
+    test('column order is uncategorized then selectOptions', ({ expect }) => {
+      const kanban = Kanban.make({
+        view,
+        arrangement: { order: ['a', 'b'], columns: {} },
+      });
+      const result = computeItemArrangement({
+        object: kanban,
+        items: [],
+        selectOptions,
+      });
+      expect(result.map((c) => c.columnValue)).toEqual([UNCATEGORIZED_VALUE, 'a', 'b']);
+    });
+  });
+});