@dxos/plugin-kanban 0.7.4 → 0.7.5-labs.071a3e2

package/src/KanbanPlugin.tsx

@@ -2,110 +2,50 @@
 // Copyright 2023 DXOS.org
 //
 
-import React from 'react';
+import { createIntent, defineModule, contributes, Capabilities, Events, definePlugin } from '@dxos/app-framework';
+import { ClientCapabilities, ClientEvents } from '@dxos/plugin-client';
+import { type Space } from '@dxos/react-client/echo';
+import { KanbanType, translations as kanbanTranslations } from '@dxos/react-ui-kanban';
 
-import { resolvePlugin, type PluginDefinition, parseIntentPlugin, NavigationAction } from '@dxos/app-framework';
-import { create } from '@dxos/live-object';
-import { parseClientPlugin } from '@dxos/plugin-client';
-import { type ActionGroup, createExtension, isActionGroup } from '@dxos/plugin-graph';
-import { SpaceAction } from '@dxos/plugin-space';
-import { loadObjectReferences } from '@dxos/react-client/echo';
-
-import { KanbanMain } from './components';
-import meta, { KANBAN_PLUGIN } from './meta';
+import { IntentResolver, ReactSurface } from './capabilities';
+import { KANBAN_PLUGIN, meta } from './meta';
 import translations from './translations';
-import { KanbanColumnType, KanbanItemType, KanbanType } from './types';
-import { KanbanAction, type KanbanPluginProvides } from './types';
+import { KanbanAction } from './types';
 
-export const KanbanPlugin = (): PluginDefinition<KanbanPluginProvides> => {
-  return {
-    meta,
-    provides: {
-      metadata: {
-        records: {
-          [KanbanType.typename]: {
-            createObject: KanbanAction.CREATE,
+export const KanbanPlugin = () =>
+  definePlugin(meta, [
+    defineModule({
+      id: `${meta.id}/module/translations`,
+      activatesOn: Events.SetupTranslations,
+      activate: () => contributes(Capabilities.Translations, [...translations, ...kanbanTranslations]),
+    }),
+    defineModule({
+      id: `${meta.id}/module/metadata`,
+      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',
-            // TODO(wittjosiah): Move out of metadata.
-            loadReferences: (kanban: KanbanType) => loadObjectReferences(kanban, (kanban) => kanban.columns),
-          },
-          [KanbanColumnType.typename]: {
-            // TODO(wittjosiah): Move out of metadata.
-            loadReferences: (column: KanbanColumnType) => loadObjectReferences(column, (column) => column.items),
-          },
-          [KanbanItemType.typename]: {
-            // TODO(wittjosiah): Move out of metadata.
-            loadReferences: (item: KanbanItemType) => [], // loadObjectReferences(item, (item) => item.object),
           },
-        },
-      },
-      echo: {
-        schema: [KanbanType],
-        system: [KanbanColumnType, KanbanItemType],
-      },
-      translations,
-      graph: {
-        builder: (plugins) => {
-          const client = resolvePlugin(plugins, parseClientPlugin)?.provides.client;
-          const dispatch = resolvePlugin(plugins, parseIntentPlugin)?.provides.intent.dispatch;
-          if (!client || !dispatch) {
-            return [];
-          }
-
-          return createExtension({
-            id: KanbanAction.CREATE,
-            filter: (node): node is ActionGroup => isActionGroup(node) && node.id.startsWith(SpaceAction.ADD_OBJECT),
-            actions: ({ node }) => {
-              const id = node.id.split('/').at(-1);
-              const [spaceId, objectId] = id?.split(':') ?? [];
-              const space = client.spaces.get().find((space) => space.id === spaceId);
-              const object = objectId && space?.db.getObjectById(objectId);
-              const target = objectId ? object : space;
-              if (!target) {
-                return;
-              }
-
-              return [
-                {
-                  id: `${KANBAN_PLUGIN}/create/${node.id}`,
-                  data: async () => {
-                    await dispatch([
-                      { plugin: KANBAN_PLUGIN, action: KanbanAction.CREATE },
-                      { action: SpaceAction.ADD_OBJECT, data: { target } },
-                      { action: NavigationAction.OPEN },
-                    ]);
-                  },
-                  properties: {
-                    label: ['create kanban label', { ns: KANBAN_PLUGIN }],
-                    icon: 'ph--kanban--regular',
-                    testId: 'kanbanPlugin.createObject',
-                  },
-                },
-              ];
-            },
-          });
-        },
-      },
-      surface: {
-        component: ({ data, role }) => {
-          switch (role) {
-            case 'main':
-              return data.active instanceof KanbanType ? <KanbanMain kanban={data.active} /> : null;
-            default:
-              return null;
-          }
-        },
-      },
-      intent: {
-        resolver: (intent) => {
-          switch (intent.action) {
-            case KanbanAction.CREATE: {
-              return { data: create(KanbanType, { columns: [] }) };
-            }
-          }
-        },
-      },
-    },
-  };
-};
+        }),
+    }),
+    defineModule({
+      id: `${meta.id}/module/schema`,
+      activatesOn: ClientEvents.SetupSchema,
+      activate: () => contributes(ClientCapabilities.Schema, [KanbanType]),
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-surface`,
+      activatesOn: Events.SetupSurfaces,
+      activate: ReactSurface,
+    }),
+    defineModule({
+      id: `${meta.id}/module/intent-resolver`,
+      activatesOn: Events.SetupIntents,
+      activate: IntentResolver,
+    }),
+  ]);

package/src/capabilities/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const IntentResolver = lazy(() => import('./intent-resolver'));
+export const ReactSurface = lazy(() => import('./react-surface'));

package/src/capabilities/intent-resolver.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { contributes, Capabilities, createResolver } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+import { getSpace } from '@dxos/react-client/echo';
+import { ViewProjection } from '@dxos/schema';
+
+import { KANBAN_PLUGIN } from '../meta';
+import { createKanban, KanbanAction } from '../types';
+
+export default () =>
+  contributes(Capabilities.IntentResolver, [
+    createResolver({
+      intent: KanbanAction.Create,
+      resolve: async ({ space }) => ({
+        data: { object: await createKanban(space) },
+      }),
+    }),
+    createResolver({
+      intent: KanbanAction.DeleteCardField,
+      resolve: ({ kanban, fieldId, deletionData }, undo) => {
+        invariant(kanban.cardView);
+
+        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);
+        }
+      },
+    }),
+  ]);

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
+import { type KanbanType } from '@dxos/react-ui-kanban';
+
+import { KanbanContainer, KanbanViewEditor } from '../components';
+import { KANBAN_PLUGIN } from '../meta';
+import { isKanban } from '../types';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, [
+    createSurface({
+      id: `${KANBAN_PLUGIN}/kanban`,
+      role: ['article', 'section'],
+      filter: (data): data is { subject: KanbanType } => isKanban(data.subject),
+      component: ({ data, role }) => <KanbanContainer kanban={data.subject} role={role} />,
+    }),
+    createSurface({
+      id: `${KANBAN_PLUGIN}/settings`,
+      role: 'complementary--settings',
+      filter: (data): data is { subject: KanbanType } => isKanban(data.subject),
+      component: ({ data }) => <KanbanViewEditor kanban={data.subject} />,
+    }),
+  ]);

package/src/components/KanbanContainer.tsx

@@ -0,0 +1,80 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback, useEffect, useState } from 'react';
+
+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';
+
+export const KanbanContainer = ({ kanban }: { kanban: KanbanType; role: string }) => {
+  const [cardSchema, setCardSchema] = useState<EchoSchema>();
+  const [projection, setProjection] = useState<ViewProjection>();
+  const space = getSpace(kanban);
+
+  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?.target && cardSchema) {
+      setProjection(new ViewProjection(cardSchema, kanban.cardView.target));
+    }
+    // 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);
+
+  const model = useKanbanModel({
+    kanban,
+    cardSchema,
+    projection,
+    items: filteredObjects,
+  });
+
+  const handleAddCard = useCallback(
+    (columnValue: string | undefined) => {
+      const path = model?.columnFieldPath;
+      if (space && cardSchema && path) {
+        space.db.add(create(cardSchema, { [path]: columnValue }));
+      }
+    },
+    [space, cardSchema, model],
+  );
+
+  const handleRemoveCard = useCallback(
+    (card: { id: string }) => {
+      invariant(space);
+      space.db.remove(card);
+    },
+    [space],
+  );
+
+  return (
+    <StackItem.Content toolbar={false}>
+      {model ? (
+        <Kanban model={model} onAddCard={handleAddCard} onRemoveCard={handleRemoveCard} />
+      ) : (
+        <span>Loading</span>
+      )}
+    </StackItem.Content>
+  );
+};

package/src/components/KanbanViewEditor.tsx

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+import { type EchoSchema, FormatEnum } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { Filter, getSpace, useQuery } 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';
+
+type KanbanViewEditorProps = { kanban: KanbanType };
+
+export const KanbanViewEditor = ({ kanban }: KanbanViewEditorProps) => {
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+  const space = getSpace(kanban);
+
+  const [schema, setSchema] = useState<EchoSchema | undefined>();
+
+  useEffect(() => {
+    if (space && kanban?.cardView?.target?.query?.type) {
+      const query = space.db.schemaRegistry.query({ typename: kanban.cardView.target.query.type });
+      const unsubscribe = query.subscribe(
+        () => {
+          const [schema] = query.results;
+          if (schema) {
+            setSchema(schema);
+          }
+        },
+        { fire: true },
+      );
+      return unsubscribe;
+    }
+  }, [space, kanban?.cardView?.target?.query?.type]);
+
+  const views = useQuery(space, Filter.schema(ViewType));
+  const currentTypename = useMemo(() => kanban?.cardView?.target?.query?.type, [kanban?.cardView?.target?.query?.type]);
+  const updateViewTypename = useCallback(
+    (newTypename: string) => {
+      invariant(schema);
+      const matchingViews = views.filter((view) => view.query.type === currentTypename);
+      for (const view of matchingViews) {
+        view.query.type = newTypename;
+      }
+      schema.updateTypename(newTypename);
+    },
+    [views, schema],
+  );
+
+  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={KanbanSettingsSchema} values={initialValues} onSave={onSave} autoSave Custom={custom} />
+      <ViewEditor
+        registry={space.db.schemaRegistry}
+        schema={schema}
+        view={kanban.cardView.target}
+        onTypenameChanged={updateViewTypename}
+        onDelete={handleDelete}
+      />
+    </>
+  );
+};

package/src/components/index.ts

@@ -1,7 +1,6 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2024 DXOS.org
 //
 
-import { lazy } from 'react';
-
-export const KanbanMain = lazy(() => import('./KanbanMain'));
+export * from './KanbanContainer';
+export * from './KanbanViewEditor';

package/src/index.ts

@@ -2,8 +2,5 @@
 // Copyright 2023 DXOS.org
 //
 
-import { KanbanPlugin } from './KanbanPlugin';
-
-export default KanbanPlugin;
-
 export * from './KanbanPlugin';
+export * from './meta';

package/src/meta.ts

@@ -6,11 +6,13 @@ import { type PluginMeta } from '@dxos/app-framework';
 
 export const KANBAN_PLUGIN = 'dxos.org/plugin/kanban';
 
-export default {
+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

@@ -2,11 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
+import { KanbanType } from '@dxos/react-ui-kanban';
+
 import { KANBAN_PLUGIN } from './meta';
 
 export default [
   {
     'en-US': {
+      [KanbanType.typename]: {
+        'typename label': 'Kanban',
+      },
       [KANBAN_PLUGIN]: {
         'plugin name': 'Kanban',
         'kanban title label': 'Title',
@@ -16,10 +21,11 @@ export default [
         'item title label': 'Item title',
         'item title placeholder': 'New item',
         'add column label': 'Add column',
-        'add item label': 'Add item',
+        'add item label': 'Add card',
         'delete column label': 'Delete column',
-        'delete item label': 'Delete item',
+        'delete item label': 'Delete card',
         'create kanban label': 'Create kanban',
+        'card field deleted label': 'Card field deleted',
       },
     },
   },

package/src/types.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { S } from '@dxos/echo-schema';
+import { type Space, SpaceSchema } from '@dxos/react-client/echo';
+import { KanbanType } from '@dxos/react-ui-kanban';
+import { initializeKanban } from '@dxos/react-ui-kanban/testing';
+import { FieldSchema } from '@dxos/schema';
+
+import { KANBAN_PLUGIN } from './meta';
+
+/**
+ * Kanban data model.
+ * A Kanban board is a collection of columns, each of which contains a collection of items.
+ * The layout of columns and items is controlled by models.
+ * The underlying data model may be represented by direct object relationships
+ * (e.g., a column object containing an array of ordered items) or projections constructed
+ * by the model (e.g., a query of items based on metadata within a column object).
+ */
+
+export namespace KanbanAction {
+  const KANBAN_ACTION = `${KANBAN_PLUGIN}/action`;
+
+  export class Create extends S.TaggedClass<Create>()(`${KANBAN_ACTION}/create`, {
+    input: S.Struct({
+      name: S.optional(S.String),
+      space: SpaceSchema,
+    }),
+    output: S.Struct({
+      object: KanbanType,
+    }),
+  }) {}
+
+  export class DeleteCardField extends S.TaggedClass<DeleteCardField>()(`${KANBAN_ACTION}/delete-card-field`, {
+    input: S.Struct({
+      kanban: KanbanType,
+      fieldId: S.String,
+      // TODO(wittjosiah): Separate fields for undo data?
+      deletionData: S.optional(
+        S.Struct({
+          field: FieldSchema,
+          // TODO(wittjosiah): This creates a type error.
+          // props: PropertySchema,
+          props: S.Any,
+          index: S.Number,
+        }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+}
+
+// TODO(burdon): Undo?
+// TODO(burdon): Typescript types (replace proto with annotations?)
+// TODO(burdon): Should pure components depend on ECHO? Relationship between ECHO object/array and Observable.
+// TODO(burdon): Can the plugin configure the object based on the data? E.g., how are the models constructed?
+// TODO(burdon): Create models. Simple first based on actual data.
+//  Model is always a projection since the dragging state is tentative.
+
+// TODO(burdon): Extend model for moving items (in and across columns).
+export interface KanbanModel {
+  root: KanbanType;
+}
+
+export type Location = {
+  idx?: number;
+};
+
+export const isKanban = (object: unknown): object is KanbanType => object != null && object instanceof KanbanType;
+
+export const createKanban = async (space: Space) => {
+  const { kanban } = await initializeKanban({ space });
+  return kanban;
+};