@dxos/plugin-kanban 0.7.5-main.9d2a38b → 0.7.5-main.b19bfc8

package/src/KanbanPlugin.tsx

@@ -2,23 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import {
-  createIntent,
-  defineModule,
-  contributes,
-  Capabilities,
-  Events,
-  definePlugin,
-  oneOf,
-} from '@dxos/app-framework';
-import { ClientCapabilities, ClientEvents } from '@dxos/plugin-client';
-import { type Space } from '@dxos/react-client/echo';
+import { createIntent, defineModule, contributes, Capabilities, Events, definePlugin } from '@dxos/app-framework';
+import { ClientEvents } from '@dxos/plugin-client';
+import { SpaceCapabilities } from '@dxos/plugin-space';
+import { defineObjectForm } from '@dxos/plugin-space/types';
 import { KanbanType, translations as kanbanTranslations } from '@dxos/react-ui-kanban';
 
-import { IntentResolver, ReactSurface } from './capabilities';
+import { ArtifactDefinition, IntentResolver, ReactSurface } from './capabilities';
 import { KANBAN_PLUGIN, meta } from './meta';
 import translations from './translations';
-import { KanbanAction } from './types';
+import { CreateKanbanSchema, KanbanAction } from './types';
 
 export const KanbanPlugin = () =>
   definePlugin(meta, [
@@ -29,31 +22,42 @@ export const KanbanPlugin = () =>
     }),
     defineModule({
       id: `${meta.id}/module/metadata`,
-      activatesOn: oneOf(Events.Startup, Events.SetupAppGraph),
+      activatesOn: Events.SetupMetadata,
       activate: () =>
         contributes(Capabilities.Metadata, {
           id: KanbanType.typename,
           metadata: {
-            createObject: (props: { name?: string }, options: { space: Space }) =>
-              createIntent(KanbanAction.Create, { ...props, space: options.space }),
             placeholder: ['kanban title placeholder', { ns: KANBAN_PLUGIN }],
             icon: 'ph--kanban--regular',
           },
         }),
     }),
     defineModule({
-      id: `${meta.id}/module/schema`,
-      activatesOn: ClientEvents.SetupClient,
-      activate: () => contributes(ClientCapabilities.Schema, [KanbanType]),
+      id: `${meta.id}/module/object-form`,
+      activatesOn: ClientEvents.SetupSchema,
+      activate: () =>
+        contributes(
+          SpaceCapabilities.ObjectForm,
+          defineObjectForm({
+            objectSchema: KanbanType,
+            formSchema: CreateKanbanSchema,
+            getIntent: (props, options) => createIntent(KanbanAction.Create, { ...props, space: options.space }),
+          }),
+        ),
     }),
     defineModule({
       id: `${meta.id}/module/react-surface`,
-      activatesOn: Events.Startup,
+      activatesOn: Events.SetupReactSurface,
       activate: ReactSurface,
     }),
     defineModule({
       id: `${meta.id}/module/intent-resolver`,
-      activatesOn: Events.SetupIntents,
+      activatesOn: Events.SetupIntentResolver,
       activate: IntentResolver,
     }),
+    defineModule({
+      id: `${meta.id}/module/artifact-definition`,
+      activatesOn: Events.SetupArtifactDefinition,
+      activate: ArtifactDefinition,
+    }),
   ]);

package/src/capabilities/artifact-definition.ts

@@ -0,0 +1,131 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { pipe } from 'effect';
+
+import { Capabilities, chain, contributes, createIntent, type PromiseIntentDispatcher } from '@dxos/app-framework';
+import { defineArtifact, defineTool, ToolResult } from '@dxos/artifact';
+import { createArtifactElement } from '@dxos/assistant';
+import { isInstanceOf, S } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { SpaceAction } from '@dxos/plugin-space/types';
+import { Filter, fullyQualifiedId, type Space } from '@dxos/react-client/echo';
+import { KanbanType } from '@dxos/react-ui-kanban';
+
+import { KanbanAction } from '../types';
+
+const QualifiedId = S.String.annotations({
+  description: 'The fully qualified ID of the kanban `spaceID:objectID`',
+});
+
+declare global {
+  interface ToolContextExtensions {
+    space?: Space;
+    dispatch?: PromiseIntentDispatcher;
+  }
+}
+
+export default () => {
+  const definition = defineArtifact({
+    id: 'plugin-kanban',
+    instructions: `
+        When working with kanban boards here are some additional instructions:
+        - Before adding items to a kanban board, inspect the board to see its schema
+        - When adding items, you must not include the 'id' field -- it is automatically generated
+        - BEFORE adding items, always make sure the board has been shown to the user!
+      `,
+    schema: KanbanType,
+    tools: [
+      defineTool({
+        name: 'kanban_new',
+        description: `
+            Create a new kanban board using an existing schema.
+            Use schema_create first to create a schema, or schema_list to choose an existing one.`,
+        schema: S.Struct({
+          typename: S.String.annotations({
+            description: 'The fully qualified typename of the schema to use for the kanban cards.',
+          }),
+          pivotColumn: S.optional(S.String).annotations({
+            description: 'Optional field name to use as the column pivot.',
+          }),
+        }),
+        execute: async ({ typename, pivotColumn }, { extensions }) => {
+          invariant(extensions?.space, 'No space');
+          invariant(extensions?.dispatch, 'No intent dispatcher');
+
+          // Validate schema exists first
+          const schema = await extensions.space.db.schemaRegistry.query({ typename }).firstOrUndefined();
+          if (!schema) {
+            return ToolResult.Error(`Schema not found: ${typename}`);
+          }
+
+          const intent = pipe(
+            createIntent(KanbanAction.Create, {
+              space: extensions.space,
+              initialSchema: typename,
+              initialPivotColumn: pivotColumn,
+            }),
+            chain(SpaceAction.AddObject, { target: extensions.space }),
+          );
+
+          const { data, error } = await extensions.dispatch(intent);
+          if (!data || error) {
+            return ToolResult.Error(error?.message ?? 'Failed to create kanban board');
+          }
+
+          return ToolResult.Success(createArtifactElement(data.id));
+        },
+      }),
+      defineTool({
+        name: 'kanban_list',
+        description: 'List all kanban boards in the current space.',
+        schema: S.Struct({}),
+        execute: async (_input, { extensions }) => {
+          invariant(extensions?.space, 'No space');
+          const space = extensions.space;
+          const { objects: boards } = await space.db.query(Filter.schema(KanbanType)).run();
+
+          const boardInfo = await Promise.all(
+            boards.map(async (board: KanbanType) => {
+              const view = await board.cardView?.load();
+              return {
+                id: fullyQualifiedId(board),
+                typename: view?.query.type,
+              };
+            }),
+          );
+
+          return ToolResult.Success(boardInfo);
+        },
+      }),
+      defineTool({
+        name: 'kanban_inspect',
+        description: 'Get details about a specific kanban board.',
+        schema: S.Struct({ id: QualifiedId }),
+        execute: async ({ id }, { extensions }) => {
+          invariant(extensions?.space, 'No space');
+          const space = extensions.space;
+          const { objects: boards } = await space.db.query(Filter.schema(KanbanType)).run();
+          const board = boards.find((board: KanbanType) => fullyQualifiedId(board) === id);
+          invariant(isInstanceOf(KanbanType, board));
+
+          const view = await board.cardView?.load();
+          invariant(view);
+
+          const typename = view.query.type;
+          const schema = await space.db.schemaRegistry.query({ typename }).firstOrUndefined();
+          invariant(schema);
+
+          return ToolResult.Success({
+            schema,
+            columnField: board.columnFieldId,
+            viewFields: view.fields,
+          });
+        },
+      }),
+    ],
+  });
+
+  return contributes(Capabilities.ArtifactDefinition, definition);
+};

package/src/capabilities/index.ts

@@ -4,5 +4,6 @@
 
 import { lazy } from '@dxos/app-framework';
 
+export const ArtifactDefinition = lazy(() => import('./artifact-definition'));
 export const IntentResolver = lazy(() => import('./intent-resolver'));
 export const ReactSurface = lazy(() => import('./react-surface'));

package/src/capabilities/intent-resolver.ts

@@ -12,28 +12,54 @@ import { createKanban, KanbanAction } from '../types';
 
 export default () =>
   contributes(Capabilities.IntentResolver, [
-    createResolver(KanbanAction.Create, async ({ space }) => ({
-      data: { object: await createKanban(space) },
-    })),
-    createResolver(KanbanAction.DeleteCardField, ({ kanban, fieldId, deletionData }, undo) => {
-      invariant(kanban.cardView);
+    createResolver({
+      intent: KanbanAction.Create,
+      resolve: async ({ space, initialSchema, initialPivotColumn }) => ({
+        data: { object: await createKanban({ space, initialSchema, initialPivotColumn }) },
+      }),
+    }),
+    createResolver({
+      intent: KanbanAction.DeleteCardField,
+      resolve: ({ kanban, fieldId, deletionData }, undo) => {
+        invariant(kanban.cardView);
+        invariant(kanban.cardView.target?.query.type);
+
+        const schema =
+          kanban.cardView.target && getSpace(kanban)?.db.schemaRegistry.getSchema(kanban.cardView.target.query.type);
+        invariant(schema);
+        const projection = new ViewProjection(schema, kanban.cardView.target!);
 
-      const schema =
-        kanban.cardView.target && getSpace(kanban)?.db.schemaRegistry.getSchema(kanban.cardView.target.query.type);
-      invariant(schema);
-      const projection = new ViewProjection(schema, kanban.cardView.target!);
+        if (!undo) {
+          const { deleted, index } = projection.deleteFieldProjection(fieldId);
+          return {
+            undoable: {
+              message: ['card field deleted label', { ns: KANBAN_PLUGIN }],
+              data: { deletionData: { ...deleted, index } },
+            },
+          };
+        } else if (undo && deletionData) {
+          const { field, props, index } = deletionData;
+          projection.setFieldProjection({ field, props }, index);
+        }
+      },
+    }),
+    createResolver({
+      intent: KanbanAction.DeleteCard,
+      resolve: ({ card }, undo) => {
+        const space = getSpace(card);
+        invariant(space);
 
-      if (!undo) {
-        const { deleted, index } = projection.deleteFieldProjection(fieldId);
-        return {
-          undoable: {
-            message: ['card field deleted label', { ns: KANBAN_PLUGIN }],
-            data: { deletionData: { ...deleted, index } },
-          },
-        };
-      } else if (undo && deletionData) {
-        const { field, props, index } = deletionData;
-        projection.setFieldProjection({ field, props }, index);
-      }
+        if (!undo) {
+          space.db.remove(card);
+          return {
+            undoable: {
+              message: ['card deleted label', { ns: KANBAN_PLUGIN }],
+              data: { card },
+            },
+          };
+        } else {
+          space.db.add(card);
+        }
+      },
     }),
   ]);

package/src/capabilities/react-surface.tsx

@@ -2,14 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import React, { useMemo } from 'react';
 
 import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
+import { type S } from '@dxos/echo-schema';
+import { findAnnotation } from '@dxos/effect';
+import { type CollectionType } from '@dxos/plugin-space/types';
+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 { KanbanContainer, KanbanViewEditor } from '../components';
 import { KANBAN_PLUGIN } from '../meta';
-import { isKanban } from '../types';
+import { isKanban, InitialSchemaAnnotationId, InitialPivotColumnAnnotationId } from '../types';
 
 export default () =>
   contributes(Capabilities.ReactSurface, [
@@ -25,4 +30,60 @@ export default () =>
       filter: (data): data is { subject: KanbanType } => isKanban(data.subject),
       component: ({ data }) => <KanbanViewEditor kanban={data.subject} />,
     }),
+    createSurface({
+      id: `${KANBAN_PLUGIN}/create-initial-schema-form-[schema]`,
+      role: 'form-input',
+      filter: (data): data is { prop: string; schema: S.Schema<any>; target: Space | CollectionType | undefined } => {
+        const annotation = findAnnotation<boolean>((data.schema as S.Schema.All).ast, InitialSchemaAnnotationId);
+        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 schemata = space?.db.schemaRegistry.query().runSync();
+
+        return <SelectInput {...props} options={schemata.map((schema) => ({ value: schema.typename }))} />;
+      },
+    }),
+    createSurface({
+      id: `${KANBAN_PLUGIN}/create-initial-schema-form-[pivot-column]`,
+      role: 'form-input',
+      filter: (data): data is { prop: string; schema: S.Schema<any>; target: Space | CollectionType | undefined } => {
+        const annotation = findAnnotation<boolean>((data.schema as S.Schema.All).ast, InitialPivotColumnAnnotationId);
+        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 { initialSchema } = useFormValues();
+        const [selectedSchema] = space?.db.schemaRegistry.query({ typename: initialSchema }).runSync();
+
+        const singleSelectColumns = useMemo(() => {
+          if (!selectedSchema?.jsonSchema?.properties) {
+            return [];
+          }
+
+          const columns = Object.entries(selectedSchema.jsonSchema.properties).reduce<string[]>((acc, [key, value]) => {
+            if (typeof value === 'object' && value?.format === 'single-select') {
+              acc.push(key);
+            }
+            return acc;
+          }, []);
+
+          return columns;
+        }, [selectedSchema?.jsonSchema]);
+
+        if (!initialSchema) {
+          return null;
+        }
+
+        return <SelectInput {...props} options={singleSelectColumns.map((column) => ({ value: column }))} />;
+      },
+    }),
   ]);

package/src/components/KanbanContainer.tsx

@@ -4,21 +4,44 @@
 
 import React, { useCallback, useEffect, useState } from 'react';
 
+import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
 import { type EchoSchema } from '@dxos/echo-schema';
-import { invariant } from '@dxos/invariant';
 import { useGlobalFilteredObjects } from '@dxos/plugin-search';
 import { Filter, useQuery, getSpace, create } from '@dxos/react-client/echo';
 import { type KanbanType, useKanbanModel, Kanban } from '@dxos/react-ui-kanban';
 import { StackItem } from '@dxos/react-ui-stack';
+import { ViewProjection } from '@dxos/schema';
+
+import { KanbanAction } from '../types';
 
 export const KanbanContainer = ({ kanban }: { kanban: KanbanType; role: string }) => {
   const [cardSchema, setCardSchema] = useState<EchoSchema>();
+  const [projection, setProjection] = useState<ViewProjection>();
   const space = getSpace(kanban);
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+
+  useEffect(() => {
+    if (kanban.cardView?.target?.query?.type && space) {
+      const query = space.db.schemaRegistry.query({ typename: kanban.cardView.target.query.type });
+      const unsubscribe = query.subscribe(
+        () => {
+          const [schema] = query.results;
+          if (schema) {
+            setCardSchema(schema);
+          }
+        },
+        { fire: true },
+      );
+      return unsubscribe;
+    }
+  }, [kanban.cardView?.target?.query, space]);
+
   useEffect(() => {
-    if (kanban.cardView && space) {
-      setCardSchema(space.db.schemaRegistry.getSchema(kanban.cardView.target!.query.type));
+    if (kanban.cardView?.target && cardSchema) {
+      setProjection(new ViewProjection(cardSchema, kanban.cardView.target));
     }
-  }, [kanban.cardView, space]);
+    // TODO(ZaymonFC): Is there a better way to get notified about deep changes in the json schema?
+  }, [kanban.cardView?.target, cardSchema, JSON.stringify(cardSchema?.jsonSchema)]);
 
   const objects = useQuery(space, cardSchema ? Filter.schema(cardSchema) : Filter.nothing());
   const filteredObjects = useGlobalFilteredObjects(objects);
@@ -26,54 +49,32 @@ export const KanbanContainer = ({ kanban }: { kanban: KanbanType; role: string }
   const model = useKanbanModel({
     kanban,
     cardSchema,
+    projection,
     items: filteredObjects,
   });
 
-  const handleAddColumn = useCallback((columnValue: string) => model?.addEmptyColumn(columnValue), [model]);
-
   const handleAddCard = useCallback(
-    (columnValue: string) => {
-      if (space && cardSchema) {
-        space.db.add(
-          create(cardSchema, {
-            title: '',
-            description: '',
-            state: columnValue,
-          }),
-        );
+    (columnValue: string | undefined) => {
+      const path = model?.columnFieldPath;
+      if (space && cardSchema && path) {
+        const card = create(cardSchema, { [path]: columnValue });
+        space.db.add(card);
+        return card.id;
       }
     },
-    [space, cardSchema],
+    [space, cardSchema, model],
   );
 
   const handleRemoveCard = useCallback(
     (card: { id: string }) => {
-      invariant(space);
-      space.db.remove(card);
-    },
-    [space],
-  );
-
-  const handleRemoveEmptyColumn = useCallback(
-    (columnValue: string) => {
-      model?.removeColumnFromArrangement(columnValue);
+      void dispatch(createIntent(KanbanAction.DeleteCard, { card }));
     },
-    [model],
+    [dispatch],
   );
 
   return (
     <StackItem.Content toolbar={false}>
-      {model ? (
-        <Kanban
-          model={model}
-          onAddCard={handleAddCard}
-          onAddColumn={handleAddColumn}
-          onRemoveCard={handleRemoveCard}
-          onRemoveEmptyColumn={handleRemoveEmptyColumn}
-        />
-      ) : (
-        <span>Loading</span>
-      )}
+      {model && <Kanban model={model} onAddCard={handleAddCard} onRemoveCard={handleRemoveCard} />}
     </StackItem.Content>
   );
 };

package/src/components/KanbanViewEditor.tsx

@@ -1,14 +1,16 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useMemo } from 'react';
 
 import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
-import { Filter, getSpace, useQuery } from '@dxos/react-client/echo';
-import { ViewEditor, Form } from '@dxos/react-ui-form';
-import { type KanbanType, KanbanPropsSchema } from '@dxos/react-ui-kanban';
-import { ViewType } from '@dxos/schema';
+import { FormatEnum } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { Filter, getSpace, useQuery, useSchema } from '@dxos/react-client/echo';
+import { ViewEditor, Form, SelectInput, type CustomInputMap } from '@dxos/react-ui-form';
+import { type KanbanType, KanbanSettingsSchema } from '@dxos/react-ui-kanban';
+import { ViewType, ViewProjection } from '@dxos/schema';
 
 import { KanbanAction } from '../types';
 
@@ -17,22 +19,13 @@ type KanbanViewEditorProps = { kanban: KanbanType };
 export const KanbanViewEditor = ({ kanban }: KanbanViewEditorProps) => {
   const { dispatchPromise: dispatch } = useIntentDispatcher();
   const space = getSpace(kanban);
-
-  // TODO(ZaymonFC): The schema registry needs an API where we can query with initial value and
-  // endure typename changes. We shouldn't need to manage a subscription at this layer.
-  const [schema, setSchema] = useState(
-    space && kanban?.cardView?.target?.query?.type
-      ? space.db.schemaRegistry.getSchema(kanban.cardView.target.query.type)
-      : undefined,
-  );
-
-  const views = useQuery(space, Filter.schema(ViewType));
   const currentTypename = useMemo(() => kanban?.cardView?.target?.query?.type, [kanban?.cardView?.target?.query?.type]);
+  const schema = useSchema(space, currentTypename);
+  const views = useQuery(space, Filter.schema(ViewType));
+
   const updateViewTypename = useCallback(
     (newTypename: string) => {
-      if (!schema) {
-        return;
-      }
+      invariant(schema);
       const matchingViews = views.filter((view) => view.query.type === currentTypename);
       for (const view of matchingViews) {
         view.query.type = newTypename;
@@ -42,40 +35,48 @@ export const KanbanViewEditor = ({ kanban }: KanbanViewEditorProps) => {
     [views, schema],
   );
 
-  useEffect(() => {
-    if (space && kanban?.cardView?.target?.query?.type) {
-      const unsubscribe = space.db.schemaRegistry
-        .query({ typename: kanban?.cardView?.target?.query?.type })
-        .subscribe((query) => {
-          const [schema] = query.results;
-          if (schema) {
-            setSchema(schema);
-          }
-        });
-
-      return unsubscribe;
-    }
-  }, [space, kanban?.cardView?.target?.query?.type]);
-
   const handleDelete = useCallback(
     (fieldId: string) => dispatch?.(createIntent(KanbanAction.DeleteCardField, { kanban, fieldId })),
     [dispatch, kanban],
   );
 
+  const projection = useMemo(() => {
+    if (kanban?.cardView?.target && schema) {
+      return new ViewProjection(schema, kanban.cardView.target);
+    }
+  }, [kanban?.cardView?.target, schema, JSON.stringify(schema)]);
+
+  const selectFields = useMemo(() => {
+    if (!projection) {
+      return [];
+    }
+
+    return projection
+      .getFieldProjections()
+      .filter((field) => field.props.format === FormatEnum.SingleSelect)
+      .map(({ field }) => ({ value: field.id, label: field.path }));
+  }, [projection]);
+
+  const onSave = useCallback(
+    (values: Partial<{ columnFieldId: string }>) => {
+      kanban.columnFieldId = values.columnFieldId;
+    },
+    [kanban],
+  );
+
+  const initialValues = useMemo(() => ({ columnFieldId: kanban.columnFieldId }), [kanban]);
+  const custom: CustomInputMap = useMemo(
+    () => ({ columnFieldId: (props) => <SelectInput {...props} options={selectFields} /> }),
+    [selectFields],
+  );
+
   if (!space || !schema || !kanban.cardView?.target) {
     return null;
   }
 
   return (
     <>
-      <Form
-        schema={KanbanPropsSchema}
-        values={{ columnField: kanban.columnField }}
-        onSave={({ columnField }) => {
-          kanban.columnField = columnField;
-          kanban.arrangement = undefined;
-        }}
-      />
+      <Form schema={KanbanSettingsSchema} values={initialValues} onSave={onSave} autoSave Custom={custom} />
       <ViewEditor
         registry={space.db.schemaRegistry}
         schema={schema}

package/src/meta.ts

@@ -9,8 +9,10 @@ export const KANBAN_PLUGIN = 'dxos.org/plugin/kanban';
 export const meta = {
   id: KANBAN_PLUGIN,
   name: 'Kanban',
-  description: 'Kanban board for managing tasks.',
+  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.',
   icon: 'ph--kanban--regular',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/experimental/plugin-kanban',
   tags: ['experimental'],
+  screenshots: ['https://dxos.network/plugin-details-kanban-dark.png'],
 } satisfies PluginMeta;

package/src/translations.ts

@@ -26,6 +26,7 @@ export default [
         'delete item label': 'Delete card',
         'create kanban label': 'Create kanban',
         'card field deleted label': 'Card field deleted',
+        'card deleted label': 'Card deleted',
       },
     },
   },