@dxos/plugin-kanban 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/meta.ts

@@ -2,16 +2,18 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const KANBAN_PLUGIN = 'dxos.org/plugin/kanban';
-
-export const meta: PluginMeta = {
-  id: KANBAN_PLUGIN,
+export const meta: Plugin.Meta = {
+  id: '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.',
+  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.
+  `,
   icon: 'ph--kanban--regular',
+  iconHue: 'green',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-kanban',
   screenshots: ['https://dxos.network/plugin-details-kanban-dark.png'],
 };

package/src/operations/definitions.ts

@@ -0,0 +1,63 @@
+// Copyright 2025 DXOS.org
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { View } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+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/operations/delete-card-field.ts

@@ -0,0 +1,47 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { JsonSchema, Obj } from '@dxos/echo';
+import { type EchoSchema } from '@dxos/echo/internal';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { ProjectionModel, createEchoChangeCallback, getTypenameFromQuery } from '@dxos/schema';
+
+import { DeleteCardField } from './definitions';
+
+const handler: Operation.WithHandler<typeof DeleteCardField> = 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 schema = yield* Effect.promise(() =>
+        db.schemaRegistry
+          .query({
+            typename: getTypenameFromQuery(view.query.ast)!,
+            location: ['database', 'runtime'],
+          })
+          .first(),
+      );
+
+      const projection = new ProjectionModel({
+        registry,
+        view,
+        baseSchema: JsonSchema.toJsonSchema(schema),
+        change: createEchoChangeCallback(view, schema as EchoSchema),
+      });
+
+      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 { Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+
+import { DeleteCard } from './definitions';
+
+const handler: Operation.WithHandler<typeof DeleteCard> = 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,12 @@
+// Copyright 2025 DXOS.org
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * as KanbanOperation from './definitions';
+
+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,41 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { JsonSchema, Obj } from '@dxos/echo';
+import { type EchoSchema } from '@dxos/echo/internal';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { ProjectionModel, createEchoChangeCallback, getTypenameFromQuery } from '@dxos/schema';
+
+import { RestoreCardField } from './definitions';
+
+const handler: Operation.WithHandler<typeof RestoreCardField> = 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 schema = yield* Effect.promise(() =>
+        db.schemaRegistry
+          .query({
+            typename: getTypenameFromQuery(view.query.ast)!,
+            location: ['database', 'runtime'],
+          })
+          .first(),
+      );
+
+      const projection = new ProjectionModel({
+        registry,
+        view,
+        baseSchema: JsonSchema.toJsonSchema(schema),
+        change: createEchoChangeCallback(view, schema as EchoSchema),
+      });
+
+      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 { Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+
+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 });
+
+    // 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. 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 });
+
+    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

@@ -2,34 +2,42 @@
 // Copyright 2023 DXOS.org
 //
 
+import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
-import { KanbanType } from '@dxos/react-ui-kanban';
 
-import { meta } from './meta';
+import { meta } from '#meta';
+import { Kanban } from '#types';
 
 export const translations = [
   {
     'en-US': {
-      [KanbanType.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,71 @@
+//
+// 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 (ids order, optional hidden). */
+const ArrangementColumnEntry = Schema.Struct({
+  ids: Schema.Array(Obj.ID),
+  hidden: Schema.optional(Schema.Boolean),
+});
+
+/** 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>;
+
+export const Kanban = Schema.Struct({
+  name: Schema.optional(Schema.String),
+
+  view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
+
+  /** Column display order and per-column card ids. */
+  arrangement: Arrangement,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.kanban',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  ViewAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--kanban--regular',
+    hue: 'green',
+  }),
+);
+
+/** Instance type; use Kanban.Kanban in type position so namespace has .Kanban as type and .KanbanSchema as schema. */
+export interface Kanban extends Schema.Schema.Type<typeof Kanban> {}
+
+type MakeProps = Omit<Partial<Obj.MakeProps<typeof Kanban>>, 'view'> & {
+  view: View.View;
+};
+
+/**
+ * Make a kanban as a view of a data set.
+ */
+export const make = (props: MakeProps): Kanban => {
+  const { name, view, arrangement } = props;
+  const order = arrangement?.order ?? [];
+  const columns = arrangement?.columns ?? {};
+  return Obj.make(Kanban, {
+    name,
+    view: Ref.make(view),
+    arrangement: { order, columns },
+  });
+};

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,7 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './constants';
+export * as Kanban from './Kanban';
 export * from './schema';
-export * from './types';
+export type * from './types';