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

package/src/meta.ts

@@ -2,14 +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 meta: PluginMeta = {
+export const meta: Plugin.Meta = {
   id: 'dxos.org/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/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,76 @@
+//
+// 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 (
+      <Mosaic.Tile
+        asChild
+        id={model.getItemId(data)}
+        data={data}
+        location={location}
+        debug={debug}
+        dragHandle={dragHandle}
+      >
+        <Focus.Group asChild>
+          <Menu.Root>
+            <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>
+                <div className='p-2 text-sm text-fg'>{Obj.getLabel(data)}</div>
+              </Card.Content>
+            </Card.Root>
+          </Menu.Root>
+        </Focus.Group>
+      </Mosaic.Tile>
+    );
+  },
+);
+
+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,41 @@
 // Copyright 2023 DXOS.org
 //
 
+import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
-import { Kanban } from '@dxos/react-ui-kanban/types';
 
 import { meta } from './meta';
+import { Kanban } from './types';
 
 export const translations = [
   {
     'en-US': {
-      [Kanban.Kanban.typename]: {
+      [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',
       },
       [meta.id]: {
+        'action menu label': 'Actions',
         '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',
+        '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',
-        'delete item label': 'Delete card',
         '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,67 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { 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: 'dxos.org/type/Kanban',
+    version: '0.3.0',
+  }),
+  LabelAnnotation.set(['name']),
+  ViewAnnotation.set(true),
+);
+
+/** 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 type * from './types';

package/src/types/schema.ts

@@ -4,8 +4,10 @@
 
 import * as Schema from 'effect/Schema';
 
-import { SpaceSchema } from '@dxos/react-client/echo';
-import { DataType, FieldSchema, TypenameAnnotationId } from '@dxos/schema';
+import { Capability } from '@dxos/app-framework';
+import { View } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+import { TypeInputOptionsAnnotation } from '@dxos/plugin-space/types';
 
 import { meta } from '../meta';
 
@@ -21,13 +23,23 @@ import { meta } from '../meta';
 // TODO(wittjosiah): Factor out?
 export const PivotColumnAnnotationId = Symbol.for('@dxos/plugin-kanban/annotation/PivotColumn');
 
+export const SettingsSchema = Schema.Struct({
+  columnFieldId: Schema.String.annotations({
+    title: 'Column field',
+  }),
+});
+
 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'],
+      registered: ['registered'],
     }),
+    Schema.optional,
   ),
   initialPivotColumn: Schema.optional(
     Schema.String.annotations({
@@ -37,38 +49,72 @@ export const CreateKanbanSchema = Schema.Struct({
   ),
 });
 
-export namespace KanbanAction {
-  const KANBAN_ACTION = `${meta.id}/action`;
+const KANBAN_OPERATION = `${meta.id}/operation`;
 
-  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 namespace KanbanOperation {
+  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 class DeleteCard extends Schema.TaggedClass<DeleteCard>()(`${KANBAN_ACTION}/delete-card`, {
-    input: Schema.Struct({
-      card: Schema.Any, // The card object to delete
-    }),
-    output: Schema.Void,
-  }) {}
+  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],
+    schema: {
+      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' },
+    schema: {
+      input: Schema.Struct({
+        card: Schema.Any,
+      }),
+      output: DeleteCardOutput,
+    },
+  });
+
+  /**
+   * Restore a deleted card field (inverse of DeleteCardField).
+   */
+  export const RestoreCardField = Operation.make({
+    meta: { key: `${KANBAN_OPERATION}/restore-card-field`, name: 'Restore Card Field' },
+    services: [Capability.Service],
+    schema: {
+      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,
+    },
+  });
+
+  /**
+   * Restore a deleted card (inverse of DeleteCard).
+   */
+  export const RestoreCard = Operation.make({
+    meta: { key: `${KANBAN_OPERATION}/restore-card`, name: 'Restore Card' },
+    schema: {
+      input: Schema.Struct({
+        card: Schema.Any.annotations({ description: 'The card to restore.' }),
+      }),
+      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.change().
+ * 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.change() if needed. */
+  setItemField: (item: T, field: string, value: unknown) => void;
+};