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

package/src/capabilities/migrations.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { defineObjectMigration } from '@dxos/client/echo';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+
+import { Kanban } from '#types';
+
+/**
+ * v0.1.0 → v0.2.0: nests the existing `view` ref under a `spec: { kind: 'view', view }`
+ * discriminated union. v0.2.0 introduced an items-variant for externally-synced kanbans;
+ * pre-migration objects were all view-based by construction.
+ */
+const migrations = [
+  defineObjectMigration({
+    from: Kanban.KanbanV1,
+    to: Kanban.Kanban,
+    transform: async (from) => ({
+      name: from.name,
+      arrangement: from.arrangement,
+      spec: { kind: 'view' as const, view: from.view },
+    }),
+    onMigration: async () => {},
+  }),
+];
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(ClientCapabilities.Migration, migrations);
+  }),
+);

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,14 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { KanbanOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, KanbanOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -2,80 +2,94 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema } from 'effect';
+import * as Effect from 'effect/Effect';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 import React, { useMemo } from 'react';
 
-import { Capabilities, contributes, createSurface, useCapabilities } from '@dxos/app-framework';
-import { Type } from '@dxos/echo';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Database, JsonSchema, Obj } from '@dxos/echo';
+import { type Collection } from '@dxos/echo';
 import { findAnnotation } from '@dxos/effect';
-import { ClientCapabilities } from '@dxos/plugin-client';
-import { getSpace, isSpace, type Space } from '@dxos/react-client/echo';
-import { type InputProps, SelectInput, useFormValues } from '@dxos/react-ui-form';
-import { type KanbanType } from '@dxos/react-ui-kanban';
-import { type DataType } from '@dxos/schema';
+import { type FormFieldComponentProps, SelectField, useFormValues } from '@dxos/react-ui-form';
 
-import { KanbanContainer, KanbanViewEditor } from '../components';
-import { meta } from '../meta';
-import { isKanban, PivotColumnAnnotationId } from '../types';
+import { KanbanContainer, KanbanSettings } from '#containers';
+import { Kanban, PivotColumnAnnotationId } from '#types';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: meta.id,
-      role: ['article', 'section'],
-      filter: (data): data is { subject: KanbanType } => isKanban(data.subject),
-      component: ({ data, role }) => <KanbanContainer kanban={data.subject} role={role} />,
-    }),
-    createSurface({
-      id: `${meta.id}/object-settings`,
-      role: 'object-settings',
-      filter: (data): data is { subject: KanbanType } => isKanban(data.subject),
-      component: ({ data }) => <KanbanViewEditor kanban={data.subject} />,
-    }),
-    createSurface({
-      id: `${meta.id}/create-initial-schema-form-[pivot-column]`,
-      role: 'form-input',
-      filter: (
-        data,
-      ): data is { prop: string; schema: Schema.Schema<any>; target: Space | DataType.Collection | undefined } => {
-        const annotation = findAnnotation<boolean>((data.schema as Schema.Schema.All).ast, PivotColumnAnnotationId);
-        return !!annotation;
-      },
-      component: ({ data: { target }, ...inputProps }) => {
-        const props = inputProps as any as InputProps;
-        const space = isSpace(target) ? target : getSpace(target);
-        if (!space) {
-          return null;
-        }
-        const { typename } = useFormValues();
-        // TODO(wittjosiah): Unify this schema lookup.
-        const schemaWhitelists = useCapabilities(ClientCapabilities.SchemaWhiteList);
-        const staticSchema = schemaWhitelists.flat().find((schema) => Type.getTypename(schema) === typename);
-        const [selectedSchema] = space?.db.schemaRegistry.query({ typename }).runSync();
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'root',
+        // TODO(wittjosiah): Split into multiple surfaces if this filter proves too strict for non-article roles.
+        filter: AppSurface.oneOf(
+          AppSurface.object(AppSurface.Article, Kanban.Kanban),
+          AppSurface.object(AppSurface.Section, Kanban.Kanban),
+        ),
+        component: ({ data, role }) => <KanbanContainer role={role} subject={data.subject} />,
+      }),
+      Surface.create({
+        id: 'object-properties',
+        position: 'hoist',
+        filter: AppSurface.object(AppSurface.ObjectProperties, Kanban.Kanban),
+        component: ({ data }) => <KanbanSettings subject={data.subject} />,
+      }),
+      Surface.create({
+        id: 'create-initial-schema-form-[pivot-column]',
+        role: 'form-input',
+        filter: (
+          data,
+        ): data is {
+          prop: string;
+          schema: Schema.Schema<any>;
+          target: Database.Database | Collection.Collection | undefined;
+          fieldPropertyAst?: SchemaAST.AST;
+        } => {
+          const annotation = findAnnotation<boolean>((data.schema as Schema.Schema.All).ast, PivotColumnAnnotationId);
+          return !!annotation;
+        },
+        component: ({ data: { target, fieldPropertyAst }, ...inputProps }) => {
+          const ast = fieldPropertyAst;
+          if (!ast) {
+            return null;
+          }
 
-        const singleSelectColumns = useMemo(() => {
-          const properties = staticSchema
-            ? Type.toJsonSchema(staticSchema).properties
-            : selectedSchema?.jsonSchema?.properties;
-          if (!properties) {
-            return [];
+          const props = { ...inputProps, type: ast } as any as FormFieldComponentProps;
+          const db = Database.isDatabase(target) ? target : target && Obj.getDatabase(target);
+          if (!db) {
+            return null;
           }
 
-          const columns = Object.entries(properties).reduce<string[]>((acc, [key, value]) => {
-            if (typeof value === 'object' && value?.format === 'single-select') {
-              acc.push(key);
+          const { typename } = useFormValues('KanbanForm');
+          const [selectedSchema] = useMemo(
+            () => db.schemaRegistry.query({ location: ['database', 'runtime'], typename }).runSync(),
+            [db, typename],
+          );
+          const singleSelectColumns = useMemo(() => {
+            const properties = JsonSchema.toJsonSchema(selectedSchema).properties;
+            if (!properties) {
+              return [];
             }
-            return acc;
-          }, []);
 
-          return columns;
-        }, [selectedSchema?.jsonSchema, staticSchema]);
+            const columns = Object.entries(properties).reduce<string[]>((acc, [key, value]) => {
+              if (typeof value === 'object' && value?.format === 'single-select') {
+                acc.push(key);
+              }
+              return acc;
+            }, []);
+
+            return columns;
+          }, [selectedSchema]);
 
-        if (!typename) {
-          return null;
-        }
+          if (!typename) {
+            return null;
+          }
 
-        return <SelectInput {...props} options={singleSelectColumns.map((column) => ({ value: column }))} />;
-      },
-    }),
-  ]);
+          return <SelectField {...props} options={singleSelectColumns.map((column) => ({ value: column }))} />;
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/undo-mappings.ts

@@ -0,0 +1,34 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability, UndoMapping } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+import { KanbanOperation } from '#operations';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.UndoMapping, [
+      UndoMapping.make({
+        operation: KanbanOperation.DeleteCardField,
+        inverse: KanbanOperation.RestoreCardField,
+        deriveContext: (input, output) => ({
+          view: input.view,
+          field: output.field,
+          props: output.props,
+          index: output.index,
+        }),
+        message: ['card-field-deleted.label', { ns: meta.id }],
+      }),
+      UndoMapping.make({
+        operation: KanbanOperation.DeleteCard,
+        inverse: KanbanOperation.RestoreCard,
+        deriveContext: (_input, output) => ({
+          card: output.card,
+        }),
+        message: ['card-deleted.label', { ns: meta.id }],
+      }),
+    ]),
+  ),
+);

package/src/components/KanbanBoard/KanbanBoard.stories.tsx

@@ -0,0 +1,146 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, RegistryContext } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useContext, useEffect, useMemo, useState } from 'react';
+
+import { Filter, JsonSchema, Obj, Query } from '@dxos/echo';
+import { type View } from '@dxos/echo';
+import { random } from '@dxos/random';
+import { withMosaic } from '@dxos/react-ui-mosaic/testing';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { ProjectionModel, ViewModel, createEchoChangeCallback } from '@dxos/schema';
+import { withRegistry } from '@dxos/storybook-utils';
+import { Organization } from '@dxos/types';
+
+import { createEchoChangeCallback as createKanbanChangeCallback } from '#hooks';
+import { KanbanCardTileSimple } from '#testing';
+import { translations } from '#translations';
+import { Kanban } from '#types';
+
+import { KanbanBoard } from './KanbanBoard';
+
+random.seed(1);
+
+const createOrg = () => ({
+  name: random.commerce.productName(),
+  description: random.lorem.sentence(),
+  image: random.image.url(),
+  website: random.internet.url(),
+  status: random.helpers.arrayElement(Organization.StatusOptions).id as Organization.Organization['status'],
+});
+
+/**
+ * In-memory Kanban board: View + ProjectionModel + Kanban + items, no plugin manager or Space.
+ * Similar to react-ui-kanban Kanban.stories.tsx.
+ */
+const DefaultStory = () => {
+  const registry = useContext(RegistryContext);
+  const items = useMemo(() => Atom.make<Obj.Unknown[]>([]), []);
+  const [state, setState] = useState<{
+    view: View.View;
+    kanban: Kanban.Kanban;
+    projection: ProjectionModel;
+    change: ReturnType<typeof createKanbanChangeCallback>;
+  }>();
+
+  useEffect(() => {
+    const view = ViewModel.make({
+      query: Query.select(Filter.typename(Organization.Organization.typename)),
+      jsonSchema: JsonSchema.toJsonSchema(Organization.Organization),
+      pivotFieldName: 'status',
+    });
+    const kanban = Kanban.make({ view });
+    const change = createKanbanChangeCallback(kanban);
+    const projection = new ProjectionModel({
+      registry,
+      view,
+      baseSchema: JsonSchema.toJsonSchema(Organization.Organization),
+      change: createEchoChangeCallback(view),
+    });
+    projection.normalizeView();
+
+    const statuses = Organization.StatusOptions.map((o) => o.id);
+    const initialItems = Array.from({ length: 12 }, () =>
+      Obj.make(Organization.Organization, {
+        ...createOrg(),
+        status: random.helpers.arrayElement(statuses) as Organization.Organization['status'],
+      }),
+    );
+
+    setState({ view, kanban, projection, change });
+    registry.set(items, initialItems);
+  }, [registry, items]);
+
+  const columnFieldPath =
+    state?.projection.tryGetFieldProjection(state.projection.getFieldId('status') ?? '')?.props.property ?? 'status';
+
+  const handleCardAdd = useCallback(
+    (columnValue: string | undefined) => {
+      if (!state || !columnFieldPath || !registry) {
+        return undefined;
+      }
+      const card = Obj.make(Organization.Organization, {
+        ...createOrg(),
+        ...(columnFieldPath ? { [columnFieldPath]: columnValue } : {}),
+      });
+      const current = registry.get(items) ?? [];
+      registry.set(items, [...current, card]);
+      return card.id;
+    },
+    [state, columnFieldPath, registry, items],
+  );
+
+  const handleCardRemove = useCallback(
+    (card: Obj.Unknown) => {
+      if (!registry) {
+        return;
+      }
+      const current = registry.get(items) ?? [];
+      registry.set(
+        items,
+        current.filter((i) => i.id !== card.id),
+      );
+    },
+    [registry, items],
+  );
+
+  if (!state) {
+    return <Loading />;
+  }
+
+  return (
+    <KanbanBoard.Root
+      kanban={state.kanban}
+      projection={state.projection}
+      items={items}
+      itemTile={KanbanCardTileSimple}
+      change={state.change}
+      onCardAdd={handleCardAdd}
+      onCardRemove={handleCardRemove}
+    >
+      <KanbanBoard.Content />
+    </KanbanBoard.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-kanban/components/KanbanBoard',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withMosaic(), withRegistry],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * In-memory board with Echo-shaped objects. No plugin manager, client, or Space.
+ */
+export const Default: Story = {};

package/src/components/KanbanBoard/KanbanBoard.tsx

@@ -0,0 +1,198 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, RegistryContext } from '@effect-atom/atom-react';
+import { createContext } from '@radix-ui/react-context';
+import React, {
+  type ComponentPropsWithoutRef,
+  type ComponentType,
+  type PropsWithChildren,
+  useCallback,
+  useContext,
+  useMemo,
+} from 'react';
+
+import { Obj } from '@dxos/echo';
+import { useTranslation } from '@dxos/react-ui';
+import { Board, useBoard } from '@dxos/react-ui-mosaic';
+import type { ProjectionModel } from '@dxos/schema';
+import { composable, composableProps } from '@dxos/ui-theme';
+
+import { useKanbanBoardModel, useKanbanColumnEventHandler } from '#hooks';
+import { meta } from '#meta';
+import { type Kanban, type KanbanChangeCallback, UNCATEGORIZED_ATTRIBUTES, UNCATEGORIZED_VALUE } from '#types';
+
+import { KanbanCard, type KanbanCardProps } from './KanbanCard';
+import { KanbanColumn, type KanbanColumnProps } from './KanbanColumn';
+
+// TODO(burdon): Rename Kanban.
+
+//
+// Context
+//
+
+const KANBAN_BOARD_NAME = 'KanbanBoard.Context';
+
+/**
+ * Context value for the Kanban board.
+ * Items are Echo objects (Obj.Unknown).
+ */
+type KanbanBoardContextValue = {
+  kanbanId: string;
+  projection: ProjectionModel | undefined;
+  columnFieldPath: string | undefined;
+  change: KanbanChangeCallback<Obj.Unknown>;
+  pivotFieldId: string | undefined;
+  getPivotAttributes: (columnValue: string) => { title: string; color: string };
+  itemTile?: ComponentType<KanbanCardProps>; // TODO(burdon): Prop.
+  onCardAdd?: (columnValue: string | undefined) => string | undefined;
+  onCardRemove?: (card: Obj.Unknown) => void;
+};
+
+const [KanbanBoardContext, useKanbanBoard] = createContext<KanbanBoardContextValue>(KANBAN_BOARD_NAME, {
+  kanbanId: 'never',
+  projection: undefined,
+  columnFieldPath: undefined,
+  change: { kanban: () => {}, setItemField: () => {} },
+  pivotFieldId: undefined,
+  getPivotAttributes: (id: string) =>
+    id === UNCATEGORIZED_VALUE ? UNCATEGORIZED_ATTRIBUTES : { title: id, color: 'neutral' },
+  itemTile: (() => null) as ComponentType<KanbanCardProps>,
+});
+
+//
+// Root
+//
+
+const KANBAN_BOARD_ROOT = 'KanbanBoard.Root';
+
+type KanbanBoardRootProps = PropsWithChildren<
+  {
+    kanban: Kanban.Kanban;
+    /** Required when providing context; Root derives columnFieldPath, pivotFieldId, getPivotAttributes from kanban + projection. */
+    projection: ProjectionModel;
+    /** Atom of items (e.g. from AtomQuery for DB, or Atom.make([]) for in-memory). */
+    items: Atom.Atom<Obj.Unknown[]>;
+    onCardAdd?: (columnValue: string | undefined) => string | undefined;
+    onCardRemove?: (card: Obj.Unknown) => void;
+  } & Pick<KanbanBoardContextValue, 'change' | 'itemTile'> &
+    ComponentPropsWithoutRef<'div'>
+>;
+
+export const KanbanBoardRoot = ({
+  children,
+  kanban,
+  projection,
+  items,
+  change,
+  itemTile = KanbanCard,
+  onCardAdd,
+  onCardRemove,
+}: KanbanBoardRootProps) => {
+  const registry = useContext(RegistryContext);
+  const { t } = useTranslation(meta.id);
+  const model = useKanbanBoardModel(kanban, projection, items, registry);
+  const columns = model?.getColumns?.() ?? [];
+  const view = kanban?.spec.kind === 'view' ? kanban.spec.view.target : undefined;
+  const pivotFieldId = view?.projection?.pivotFieldId;
+  const columnFieldPath = useMemo(() => {
+    // Items-variant kanbans use the property name itself as the pivot field
+    // (no view/projection translation layer).
+    if (kanban?.spec.kind === 'items') {
+      return kanban.spec.pivotField;
+    }
+    if (pivotFieldId === undefined || !projection) {
+      return undefined;
+    }
+
+    return projection.tryGetFieldProjection(pivotFieldId)?.props.property;
+  }, [kanban?.spec, projection, pivotFieldId]);
+
+  const getPivotAttributes = useCallback<KanbanBoardContextValue['getPivotAttributes']>(
+    (columnValue) => {
+      if (columnValue === UNCATEGORIZED_VALUE) {
+        return UNCATEGORIZED_ATTRIBUTES;
+      }
+
+      const options = projection?.tryGetFieldProjection(pivotFieldId ?? '')?.props.options ?? [];
+      const option = options.find((option) => option.id === columnValue);
+      return option ?? ({ title: columnValue, color: 'neutral' } as const);
+    },
+    [projection, pivotFieldId],
+  );
+
+  if (columns.length === 0) {
+    return (
+      <div role='none' className='flex flex-1 items-center justify-center p-8 text-center text-description'>
+        {t('select-pivot.placeholder')}
+      </div>
+    );
+  }
+
+  return (
+    <KanbanBoardContext
+      kanbanId={Obj.getDXN(kanban).toString()}
+      projection={projection}
+      columnFieldPath={columnFieldPath}
+      pivotFieldId={pivotFieldId}
+      getPivotAttributes={getPivotAttributes}
+      itemTile={itemTile}
+      change={change}
+      onCardAdd={onCardAdd}
+      onCardRemove={onCardRemove}
+    >
+      <Board.Root model={model}>{children}</Board.Root>
+    </KanbanBoardContext>
+  );
+};
+
+KanbanBoardRoot.displayName = KANBAN_BOARD_ROOT;
+
+//
+// KanbanBoardContent
+//
+
+const KANBAN_BOARD_CONTENT = 'KanbanBoard.Content';
+
+type KanbanBoardContentProps = {};
+
+export const KanbanBoardContent = composable<HTMLDivElement, KanbanBoardContentProps>((props, forwardedRef) => {
+  const { model } = useBoard(KANBAN_BOARD_CONTENT);
+  const { kanbanId, projection, pivotFieldId, change } = useKanbanBoard(KANBAN_BOARD_CONTENT);
+
+  const columnEventHandler = useKanbanColumnEventHandler({
+    id: `${kanbanId}-columns`,
+    model,
+    projection: projection ?? undefined,
+    pivotFieldId: pivotFieldId ?? undefined,
+    change,
+  });
+
+  return (
+    <Board.Content
+      {...composableProps(props)}
+      ref={forwardedRef}
+      id={kanbanId}
+      eventHandler={columnEventHandler}
+      Tile={KanbanColumn}
+    />
+  );
+});
+
+KanbanBoardContent.displayName = KANBAN_BOARD_CONTENT;
+
+//
+// KanbanBoard
+//
+
+export const KanbanBoard = {
+  Root: KanbanBoardRoot,
+  Content: KanbanBoardContent,
+  Column: KanbanColumn,
+  Card: KanbanCard,
+};
+
+export { useKanbanBoard };
+
+export type { KanbanBoardRootProps as KanbanBoardProps, KanbanCardProps, KanbanColumnProps };