@dxos/plugin-kanban 0.8.4-main.9735255 → 0.8.4-main.9be5663bfe

package/src/{components → containers/KanbanContainer}/KanbanContainer.stories.tsx

@@ -5,43 +5,43 @@
 import { RegistryContext } from '@effect-atom/atom-react';
 import { type Decorator, type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
-import React, { useCallback, useContext } from 'react';
+import React, { useCallback, useContext, useMemo } from 'react';
 import { expect, waitFor, within } from 'storybook/test';
 
 import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface } from '@dxos/app-framework/ui';
 import { Obj, type QueryAST, Type } from '@dxos/echo';
+import { View } from '@dxos/echo';
 import { type Mutable } from '@dxos/echo/internal';
 import { invariant } from '@dxos/invariant';
 import { ClientPlugin } from '@dxos/plugin-client';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
 import { PreviewPlugin } from '@dxos/plugin-preview';
-import { useGlobalFilteredObjects } from '@dxos/plugin-search';
 import { SpacePlugin } from '@dxos/plugin-space';
 import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { Filter, type Space, useQuery, useSchema, useSpaces } from '@dxos/react-client/echo';
-import { withTheme } from '@dxos/react-ui/testing';
 import { ViewEditor } from '@dxos/react-ui-form';
-import {
-  Kanban as KanbanComponent,
-  translations as kanbanTranslations,
-  useKanbanModel,
-  useProjectionModel,
-} from '@dxos/react-ui-kanban';
-import { Kanban } from '@dxos/react-ui-kanban/types';
-import { JsonFilter } from '@dxos/react-ui-syntax-highlighter';
-import { View, getTypenameFromQuery } from '@dxos/schema';
+import { Json } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout } from '@dxos/react-ui/testing';
+import { ViewModel, getTypenameFromQuery } from '@dxos/schema';
+// TODO(wittjosiah): Replace with echo/testing.
 import { Organization, Person } from '@dxos/types';
 
-import { translations } from '../translations';
+import { useProjectionModel } from '#hooks';
+import { Kanban } from '#types';
 
-faker.seed(0);
+import { KanbanPlugin } from '../../KanbanPlugin';
+import { translations } from '../../translations';
 
-const createOrg = () => ({
-  name: faker.commerce.productName(),
-  description: faker.lorem.paragraph(),
-  image: faker.image.url(),
-  website: faker.internet.url(),
-  status: faker.helpers.arrayElement(Organization.StatusOptions).id as Organization.Organization['status'],
+random.seed(0);
+
+const createOrg = (status?: Organization.Organization['status']) => ({
+  name: random.commerce.productName(),
+  description: random.lorem.paragraph(),
+  image: random.image.url(),
+  website: random.internet.url(),
+  status: (status ?? random.helpers.arrayElement(Organization.StatusOptions).id) as Organization.Organization['status'],
 });
 
 //
@@ -49,12 +49,13 @@ const createOrg = () => ({
 //
 
 type ClientSetupOptions = {
-  types?: Type.Entity.Any[];
+  types?: Type.AnyEntity[];
   onSpaceCreated?: (space: Space) => Promise<void>;
 };
 
 /**
  * Creates the standard plugin manager decorator with client configuration.
+ * Includes KanbanPlugin so the Surface resolves to KanbanContainer.
  */
 const withKanbanPlugins = ({ types = [], onSpaceCreated }: ClientSetupOptions): Decorator =>
   withPluginManager({
@@ -64,7 +65,7 @@ const withKanbanPlugins = ({ types = [], onSpaceCreated }: ClientSetupOptions):
         types: [...types, View.View, Kanban.Kanban],
         onClientInitialized: ({ client }) =>
           Effect.gen(function* () {
-            yield* Effect.promise(() => client.halo.createIdentity());
+            yield* initializeIdentity(client);
             const space = yield* Effect.promise(() => client.spaces.create());
             yield* Effect.promise(() => space.waitUntilReady());
             yield* Effect.promise(() => onSpaceCreated?.(space) ?? Promise.resolve());
@@ -73,61 +74,37 @@ const withKanbanPlugins = ({ types = [], onSpaceCreated }: ClientSetupOptions):
       PreviewPlugin(),
       SpacePlugin({}),
       StorybookPlugin({}),
+      KanbanPlugin(),
     ],
   });
 
-//
-// Story components.
-//
-
+/**
+ * Renders the first Kanban in the space via Surface (resolves to KanbanContainer),
+ * with a sidebar containing ViewEditor and Json filter.
+ */
 const DefaultComponent = () => {
   const registry = useContext(RegistryContext);
   const spaces = useSpaces();
   const space = spaces[spaces.length - 1];
-  const [object] = useQuery(space?.db, Filter.type(Kanban.Kanban));
-  const typename = object?.view.target?.query ? getTypenameFromQuery(object.view.target.query.ast) : undefined;
+  const [kanban] = useQuery(space?.db, Filter.type(Kanban.Kanban));
+  const typename = kanban?.view.target?.query ? getTypenameFromQuery(kanban.view.target.query.ast) : undefined;
   const schema = useSchema(space?.db, typename);
+  const projection = useProjectionModel(schema, kanban, registry);
 
-  const objects = useQuery(space?.db, schema ? Filter.type(schema) : Filter.nothing());
-  const filteredObjects = useGlobalFilteredObjects(objects);
-
-  const projection = useProjectionModel(schema, object, registry);
-  const model = useKanbanModel({
-    object,
-    projection,
-    items: filteredObjects,
-  });
-
-  const handleAddCard = useCallback(
-    (columnValue: string | undefined) => {
-      const path = model?.columnFieldPath;
-      if (space && schema && Type.isObjectSchema(schema) && path) {
-        const card = Obj.make(schema, {
-          ...createOrg(),
-          [path]: columnValue,
-        });
-
-        space.db.add(card);
-        return card.id;
-      }
-    },
-    [space, schema, model],
-  );
-
-  const handleRemoveCard = useCallback((card: { id: string }) => Obj.isObject(card) && space?.db.remove(card), [space]);
+  const data = useMemo(() => (kanban ? { subject: kanban, attendableId: 'story' } : {}), [kanban]);
 
   const handleUpdateQuery = useCallback(
     (newQuery: QueryAST.Query) => {
       invariant(schema);
-      invariant(Type.isMutable(schema));
-      invariant(object.view.target);
-
-      schema.updateTypename(getTypenameFromQuery(newQuery));
-      Obj.change(object.view.target, (v) => {
-        v.query.ast = newQuery as Mutable<typeof newQuery>;
+      invariant(kanban?.view.target);
+      if (Type.isMutable(schema)) {
+        schema.updateTypename(getTypenameFromQuery(newQuery));
+      }
+      Obj.change(kanban.view.target, (view) => {
+        view.query.ast = newQuery as Mutable<QueryAST.Query>;
       });
     },
-    [object, schema],
+    [kanban, schema],
   );
 
   const handleDeleteField = useCallback(
@@ -139,23 +116,27 @@ const DefaultComponent = () => {
     [schema, projection],
   );
 
-  if (!schema || !object.view.target) {
+  if (!schema || !kanban?.view.target) {
     return null;
   }
 
   return (
-    <div className='grow grid grid-cols-[1fr_350px] overflow-hidden'>
-      {model ? <KanbanComponent model={model} onAddCard={handleAddCard} onRemoveCard={handleRemoveCard} /> : <div />}
-      <div className='flex flex-col bs-full overflow-hidden border-l border-separator'>
+    <div className='grow grid grid-cols-[1fr_350px] overflow-hidden h-full w-full'>
+      <Surface.Surface role='article' data={data} limit={1} />
+      <div className='flex flex-col h-full overflow-hidden border-l border-separator'>
         <ViewEditor
-          classNames='p-2'
           registry={space?.db.schemaRegistry}
           schema={schema}
-          view={object.view.target}
+          view={kanban.view.target}
           onQueryChanged={handleUpdateQuery}
-          onDelete={Type.isMutable(schema) ? handleDeleteField : undefined}
+          onDelete={schema && Type.isMutable(schema) ? handleDeleteField : undefined}
         />
-        <JsonFilter data={{ view: object.view.target, schema }} classNames='text-xs' />
+        <Json.Root data={{ view: kanban.view.target, schema }}>
+          <Json.Content>
+            <Json.Filter />
+            <Json.Data classNames='text-xs' />
+          </Json.Content>
+        </Json.Root>
       </div>
     </div>
   );
@@ -166,13 +147,13 @@ const DefaultComponent = () => {
 //
 
 const meta = {
-  title: 'plugins/plugin-kanban/Kanban',
+  title: 'plugins/plugin-kanban/containers/Kanban',
   component: DefaultComponent,
   render: () => <DefaultComponent />,
-  decorators: [withTheme],
+  decorators: [withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
-    translations: [...translations, ...kanbanTranslations],
+    translations,
   },
 } satisfies Meta<typeof DefaultComponent>;
 
@@ -189,7 +170,7 @@ export const Default: Story = {
     withKanbanPlugins({
       types: [Organization.Organization, Person.Person],
       onSpaceCreated: async (space) => {
-        const { view } = await View.makeFromDatabase({
+        const { view } = await ViewModel.makeFromDatabase({
           db: space.db,
           typename: Organization.Organization.typename,
           pivotFieldName: 'status',
@@ -197,8 +178,7 @@ export const Default: Story = {
         const kanban = Kanban.make({ view });
         space.db.add(kanban);
 
-        // TODO(burdon): Replace with sdk/schema/testing.
-        Array.from({ length: 80 }).map(() => {
+        Array.from({ length: 10 }).map(() => {
           return space.db.add(Obj.make(Organization.Organization, createOrg()));
         });
       },
@@ -209,25 +189,24 @@ export const Default: Story = {
 
     // Wait for the kanban columns to render by finding the status tags.
     // Organization.StatusOptions: prospect, qualified, active, commit, reject.
-    const activeTag = await canvas.findByText('Active', undefined, { timeout: 30_000 });
-    const prospectTag = await canvas.findByText('Prospect', undefined, { timeout: 10_000 });
-    const commitTag = await canvas.findByText('Commit', undefined, { timeout: 10_000 });
+    const activeTag = await canvas.findByText('Active', undefined, { timeout: 12_000 });
+    const prospectTag = await canvas.findByText('Prospect', undefined, { timeout: 12_000 });
+    const commitTag = await canvas.findByText('Commit', undefined, { timeout: 12_000 });
 
     // Verify all expected columns are rendered.
     await expect(activeTag).toBeTruthy();
     await expect(prospectTag).toBeTruthy();
     await expect(commitTag).toBeTruthy();
 
-    // Find the column containers.
-    const activeColumn = activeTag.closest('[data-dx-stack-item]') as HTMLElement;
-    const prospectColumn = prospectTag.closest('[data-dx-stack-item]') as HTMLElement;
+    // Find the column containers (Board uses data-testid="board-column").
+    const activeColumn = activeTag.closest('[data-testid="board-column"]') as HTMLElement;
+    const prospectColumn = prospectTag.closest('[data-testid="board-column"]') as HTMLElement;
     await expect(activeColumn).toBeTruthy();
     await expect(prospectColumn).toBeTruthy();
 
-    // Wait for cards to render in the columns.
-    // Cards have data-dx-item-id attribute from StackItem.Root.
+    // Wait for cards to render in the columns (Board items use data-testid="board-item").
     const getColumnCards = (column: HTMLElement) =>
-      Array.from(column.querySelectorAll('[data-dx-item-id]')) as HTMLElement[];
+      Array.from(column.querySelectorAll('[data-testid="board-item"]')) as HTMLElement[];
 
     await waitFor(() => expect(getColumnCards(activeColumn).length).toBeGreaterThan(0));
 
@@ -237,16 +216,16 @@ export const Default: Story = {
     await expect(activeCards.length).toBeGreaterThan(0);
     await expect(prospectCards.length).toBeGreaterThan(0);
 
-    // Verify cards have drag handles (first button in toolbar).
+    // Verify cards have drag handles (Card.Toolbar includes drag handle).
     const firstActiveCard = activeCards[0];
     const buttons = firstActiveCard.querySelectorAll('button');
     await expect(buttons.length).toBeGreaterThan(0);
 
-    // Verify the drop zone exists in each column.
-    const activeDropZone = activeColumn.querySelector('.kanban-drop');
-    const prospectDropZone = prospectColumn.querySelector('.kanban-drop');
-    await expect(activeDropZone).toBeTruthy();
-    await expect(prospectDropZone).toBeTruthy();
+    // Verify add-card action exists in columns (optional footer).
+    const activeAddItem = activeColumn.querySelector('[data-testid="board-column-add-item"]');
+    const prospectAddItem = prospectColumn.querySelector('[data-testid="board-column-add-item"]');
+    await expect(activeAddItem).toBeTruthy();
+    await expect(prospectAddItem).toBeTruthy();
 
     // TODO(wittjosiah): Get drag & drop tests working.
     //   See packages/apps/composer-app/src/playwright/stack.spec.ts for reference.
@@ -268,7 +247,7 @@ export const MutableSchema: Story = {
         // Register schema in the database to make it mutable (EchoSchema).
         const [schema] = await space.db.schemaRegistry.register([Organization.Organization]);
 
-        const { view } = await View.makeFromDatabase({
+        const { view } = await ViewModel.makeFromDatabase({
           db: space.db,
           typename: schema.typename,
           pivotFieldName: 'status',
@@ -277,9 +256,14 @@ export const MutableSchema: Story = {
         space.db.add(kanban);
 
         // Create test data using the registered schema.
-        Array.from({ length: 80 }).map(() => {
-          return space.db.add(Obj.make(schema, createOrg()));
-        });
+        const requiredOrgs = [
+          ...Array.from({ length: 2 }, () => createOrg('prospect')),
+          ...Array.from({ length: 5 }, () => createOrg('qualified')),
+          ...Array.from({ length: 1 }, () => createOrg('active')),
+          ...Array.from({ length: 1 }, () => createOrg('commit')),
+          ...Array.from({ length: 1 }, () => createOrg('reject')),
+        ];
+        requiredOrgs.forEach((org) => space.db.add(Obj.make(schema, org)));
       },
     }),
   ],

package/src/containers/KanbanContainer/KanbanContainer.tsx

@@ -0,0 +1,96 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import React, { useCallback, useContext, useMemo } from 'react';
+
+import { useCapabilities, useOperationInvoker } from '@dxos/app-framework/ui';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Filter, Obj, Query, Type } from '@dxos/echo';
+import { AtomQuery } from '@dxos/echo-atom';
+import { useObject, useSchema } from '@dxos/react-client/echo';
+import { Panel, Toolbar } from '@dxos/react-ui';
+import { getTagFromQuery, getTypenameFromQuery } from '@dxos/schema';
+
+import { KanbanBoard } from '#components';
+import { useEchoChangeCallback, useProjectionModel } from '#hooks';
+import { KanbanOperation } from '#operations';
+import { type Kanban } from '#types';
+
+export type KanbanContainerProps = AppSurface.ObjectArticleProps<Kanban.Kanban>;
+
+export const KanbanContainer = ({ role, subject: object }: KanbanContainerProps) => {
+  const registry = useContext(RegistryContext);
+  const schemas = useCapabilities(AppCapabilities.Schema);
+  const db = Obj.getDatabase(object);
+  const { invokePromise } = useOperationInvoker();
+  const [view] = useObject(object.view);
+  const typename = view?.query ? getTypenameFromQuery(view.query.ast) : undefined;
+  const tag = view?.query ? getTagFromQuery(view.query.ast) : undefined;
+
+  const schemaFromDb = useSchema(db, typename);
+  const cardSchema = useMemo(
+    () => schemaFromDb ?? schemas.flat().find((schema) => Type.getTypename(schema) === typename),
+    [schemaFromDb, schemas, typename],
+  );
+
+  const items = useMemo(() => {
+    if (!db) {
+      return null;
+    }
+    const baseFilter = cardSchema ? Filter.type(cardSchema) : Filter.nothing();
+    const query = tag ? Query.select(baseFilter).select(Filter.tag(tag)) : Query.select(baseFilter);
+    return AtomQuery.make(db, query);
+  }, [db, cardSchema, tag]);
+
+  const projection = useProjectionModel(cardSchema, object, registry);
+  const change = useEchoChangeCallback(object);
+
+  const pivotFieldId = view?.projection?.pivotFieldId;
+  const columnFieldPath =
+    projection && pivotFieldId ? projection.tryGetFieldProjection(pivotFieldId)?.props.property : undefined;
+
+  const handleCardAdd = useCallback(
+    (columnValue: string | undefined) => {
+      if (db && cardSchema && columnFieldPath) {
+        const card = Obj.make(cardSchema, { [columnFieldPath]: columnValue });
+        db.add(card);
+        return card.id;
+      }
+    },
+    [db, cardSchema, columnFieldPath],
+  );
+
+  const handleCardRemove = useCallback(
+    (card: { id: string }) => {
+      void invokePromise(KanbanOperation.DeleteCard, { card });
+    },
+    [invokePromise],
+  );
+
+  if (!object || !db || !items || !projection || !change) {
+    return null;
+  }
+
+  return (
+    <Panel.Root role={role}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root />
+      </Panel.Toolbar>
+      <KanbanBoard.Root
+        kanban={object}
+        projection={projection}
+        items={items}
+        change={change}
+        onCardAdd={handleCardAdd}
+        onCardRemove={handleCardRemove}
+      >
+        <Panel.Content asChild>
+          <KanbanBoard.Content />
+        </Panel.Content>
+      </KanbanBoard.Root>
+    </Panel.Root>
+  );
+};

package/src/containers/KanbanContainer/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export { KanbanContainer as default } from './KanbanContainer';

package/src/{components → containers/KanbanViewEditor}/KanbanViewEditor.tsx

@@ -5,40 +5,44 @@
 import { RegistryContext } from '@effect-atom/atom-react';
 import React, { useCallback, useContext, useMemo } from 'react';
 
+import { type AppSurface } from '@dxos/app-toolkit/ui';
 import { Obj } from '@dxos/echo';
 import { Format } from '@dxos/echo/internal';
-import { invariant } from '@dxos/invariant';
-import { useSchema } from '@dxos/react-client/echo';
+import { useObject, useSchema } from '@dxos/react-client/echo';
 import { Form, type FormFieldMap, SelectField } from '@dxos/react-ui-form';
-import { useProjectionModel } from '@dxos/react-ui-kanban';
-import { type Kanban } from '@dxos/react-ui-kanban/types';
 import { getTypenameFromQuery } from '@dxos/schema';
 
-import { SettingsSchema } from '../types';
+import { useProjectionModel } from '#hooks';
+import { type Kanban, SettingsSchema } from '#types';
 
-type KanbanViewEditorProps = { object: Kanban.Kanban };
+export type KanbanViewEditorProps = AppSurface.ObjectPropertiesProps<Kanban.Kanban>;
 
-export const KanbanViewEditor = ({ object }: KanbanViewEditorProps) => {
+export const KanbanViewEditor = ({ subject: object }: KanbanViewEditorProps) => {
   const registry = useContext(RegistryContext);
   const db = Obj.getDatabase(object);
-  const view = object.view.target;
+  const [view, updateView] = useObject(object.view);
   const currentTypename = view?.query ? getTypenameFromQuery(view.query.ast) : undefined;
   const schema = useSchema(db, currentTypename);
   const projection = useProjectionModel(schema, object, registry);
 
-  const fieldProjections = projection?.getFieldProjections() || [];
-  const selectFields = fieldProjections
-    .filter((field) => field.props.format === Format.TypeFormat.SingleSelect)
-    .map(({ field }) => ({ value: field.id, label: field.path }));
+  const fieldProjections = projection?.getFieldProjections() ?? [];
+  const selectFields = useMemo(
+    () =>
+      fieldProjections
+        .filter((field) => field.props.format === Format.TypeFormat.SingleSelect)
+        .map(({ field }) => ({ value: field.id, label: field.path })),
+    [fieldProjections],
+  );
 
-  const handleSave = useCallback(
+  const handleValuesChanged = useCallback(
     (values: Partial<{ columnFieldId: string }>) => {
-      invariant(view);
-      Obj.change(view, (v) => {
-        v.projection.pivotFieldId = values.columnFieldId;
-      });
+      if (values.columnFieldId != null) {
+        updateView((view) => {
+          view.projection.pivotFieldId = values.columnFieldId;
+        });
+      }
     },
-    [view],
+    [updateView],
   );
 
   const initialValues = useMemo(
@@ -52,7 +56,7 @@ export const KanbanViewEditor = ({ object }: KanbanViewEditorProps) => {
   );
 
   return (
-    <Form.Root schema={SettingsSchema} values={initialValues} fieldMap={fieldMap} autoSave onSave={handleSave}>
+    <Form.Root schema={SettingsSchema} values={initialValues} fieldMap={fieldMap} onValuesChanged={handleValuesChanged}>
       <Form.FieldSet />
     </Form.Root>
   );

package/src/containers/KanbanViewEditor/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { KanbanViewEditor as default } from './KanbanViewEditor';

package/src/containers/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const KanbanContainer: ComponentType<any> = lazy(() => import('./KanbanContainer'));
+export const KanbanViewEditor: ComponentType<any> = lazy(() => import('./KanbanViewEditor'));

package/src/hooks/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useEchoChangeCallback';
+export * from './useKanbanBoardModel';
+export * from './useKanbanColumnEventHandler';
+export * from './useKanbanItemEventHandler';
+export * from './useProjectionModel';

package/src/hooks/useEchoChangeCallback.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { Obj } from '@dxos/echo';
+
+import { type Kanban, type KanbanChangeCallback } from '#types';
+
+/**
+ * Creates a change callback for ECHO-backed kanban and items (plain function, no hooks).
+ * Use this when the kanban and items are stored in the ECHO database.
+ */
+export const createEchoChangeCallback = <T extends Obj.Unknown>(kanban: Kanban.Kanban): KanbanChangeCallback<T> => ({
+  kanban: (mutate) => Obj.change(kanban, (kanban) => mutate(kanban)),
+  setItemField: (item, field, value) => {
+    Obj.change(item, (item: any) => {
+      item[field] = value;
+    });
+  },
+});
+
+/**
+ * Returns a memoized ECHO change callback for the given kanban.
+ * Returns null when kanban is undefined.
+ */
+export const useEchoChangeCallback = <T extends Obj.Unknown = Obj.Unknown>(
+  kanban: Kanban.Kanban | undefined,
+): KanbanChangeCallback<T> | null => useMemo(() => (kanban ? createEchoChangeCallback<T>(kanban) : null), [kanban]);