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

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

@@ -8,28 +8,28 @@ import React, { useCallback, useContext, useEffect, useMemo, useState } from 're
 
 import { Filter, JsonSchema, Obj, Query } from '@dxos/echo';
 import { type View } from '@dxos/echo';
-import { faker } from '@dxos/random';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
+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 { createEchoChangeCallback as createKanbanChangeCallback } from '#hooks';
+import { KanbanCardTileSimple } from '#testing';
+import { translations } from '#translations';
+import { Kanban } from '#types';
 
 import { KanbanBoard } from './KanbanBoard';
 
-faker.seed(1);
+random.seed(1);
 
 const createOrg = () => ({
-  name: faker.commerce.productName(),
-  description: faker.lorem.sentence(),
-  image: faker.image.url(),
-  website: faker.internet.url(),
-  status: faker.helpers.arrayElement(Organization.StatusOptions).id as Organization.Organization['status'],
+  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'],
 });
 
 /**
@@ -66,7 +66,7 @@ const DefaultStory = () => {
     const initialItems = Array.from({ length: 12 }, () =>
       Obj.make(Organization.Organization, {
         ...createOrg(),
-        status: faker.helpers.arrayElement(statuses) as Organization.Organization['status'],
+        status: random.helpers.arrayElement(statuses) as Organization.Organization['status'],
       }),
     );
 
@@ -79,7 +79,9 @@ const DefaultStory = () => {
 
   const handleCardAdd = useCallback(
     (columnValue: string | undefined) => {
-      if (!state || !columnFieldPath || !registry) return undefined;
+      if (!state || !columnFieldPath || !registry) {
+        return undefined;
+      }
       const card = Obj.make(Organization.Organization, {
         ...createOrg(),
         ...(columnFieldPath ? { [columnFieldPath]: columnValue } : {}),
@@ -93,7 +95,9 @@ const DefaultStory = () => {
 
   const handleCardRemove = useCallback(
     (card: Obj.Unknown) => {
-      if (!registry) return;
+      if (!registry) {
+        return;
+      }
       const current = registry.get(items) ?? [];
       registry.set(
         items,
@@ -104,7 +108,7 @@ const DefaultStory = () => {
   );
 
   if (!state) {
-    return <></>;
+    return <Loading />;
   }
 
   return (

package/src/components/KanbanBoard/KanbanBoard.tsx

@@ -3,63 +3,30 @@
 //
 
 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 React, { type ComponentPropsWithoutRef, 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 { 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';
+import { composable, composableProps } from '@dxos/ui-theme';
+
+import { useKanbanBoardModel, useKanbanColumnEventHandler } from '#hooks';
+import { meta } from '#meta';
+import { type Kanban, UNCATEGORIZED_ATTRIBUTES, UNCATEGORIZED_VALUE } from '#types';
+
+import {
+  KanbanBoardContext,
+  type KanbanBoardContextValue,
+  type KanbanCardProps,
+  type KanbanColumnProps,
+  useKanbanBoard,
+} from './context';
+import { KanbanCard } from './KanbanCard';
+import { KanbanColumn } 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
 //
@@ -67,7 +34,7 @@ const [KanbanBoardContext, useKanbanBoard] = createContext<KanbanBoardContextVal
 const KANBAN_BOARD_ROOT = 'KanbanBoard.Root';
 
 type KanbanBoardRootProps = PropsWithChildren<
-  Pick<KanbanBoardContextValue, 'change' | 'itemTile'> & {
+  {
     kanban: Kanban.Kanban;
     /** Required when providing context; Root derives columnFieldPath, pivotFieldId, getPivotAttributes from kanban + projection. */
     projection: ProjectionModel;
@@ -75,33 +42,38 @@ type KanbanBoardRootProps = PropsWithChildren<
     items: Atom.Atom<Obj.Unknown[]>;
     onCardAdd?: (columnValue: string | undefined) => string | undefined;
     onCardRemove?: (card: Obj.Unknown) => void;
-  } & ComponentPropsWithoutRef<'div'>
+  } & Pick<KanbanBoardContextValue, 'change' | 'itemTile'> &
+    ComponentPropsWithoutRef<'div'>
 >;
 
 export const KanbanBoardRoot = ({
   children,
-  change,
-  itemTile = KanbanCard,
   kanban,
   projection,
   items,
+  change,
+  itemTile = KanbanCard,
   onCardAdd,
   onCardRemove,
-  ...props
 }: KanbanBoardRootProps) => {
   const registry = useContext(RegistryContext);
   const { t } = useTranslation(meta.id);
   const model = useKanbanBoardModel(kanban, projection, items, registry);
   const columns = model?.getColumns?.() ?? [];
-  const view = kanban?.view?.target;
+  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;
-  }, [projection, pivotFieldId]);
+  }, [kanban?.spec, projection, pivotFieldId]);
 
   const getPivotAttributes = useCallback<KanbanBoardContextValue['getPivotAttributes']>(
     (columnValue) => {
@@ -118,8 +90,8 @@ export const KanbanBoardRoot = ({
 
   if (columns.length === 0) {
     return (
-      <div {...props} className='flex flex-1 items-center justify-center p-8 text-center text-description'>
-        {t('select pivot placeholder')}
+      <div className='flex flex-1 items-center justify-center p-8 text-center text-description'>
+        {t('select-pivot.placeholder')}
       </div>
     );
   }
@@ -136,9 +108,7 @@ export const KanbanBoardRoot = ({
       onCardAdd={onCardAdd}
       onCardRemove={onCardRemove}
     >
-      <Board.Root model={model}>
-        <div {...props}>{children}</div>
-      </Board.Root>
+      <Board.Root model={model}>{children}</Board.Root>
     </KanbanBoardContext>
   );
 };
@@ -151,7 +121,9 @@ KanbanBoardRoot.displayName = KANBAN_BOARD_ROOT;
 
 const KANBAN_BOARD_CONTENT = 'KanbanBoard.Content';
 
-export const KanbanBoardContent = () => {
+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);
 
@@ -163,8 +135,16 @@ export const KanbanBoardContent = () => {
     change,
   });
 
-  return <Board.Content id={kanbanId} eventHandler={columnEventHandler} Tile={KanbanColumn} />;
-};
+  return (
+    <Board.Content
+      {...composableProps(props)}
+      ref={forwardedRef}
+      id={kanbanId}
+      eventHandler={columnEventHandler}
+      Tile={KanbanColumn}
+    />
+  );
+});
 
 KanbanBoardContent.displayName = KANBAN_BOARD_CONTENT;
 

package/src/components/KanbanBoard/KanbanCard.tsx

@@ -5,83 +5,97 @@
 import React, { forwardRef, useCallback, useMemo, useState } from 'react';
 
 import { Surface } from '@dxos/app-framework/ui';
-import { useObjectMenuItems, useObjectNavigate } from '@dxos/app-toolkit/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, type MosaicTileProps, useBoard } from '@dxos/react-ui-mosaic';
+import { Focus, Mosaic, useBoard } from '@dxos/react-ui-mosaic';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
 
-import { useKanbanBoard } from './KanbanBoard';
+import { type KanbanCardProps, useKanbanBoard } from './context';
 
-const KANBAN_CARD_TILE_NAME = 'KanbanBoard.Card';
+export { type KanbanCardProps };
 
-export type KanbanCardProps = Pick<MosaicTileProps<Obj.Unknown>, 'location' | 'data' | 'debug'>;
+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 }, forwardedRef) => {
-  const { t } = useTranslation(meta.id);
-  const { model } = useBoard(KANBAN_CARD_TILE_NAME);
-  const { projection, onCardRemove } = useKanbanBoard(KANBAN_CARD_TILE_NAME);
-  const [dragHandle, setDragHandle] = useState<HTMLButtonElement | null>(null);
-  const dragHandleRef = useCallback((el: HTMLButtonElement | null) => setDragHandle(el), []);
+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 handleNavigate = useObjectNavigate(data);
+    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],
-  );
+    const menuItems = useMemo(
+      () => [
+        ...objectMenuItems,
+        ...(onCardRemove
+          ? [
+              createMenuAction('remove', () => onCardRemove(data), {
+                label: t('remove-card.label'),
+                icon: 'ph--trash--regular',
+              }),
+            ]
+          : []),
+      ],
+      [objectMenuItems, onCardRemove, data, t],
+    );
 
-  return (
-    <Mosaic.Tile
-      asChild
-      id={model.getItemId(data)}
-      data={data}
-      location={location}
-      debug={debug}
-      dragHandle={dragHandle}
-    >
-      <Focus.Group asChild>
-        <Menu.Root>
-          <Card.Root ref={forwardedRef} data-testid='board-item'>
-            <Card.Toolbar>
-              <Card.DragHandle ref={dragHandleRef} />
-              <Card.Title onClick={handleNavigate}>{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 role='card--content' limit={1} data={{ subject: data, projection }} />}
-            </Card.Content>
-          </Card.Root>
-        </Menu.Root>
-      </Focus.Group>
-    </Mosaic.Tile>
-  );
-});
+    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

@@ -2,31 +2,31 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { forwardRef, useRef } from 'react';
+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 { useKanbanItemEventHandler } from '#hooks';
+import { type ColumnStructure, UNCATEGORIZED_VALUE } from '#types';
 
-import { useKanbanBoard } from './KanbanBoard';
+import { type KanbanColumnProps, useKanbanBoard } from './context';
 
-const KANBAN_COLUMN_NAME = 'KanbanBoard.Column';
+export { type KanbanColumnProps };
 
-export type KanbanColumnProps = Pick<MosaicTileProps<ColumnStructure>, 'location' | 'data' | 'debug'>;
+const KANBAN_COLUMN_NAME = 'KanbanBoard.Column';
 
 /**
  * Mosaic Tile for Kanban column.
  */
 export const KanbanColumn = forwardRef<HTMLDivElement, KanbanColumnProps>(
-  ({ data: column, location, debug }, forwardedRef) => {
+  ({ 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 dragHandleRef = useRef<HTMLButtonElement | null>(null);
+    const [dragHandle, setDragHandle] = useState<HTMLButtonElement | null>(null);
 
     const eventHandler = useKanbanItemEventHandler({
       column,
@@ -41,7 +41,8 @@ export const KanbanColumn = forwardRef<HTMLDivElement, KanbanColumnProps>(
         location={location}
         classNames='grid grid-rows-[var(--dx-rail-action)_1fr_var(--dx-rail-action)]'
         debug={debug}
-        dragHandleRef={dragHandleRef}
+        draggable={draggable}
+        dragHandle={dragHandle}
         ref={forwardedRef}
       >
         {uncategorized ? (
@@ -49,18 +50,20 @@ export const KanbanColumn = forwardRef<HTMLDivElement, KanbanColumnProps>(
             <span className='font-medium'>{title}</span>
           </div>
         ) : (
-          <Board.Column.Header label={title} dragHandleRef={dragHandleRef as React.RefObject<HTMLButtonElement>} />
+          <Board.Column.Header label={title} dragHandleRef={setDragHandle} />
         )}
         <Board.Column.Body
           data={column}
           eventHandler={eventHandler}
-          Tile={itemTile as React.FC<MosaicTileProps<Obj.Unknown>>}
+          Tile={itemTile as FC<MosaicTileProps<Obj.Unknown>>}
+        />
+        <Board.Column.Footer
+          onAdd={
+            onCardAdd
+              ? () => onCardAdd(column.columnValue === UNCATEGORIZED_VALUE ? undefined : column.columnValue)
+              : undefined
+          }
         />
-        {onCardAdd && (
-          <Board.Column.Footer
-            onAdd={() => onCardAdd(column.columnValue === UNCATEGORIZED_VALUE ? undefined : column.columnValue)}
-          />
-        )}
       </Board.Column.Root>
     );
   },

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>,
+});