@dxos/plugin-kanban 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/src/components/KanbanBoard/KanbanCard.tsx

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { forwardRef, useCallback, useMemo, useState } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface, useObjectMenuItems } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { Card, Toolbar, useTranslation } from '@dxos/react-ui';
+import { Menu, createMenuAction } from '@dxos/react-ui-menu';
+import { Focus, Mosaic, useBoard } from '@dxos/react-ui-mosaic';
+
+import { meta } from '#meta';
+
+import { type KanbanCardProps, useKanbanBoard } from './context';
+
+export { type KanbanCardProps };
+
+const KANBAN_CARD_TILE_NAME = 'KanbanBoard.Card';
+
+/**
+ * Mosaic Tile for Kanban card.
+ * Uses Surface for content; requires plugin manager context.
+ */
+export const KanbanCard = forwardRef<HTMLDivElement, KanbanCardProps>(
+  ({ data, location, debug, draggable }, forwardedRef) => {
+    const { t } = useTranslation(meta.id);
+    const { model } = useBoard(KANBAN_CARD_TILE_NAME);
+    const { projection, columnFieldPath, onCardRemove } = useKanbanBoard(KANBAN_CARD_TILE_NAME);
+    const [dragHandle, setDragHandle] = useState<HTMLButtonElement | null>(null);
+    const dragHandleRef = useCallback((el: HTMLButtonElement | null) => setDragHandle(el), []);
+
+    const objectMenuItems = useObjectMenuItems(data);
+
+    const menuItems = useMemo(
+      () => [
+        ...objectMenuItems,
+        ...(onCardRemove
+          ? [
+              createMenuAction('remove', () => onCardRemove(data), {
+                label: t('remove-card.label'),
+                icon: 'ph--trash--regular',
+              }),
+            ]
+          : []),
+      ],
+      [objectMenuItems, onCardRemove, data, t],
+    );
+
+    return (
+      <Menu.Root>
+        <Mosaic.Tile
+          asChild
+          id={model.getItemId(data)}
+          data={data}
+          location={location}
+          debug={debug}
+          draggable={draggable}
+          dragHandle={dragHandle}
+        >
+          <Focus.Item asChild>
+            <Card.Root ref={forwardedRef} data-testid='board-item'>
+              <Card.Toolbar>
+                <Card.DragHandle ref={dragHandleRef} testId='mosaicBoard.cardDragHandle' />
+                <Card.Title data-testid='mosaicBoard.cardTitle'>{Obj.getLabel(data)}</Card.Title>
+                {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
+                <Menu.Trigger asChild disabled={!menuItems?.length}>
+                  <Toolbar.IconButton
+                    iconOnly
+                    variant='ghost'
+                    icon='ph--dots-three-vertical--regular'
+                    label={t('action-menu.label')}
+                  />
+                </Menu.Trigger>
+                <Menu.Content items={menuItems} />
+              </Card.Toolbar>
+              <Card.Content>
+                {projection && (
+                  <Surface.Surface
+                    type={AppSurface.Card}
+                    limit={1}
+                    data={{
+                      subject: data,
+                      projection,
+                      // Hide the pivot field: its value is already conveyed by
+                      // which column the card sits in.
+                      ignorePaths: columnFieldPath ? [columnFieldPath] : undefined,
+                    }}
+                  />
+                )}
+              </Card.Content>
+            </Card.Root>
+          </Focus.Item>
+        </Mosaic.Tile>
+      </Menu.Root>
+    );
+  },
+);
+
+KanbanCard.displayName = KANBAN_CARD_TILE_NAME;

package/src/components/KanbanBoard/KanbanColumn.tsx

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { FC, forwardRef, useState } from 'react';
+
+import type { Obj } from '@dxos/echo';
+import { Board, type MosaicTileProps, useBoard } from '@dxos/react-ui-mosaic';
+
+import { useKanbanItemEventHandler } from '#hooks';
+import { type ColumnStructure, UNCATEGORIZED_VALUE } from '#types';
+
+import { type KanbanColumnProps, useKanbanBoard } from './context';
+
+export { type KanbanColumnProps };
+
+const KANBAN_COLUMN_NAME = 'KanbanBoard.Column';
+
+/**
+ * Mosaic Tile for Kanban column.
+ */
+export const KanbanColumn = forwardRef<HTMLDivElement, KanbanColumnProps>(
+  ({ data: column, location, debug, draggable }, forwardedRef) => {
+    const { model } = useBoard<ColumnStructure, Obj.Unknown>(KANBAN_COLUMN_NAME);
+    const { columnFieldPath, change, onCardAdd, getPivotAttributes, itemTile } = useKanbanBoard(KANBAN_COLUMN_NAME);
+
+    const { title } = getPivotAttributes(column.columnValue);
+    const uncategorized = column.columnValue === UNCATEGORIZED_VALUE;
+    const [dragHandle, setDragHandle] = useState<HTMLButtonElement | null>(null);
+
+    const eventHandler = useKanbanItemEventHandler({
+      column,
+      columnFieldPath,
+      model,
+      change,
+    });
+
+    return (
+      <Board.Column.Root
+        data={column}
+        location={location}
+        classNames='grid grid-rows-[var(--dx-rail-action)_1fr_var(--dx-rail-action)]'
+        debug={debug}
+        draggable={draggable}
+        dragHandle={dragHandle}
+        ref={forwardedRef}
+      >
+        {uncategorized ? (
+          <div className='border-b border-separator p-2' data-testid='board-column-header'>
+            <span className='font-medium'>{title}</span>
+          </div>
+        ) : (
+          <Board.Column.Header label={title} dragHandleRef={setDragHandle} />
+        )}
+        <Board.Column.Body
+          data={column}
+          eventHandler={eventHandler}
+          Tile={itemTile as FC<MosaicTileProps<Obj.Unknown>>}
+        />
+        <Board.Column.Footer
+          onAdd={
+            onCardAdd
+              ? () => onCardAdd(column.columnValue === UNCATEGORIZED_VALUE ? undefined : column.columnValue)
+              : undefined
+          }
+        />
+      </Board.Column.Root>
+    );
+  },
+);
+
+KanbanColumn.displayName = KANBAN_COLUMN_NAME;

package/src/components/KanbanBoard/context.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import { type ComponentType } from 'react';
+
+import { type Obj } from '@dxos/echo';
+import { type MosaicTileProps } from '@dxos/react-ui-mosaic';
+import { type ProjectionModel } from '@dxos/schema';
+
+import { type ColumnStructure, type KanbanChangeCallback, UNCATEGORIZED_ATTRIBUTES, UNCATEGORIZED_VALUE } from '#types';
+
+const KANBAN_BOARD_NAME = 'KanbanBoard.Context';
+
+/**
+ * Card tile props. Defined here (rather than in `KanbanCard.tsx`) so the
+ * context type can reference it without forming a cycle through that
+ * module's runtime exports — webkit treats the resulting TDZ as a hard
+ * error while other engines are lenient.
+ */
+export type KanbanCardProps = Pick<MosaicTileProps<Obj.Unknown>, 'location' | 'data' | 'debug' | 'draggable'>;
+
+/**
+ * Column tile props. See note on {@link KanbanCardProps}.
+ */
+export type KanbanColumnProps = Pick<MosaicTileProps<ColumnStructure>, 'location' | 'data' | 'debug' | 'draggable'>;
+
+/**
+ * Context value for the Kanban board.
+ * Items are Echo objects (Obj.Unknown).
+ */
+export 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;
+};
+
+export 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>,
+});

package/src/components/KanbanBoard/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './KanbanBoard';

package/src/components/index.ts

@@ -2,5 +2,4 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './KanbanContainer';
-export * from './KanbanViewEditor';
+export * from './KanbanBoard';

package/src/containers/KanbanContainer/KanbanContainer.stories.tsx

@@ -0,0 +1,277 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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, 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 { AppSurface } from '@dxos/app-toolkit/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';
+// `/plugin` entrypoints used here for the same reason as `corePlugins()` —
+// see `@dxos/plugin-testing/src/core.ts` for the rationale.
+import { ClientPlugin } from '@dxos/plugin-client/testing';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { PreviewPlugin } from '@dxos/plugin-preview/testing';
+import { SpacePlugin } from '@dxos/plugin-space/testing';
+import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { Filter, type Space, useQuery, useSchema, useSpaces } from '@dxos/react-client/echo';
+import { ViewEditor } from '@dxos/react-ui-form';
+import { Syntax } 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 { useProjectionModel } from '#hooks';
+import { translations } from '#translations';
+import { Kanban } from '#types';
+
+import { KanbanPlugin } from '../../KanbanPlugin';
+
+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'],
+});
+
+//
+// Story setup helpers.
+//
+
+type ClientSetupOptions = {
+  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({
+    plugins: [
+      ...corePlugins(),
+      ClientPlugin({
+        types: [...types, View.View, Kanban.Kanban],
+        onClientInitialized: ({ client }) =>
+          Effect.gen(function* () {
+            yield* initializeIdentity(client);
+            const space = yield* Effect.promise(() => client.spaces.create());
+            yield* Effect.promise(() => space.waitUntilReady());
+            yield* Effect.promise(() => onSpaceCreated?.(space) ?? Promise.resolve());
+          }),
+      }),
+      PreviewPlugin(),
+      SpacePlugin({}),
+      StorybookPlugin({}),
+      KanbanPlugin(),
+    ],
+  });
+
+/**
+ * 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 [kanban] = useQuery(space?.db, Filter.type(Kanban.Kanban));
+  const viewRef = kanban && kanban.spec.kind === 'view' ? kanban.spec.view : undefined;
+  const view = viewRef?.target;
+  const typename = view?.query ? getTypenameFromQuery(view.query.ast) : undefined;
+  const schema = useSchema(space?.db, typename);
+  const projection = useProjectionModel(schema, kanban, registry);
+
+  const data = useMemo(() => (kanban ? { subject: kanban, attendableId: 'story' } : undefined), [kanban]);
+
+  const handleUpdateQuery = useCallback(
+    (newQuery: QueryAST.Query) => {
+      invariant(schema);
+      invariant(view);
+      if (Type.isMutable(schema)) {
+        schema.updateTypename(getTypenameFromQuery(newQuery));
+      }
+      Obj.update(view, (view) => {
+        view.query.ast = newQuery as Mutable<QueryAST.Query>;
+      });
+    },
+    [view, schema],
+  );
+
+  const handleDeleteField = useCallback(
+    (fieldId: string) => {
+      if (schema && Type.isMutable(schema) && projection) {
+        projection.deleteFieldProjection(fieldId);
+      }
+    },
+    [schema, projection],
+  );
+
+  if (!schema || !view) {
+    return null;
+  }
+
+  return (
+    <div className='grow grid grid-cols-[1fr_350px] overflow-hidden h-full w-full'>
+      <Surface.Surface type={AppSurface.Article} data={data} limit={1} />
+      <div className='flex flex-col h-full overflow-hidden border-l border-separator'>
+        <ViewEditor
+          registry={space?.db.schemaRegistry}
+          schema={schema}
+          view={view}
+          onQueryChanged={handleUpdateQuery}
+          onDelete={schema && Type.isMutable(schema) ? handleDeleteField : undefined}
+        />
+        <Syntax.Root data={{ view, schema }}>
+          <Syntax.Content>
+            <Syntax.Filter />
+            <Syntax.Viewport>
+              <Syntax.Code classNames='text-xs' />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
+      </div>
+    </div>
+  );
+};
+
+//
+// Story definitions.
+//
+
+const meta = {
+  title: 'plugins/plugin-kanban/containers/Kanban',
+  component: DefaultComponent,
+  render: () => <DefaultComponent />,
+  decorators: [withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultComponent>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default story using static runtime schema (immutable).
+ * Schema mutations are not allowed.
+ */
+export const Default: Story = {
+  decorators: [
+    withKanbanPlugins({
+      types: [Organization.Organization, Person.Person],
+      onSpaceCreated: async (space) => {
+        const { view } = await ViewModel.makeFromDatabase({
+          db: space.db,
+          typename: Organization.Organization.typename,
+          pivotFieldName: 'status',
+        });
+        const kanban = Kanban.make({ view });
+        space.db.add(kanban);
+
+        Array.from({ length: 10 }).map(() => {
+          return space.db.add(Obj.make(Organization.Organization, createOrg()));
+        });
+      },
+    }),
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // 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: 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 (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 (Board items use data-testid="board-item").
+    const getColumnCards = (column: HTMLElement) =>
+      Array.from(column.querySelectorAll('[data-testid="board-item"]')) as HTMLElement[];
+
+    await waitFor(() => expect(getColumnCards(activeColumn).length).toBeGreaterThan(0));
+
+    // Verify cards are distributed across columns.
+    const activeCards = getColumnCards(activeColumn);
+    const prospectCards = getColumnCards(prospectColumn);
+    await expect(activeCards.length).toBeGreaterThan(0);
+    await expect(prospectCards.length).toBeGreaterThan(0);
+
+    // 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 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.
+  },
+};
+
+/**
+ * Story variant that uses a mutable database schema (EchoSchema).
+ * This allows testing schema mutations like adding/removing fields.
+ */
+// TODO(wittjosiah): Card previews (e.g., OrganizationCard) are type-specific and hard-coded.
+//   They don't use the projection to determine which fields to display, so deleting a field
+//   from the schema won't remove it from the card preview. To fix this, the type-specific
+//   cards in PreviewPlugin would need to accept and respect the projection prop.
+export const MutableSchema: Story = {
+  decorators: [
+    withKanbanPlugins({
+      onSpaceCreated: async (space) => {
+        // Register schema in the database to make it mutable (EchoSchema).
+        const [schema] = await space.db.schemaRegistry.register([Organization.Organization]);
+
+        const { view } = await ViewModel.makeFromDatabase({
+          db: space.db,
+          typename: schema.typename,
+          pivotFieldName: 'status',
+        });
+        const kanban = Kanban.make({ view });
+        space.db.add(kanban);
+
+        // Create test data using the registered schema.
+        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)));
+      },
+    }),
+  ],
+};