@dxos/plugin-kanban 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

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

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

package/src/translations.ts

@@ -4,32 +4,40 @@
 
 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 { 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]: {
-        'plugin name': 'Kanban',
-        'kanban title label': 'Title',
-        'column title label': 'Column title',
-        'column title placeholder': 'New column',
-        'add column label': 'Add column',
-        'delete column label': 'Delete column',
-        '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 type * from './types';

package/src/types/schema.ts

@@ -4,12 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Capability } from '@dxos/app-framework';
-import { Operation } from '@dxos/operation';
 import { TypeInputOptionsAnnotation } from '@dxos/plugin-space/types';
-import { FieldSchema, View } from '@dxos/schema';
-
-import { meta } from '../meta';
 
 /**
  * Kanban data model.
@@ -37,7 +32,6 @@ export const CreateKanbanSchema = Schema.Struct({
     TypeInputOptionsAnnotation.set({
       location: ['database', 'runtime'],
       kind: ['user'],
-      registered: ['registered'],
     }),
     Schema.optional,
   ),
@@ -48,73 +42,3 @@ export const CreateKanbanSchema = Schema.Struct({
     }),
   ),
 });
-
-const KANBAN_OPERATION = `${meta.id}/operation`;
-
-export namespace KanbanOperation {
-  export const DeleteCardFieldOutput = Schema.Struct({
-    field: 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],
-    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: 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;
+};

package/src/util/arrangement.test.ts

@@ -0,0 +1,208 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { beforeEach, describe, test } from 'vitest';
+
+import { Filter, JsonSchema, Query, Type } from '@dxos/echo';
+import { 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('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']);
+    });
+  });
+});