@dxos/plugin-kanban 0.7.4 → 0.7.5-labs.401163d

package/src/capabilities/intent-resolver.ts

@@ -0,0 +1,64 @@
+//
+// 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, initialSchema, initialPivotColumn }) => ({
+        data: { object: await createKanban({ space, initialSchema, initialPivotColumn }) },
+      }),
+    }),
+    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);
+        }
+      },
+    }),
+    createResolver({
+      intent: KanbanAction.DeleteCard,
+      resolve: ({ card }, undo) => {
+        const space = getSpace(card);
+        invariant(space);
+
+        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

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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, InitialSchemaAnnotationId, InitialPivotColumnAnnotationId } 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} />,
+    }),
+    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

@@ -0,0 +1,84 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback, useEffect, useState } from 'react';
+
+import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+import { type EchoSchema } from '@dxos/echo-schema';
+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?.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) {
+        const card = create(cardSchema, { [path]: columnValue });
+        space.db.add(card);
+        return card.id;
+      }
+    },
+    [space, cardSchema, model],
+  );
+
+  const handleRemoveCard = useCallback(
+    (card: { id: string }) => {
+      void dispatch(createIntent(KanbanAction.DeleteCard, { card }));
+    },
+    [dispatch],
+  );
+
+  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,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
+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';
+
+type KanbanViewEditorProps = { kanban: KanbanType };
+
+export const KanbanViewEditor = ({ kanban }: KanbanViewEditorProps) => {
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+  const space = getSpace(kanban);
+  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) => {
+      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,12 @@ 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',
+        'card deleted label': 'Card deleted',
       },
     },
   },

package/src/types.ts

@@ -0,0 +1,102 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { TitleAnnotationId } from '@effect/schema/AST';
+
+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 const InitialSchemaAnnotationId = Symbol.for('@dxos/plugin-kanban/annotation/InitialSchema');
+export const InitialPivotColumnAnnotationId = Symbol.for('@dxos/plugin-kanban/annotation/InitialPivotColumn');
+
+export const CreateKanbanSchema = S.Struct({
+  name: S.optional(S.String),
+  initialSchema: S.optional(
+    S.String.annotations({
+      [InitialSchemaAnnotationId]: true,
+      [TitleAnnotationId]: 'Select card schema (leave empty to start fresh)',
+    }),
+  ),
+  initialPivotColumn: S.optional(
+    S.String.annotations({
+      [InitialPivotColumnAnnotationId]: true,
+      [TitleAnnotationId]: 'Pivot column',
+    }),
+  ),
+});
+
+export type CreateKanbanType = S.Schema.Type<typeof CreateKanbanSchema>;
+
+export namespace KanbanAction {
+  const KANBAN_ACTION = `${KANBAN_PLUGIN}/action`;
+
+  export class Create extends S.TaggedClass<Create>()(`${KANBAN_ACTION}/create`, {
+    input: S.extend(S.Struct({ space: SpaceSchema }), CreateKanbanSchema),
+    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,
+  }) {}
+
+  export class DeleteCard extends S.TaggedClass<DeleteCard>()(`${KANBAN_ACTION}/delete-card`, {
+    input: S.Struct({
+      card: S.Any, // The card object to delete
+    }),
+    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 (props: { space: Space; initialSchema?: string; initialPivotColumn?: string }) => {
+  const { kanban } = await initializeKanban(props);
+  return kanban;
+};