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

package/src/containers/{KanbanContainer/KanbanContainer.stories.tsx → KanbanArticle/KanbanArticle.stories.tsx}

@@ -10,36 +10,40 @@ import { expect, waitFor, within } from 'storybook/test';
 
 import { withPluginManager } from '@dxos/app-framework/testing';
 import { Surface } from '@dxos/app-framework/ui';
-import { Obj, type QueryAST, Type } from '@dxos/echo';
-import { View } from '@dxos/echo';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Filter, Obj, type QueryAST, Type, View } from '@dxos/echo';
 import { type Mutable } from '@dxos/echo/internal';
 import { invariant } from '@dxos/invariant';
-import { ClientPlugin } from '@dxos/plugin-client';
-import { PreviewPlugin } from '@dxos/plugin-preview';
-import { SpacePlugin } from '@dxos/plugin-space';
+// `/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 { faker } from '@dxos/random';
-import { Filter, type Space, useQuery, useSchema, useSpaces } from '@dxos/react-client/echo';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { random } from '@dxos/random';
+import { type Space, useQuery, useType, useSpaces } from '@dxos/react-client/echo';
 import { ViewEditor } from '@dxos/react-ui-form';
-import { JsonFilter } from '@dxos/react-ui-syntax-highlighter';
+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 { useProjectionModel } from '#hooks';
+import { translations } from '#translations';
+import { Kanban } from '#types';
+
 import { KanbanPlugin } from '../../KanbanPlugin';
-import { translations } from '../../translations';
-import { Kanban } from '../../types';
 
-faker.seed(0);
+random.seed(0);
 
 const createOrg = (status?: Organization.Organization['status']) => ({
-  name: faker.commerce.productName(),
-  description: faker.lorem.paragraph(),
-  image: faker.image.url(),
-  website: faker.internet.url(),
-  status: (status ?? faker.helpers.arrayElement(Organization.StatusOptions).id) as 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'],
 });
 
 //
@@ -53,7 +57,7 @@ type ClientSetupOptions = {
 
 /**
  * Creates the standard plugin manager decorator with client configuration.
- * Includes KanbanPlugin so the Surface resolves to KanbanContainer.
+ * Includes KanbanPlugin so the Surface resolves to KanbanArticle.
  */
 const withKanbanPlugins = ({ types = [], onSpaceCreated }: ClientSetupOptions): Decorator =>
   withPluginManager({
@@ -63,7 +67,7 @@ const withKanbanPlugins = ({ types = [], onSpaceCreated }: ClientSetupOptions):
         types: [...types, View.View, Kanban.Kanban],
         onClientInitialized: ({ client }) =>
           Effect.gen(function* () {
-            yield* Effect.promise(() => client.halo.createIdentity());
+            yield* initializeIdentity(client);
             const space = yield* Effect.promise(() => client.spaces.create());
             yield* Effect.promise(() => space.waitUntilReady());
             yield* Effect.promise(() => onSpaceCreated?.(space) ?? Promise.resolve());
@@ -77,59 +81,67 @@ const withKanbanPlugins = ({ types = [], onSpaceCreated }: ClientSetupOptions):
   });
 
 /**
- * Renders the first Kanban in the space via Surface (resolves to KanbanContainer),
- * with a sidebar containing ViewEditor and JsonFilter.
+ * Renders the first Kanban in the space via Surface (resolves to KanbanArticle),
+ * 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 typename = kanban?.view.target?.query ? getTypenameFromQuery(kanban.view.target.query.ast) : undefined;
-  const schema = useSchema(space?.db, typename);
-  const projection = useProjectionModel(schema, kanban, registry);
+  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 type = useType(space?.db, typename);
+  const projection = useProjectionModel(type, kanban, registry);
 
-  const data = useMemo(() => (kanban ? { subject: kanban } : {}), [kanban]);
+  const data = useMemo(() => (kanban ? { subject: kanban, attendableId: 'story' } : undefined), [kanban]);
 
   const handleUpdateQuery = useCallback(
     (newQuery: QueryAST.Query) => {
-      invariant(schema);
-      invariant(kanban?.view.target);
-      if (Type.isMutable(schema)) {
-        schema.updateTypename(getTypenameFromQuery(newQuery));
-      }
-      Obj.change(kanban.view.target, (view) => {
+      invariant(type);
+      invariant(view);
+      // NOTE: persisted Type.Type typename is immutable; only the view's
+      // query is updated here.
+      Obj.update(view, (view) => {
         view.query.ast = newQuery as Mutable<QueryAST.Query>;
       });
     },
-    [kanban, schema],
+    [view, type],
   );
 
   const handleDeleteField = useCallback(
     (fieldId: string) => {
-      if (schema && Type.isMutable(schema) && projection) {
+      if (type && Type.getDatabase(type) != null && projection) {
         projection.deleteFieldProjection(fieldId);
       }
     },
-    [schema, projection],
+    [type, projection],
   );
 
-  if (!schema || !kanban?.view.target) {
+  if (!type || !view) {
     return null;
   }
 
   return (
     <div className='grow grid grid-cols-[1fr_350px] overflow-hidden h-full w-full'>
-      <Surface.Surface role='article' data={data} limit={1} />
+      <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={kanban.view.target}
+          registry={space?.db.graph.registry}
+          type={type}
+          view={view}
           onQueryChanged={handleUpdateQuery}
-          onDelete={schema && Type.isMutable(schema) ? handleDeleteField : undefined}
+          onDelete={type && Type.getDatabase(type) != null ? handleDeleteField : undefined}
         />
-        <JsonFilter data={{ view: kanban.view.target, schema }} classNames='text-xs' />
+        <Syntax.Root data={{ view, schema: Type.getSchema(type) }}>
+          <Syntax.Content>
+            <Syntax.Filter />
+            <Syntax.Viewport>
+              <Syntax.Code classNames='text-xs' />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
       </div>
     </div>
   );
@@ -143,7 +155,7 @@ const meta = {
   title: 'plugins/plugin-kanban/containers/Kanban',
   component: DefaultComponent,
   render: () => <DefaultComponent />,
-  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  decorators: [withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
     translations,
@@ -165,7 +177,7 @@ export const Default: Story = {
       onSpaceCreated: async (space) => {
         const { view } = await ViewModel.makeFromDatabase({
           db: space.db,
-          typename: Organization.Organization.typename,
+          typename: Type.getTypename(Organization.Organization),
           pivotFieldName: 'status',
         });
         const kanban = Kanban.make({ view });
@@ -182,9 +194,9 @@ export const Default: Story = {
 
     // 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: 30_000 });
-    const prospectTag = await canvas.findByText('Prospect', undefined, { timeout: 10_000 });
-    const commitTag = await canvas.findByText('Commit', undefined, { timeout: 10_000 });
+    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();
@@ -209,7 +221,7 @@ export const Default: Story = {
     await expect(activeCards.length).toBeGreaterThan(0);
     await expect(prospectCards.length).toBeGreaterThan(0);
 
-    // Verify cards have drag handles (Card.Toolbar includes drag handle).
+    // Verify cards have drag handles (Card.Header includes drag handle).
     const firstActiveCard = activeCards[0];
     const buttons = firstActiveCard.querySelectorAll('button');
     await expect(buttons.length).toBeGreaterThan(0);
@@ -226,7 +238,7 @@ export const Default: Story = {
 };
 
 /**
- * Story variant that uses a mutable database schema (EchoSchema).
+ * Story variant that uses a database-stored Type.Type entity (mutable schema).
  * This allows testing schema mutations like adding/removing fields.
  */
 // TODO(wittjosiah): Card previews (e.g., OrganizationCard) are type-specific and hard-coded.
@@ -237,12 +249,14 @@ 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]);
+        // Persist the schema in the database to make it mutable (stored Type.Type).
+        const type = await space.db.addType(Organization.Organization);
 
         const { view } = await ViewModel.makeFromDatabase({
           db: space.db,
-          typename: schema.typename,
+          // `db.addType` returns a persisted `Type.Type` entity; its typename lives in the
+          // type metadata, so read it via `Type.getTypename` rather than a `.typename` prop.
+          typename: Type.getTypename(type),
           pivotFieldName: 'status',
         });
         const kanban = Kanban.make({ view });
@@ -256,7 +270,7 @@ export const MutableSchema: Story = {
           ...Array.from({ length: 1 }, () => createOrg('commit')),
           ...Array.from({ length: 1 }, () => createOrg('reject')),
         ];
-        requiredOrgs.forEach((org) => space.db.add(Obj.make(schema, org)));
+        requiredOrgs.forEach((org) => space.db.add(Obj.make(type, org)));
       },
     }),
   ],

package/src/containers/KanbanArticle/KanbanArticle.tsx

@@ -0,0 +1,180 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Atom, RegistryContext } from '@effect-atom/atom-react';
+import React, { useCallback, useContext, useMemo } from 'react';
+
+import { useCapabilities, useOperationInvoker } from '@dxos/app-framework/ui';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { useSchemaFilter, type AppSurface } from '@dxos/app-toolkit/ui';
+import { Filter, Obj, Query, type Ref, Type } from '@dxos/echo';
+import { AtomObj, AtomQuery } from '@dxos/echo-atom';
+import { useObject, useType } from '@dxos/react-client/echo';
+import { Panel, Toolbar } from '@dxos/react-ui';
+import { getTagFromQuery, getTypenameFromQuery } from '@dxos/schema';
+
+import { KanbanBoard } from '#components';
+import { useEchoChangeCallback, useItemsProjection, useProjectionModel } from '#hooks';
+import { KanbanOperation } from '#types';
+import { Kanban } from '#types';
+
+export type KanbanArticleProps = AppSurface.ObjectArticleProps<Kanban.Kanban>;
+
+export const KanbanArticle = (props: KanbanArticleProps) => {
+  // Branch on `kanban.spec.kind`: view-variant runs a typename query through
+  // `useProjectionModel`; items-variant dereferences `kanban.spec.items` and
+  // uses a stub projection from `useItemsProjection`.
+  return Kanban.isKanbanItems(props.subject) ? (
+    <ItemsKanbanArticle {...props} subject={props.subject} />
+  ) : (
+    <ViewKanbanArticle {...props} />
+  );
+};
+
+const ViewKanbanArticle = ({ role, subject: object }: KanbanArticleProps) => {
+  const registry = useContext(RegistryContext);
+  const schemas = useCapabilities(AppCapabilities.Schema);
+  const db = Obj.getDatabase(object);
+  const { invokePromise } = useOperationInvoker();
+  const [view] = useObject(object.spec.kind === 'view' ? object.spec.view : undefined);
+  const typename = view?.query ? getTypenameFromQuery(view.query.ast) : undefined;
+  const tag = view?.query ? getTagFromQuery(view.query.ast) : undefined;
+
+  const schemaFromDb = useType(db, typename);
+  const cardSchema = useMemo(
+    () => schemaFromDb ?? schemas.flat().find((schema) => Type.getTypename(schema) === typename),
+    [schemaFromDb, schemas, typename],
+  );
+
+  const baseFilter = useSchemaFilter(cardSchema);
+  const items = useMemo(() => {
+    if (!db) {
+      return null;
+    }
+    const query = tag ? Query.select(baseFilter).select(Filter.tag(tag)) : Query.select(baseFilter);
+    return AtomQuery.make(db, query);
+  }, [db, baseFilter, tag]);
+
+  const projection = useProjectionModel(cardSchema, object, registry);
+  const change = useEchoChangeCallback(object);
+
+  const pivotFieldId = view?.projection?.pivotFieldId;
+  const columnFieldPath =
+    projection && pivotFieldId ? projection.tryGetFieldProjection(pivotFieldId)?.props.property : undefined;
+
+  const handleCardAdd = useCallback(
+    (columnValue: string | undefined) => {
+      if (db && cardSchema && columnFieldPath) {
+        const card = Obj.make(Type.assertObject(cardSchema), {
+          [columnFieldPath]: columnValue,
+        });
+        db.add(card);
+        return card.id;
+      }
+    },
+    [db, cardSchema, columnFieldPath],
+  );
+
+  const handleCardRemove = useCallback(
+    (card: { id: string }) => {
+      void invokePromise(KanbanOperation.DeleteCard, { card });
+    },
+    [invokePromise],
+  );
+
+  if (!object || !db || !items || !projection || !change) {
+    return null;
+  }
+
+  return (
+    <Panel.Root role={role}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root />
+      </Panel.Toolbar>
+      <KanbanBoard.Root
+        kanban={object}
+        projection={projection}
+        items={items}
+        change={change}
+        onCardAdd={handleCardAdd}
+        onCardRemove={handleCardRemove}
+      >
+        <Panel.Content asChild>
+          <KanbanBoard.Content />
+        </Panel.Content>
+      </KanbanBoard.Root>
+    </Panel.Root>
+  );
+};
+
+type ItemsKanbanArticleProps = Omit<KanbanArticleProps, 'subject'> & { subject: Kanban.KanbanItems };
+
+const ItemsKanbanArticle = ({ role, subject: object }: ItemsKanbanArticleProps) => {
+  const db = Obj.getDatabase(object);
+  const projection = useItemsProjection(object);
+  const change = useEchoChangeCallback(object);
+
+  // TODO(wittjosiah): pass refs (not loaded objects) through to the kanban
+  //   board and let `KanbanCard` subscribe to its own ref via `useObject`.
+  //   Today this atom subscribes to *every* item — any one changing causes the
+  //   container (and the model's per-column atoms) to recompute. With cards
+  //   subscribing themselves, the container only needs the refs and the
+  //   per-card render is independent. Requires:
+  //     - `KanbanCard` to accept `Ref<Obj.Unknown>` as `data` and call
+  //       `useObject(ref)` internally.
+  //     - The model to handle a ref-bearing item shape (id from
+  //       `ref.dxn.asEchoDXN()?.echoUri`) and use arrangement-only ordering
+  //       for items-variant (no pivot-value fallback, since refs don't expose
+  //       the pivot field without loading).
+  //     - `Mosaic.isItem` to accept the ref wrapper alongside `Obj.isObject`.
+  const itemsAtom = useMemo(
+    () =>
+      Atom.make((get) => {
+        const out: Obj.Unknown[] = [];
+        for (const ref of object.spec.items as ReadonlyArray<Ref.Ref<Obj.Unknown>>) {
+          const target = get(AtomObj.make(ref));
+          if (target == null) {
+            continue;
+          }
+          // Drop soft-deleted cards (e.g. Trello-closed cards). The ref
+          // stays in `spec.items` so arrangement is preserved, but the card
+          // shouldn't render.
+          if (Obj.isDeleted(target)) {
+            continue;
+          }
+          out.push(target as unknown as Obj.Unknown);
+        }
+        return out;
+      }),
+    [object.spec.items],
+  );
+
+  const handleCardRemove = useCallback(() => undefined, []);
+
+  if (!object || !db || !change) {
+    return null;
+  }
+
+  // TODO(wittjosiah): wire `onCardAdd` to the create-object flow so
+  //   users can add items directly from the kanban (currently the column's
+  //   "+" button is hidden because `onCardAdd` is undefined).
+  return (
+    <Panel.Root role={role}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root />
+      </Panel.Toolbar>
+      <KanbanBoard.Root
+        kanban={object}
+        projection={projection}
+        items={itemsAtom}
+        change={change}
+        onCardRemove={handleCardRemove}
+      >
+        <Panel.Content asChild>
+          <KanbanBoard.Content />
+        </Panel.Content>
+      </KanbanBoard.Root>
+    </Panel.Root>
+  );
+};

package/src/containers/KanbanArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export { KanbanArticle as default } from './KanbanArticle';

package/src/containers/KanbanSettings/KanbanSettings.tsx

@@ -0,0 +1,94 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import React, { useCallback, useContext, useMemo } from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { Format } from '@dxos/echo/internal';
+import { useObject, useType } from '@dxos/react-client/echo';
+import { Form, type FormFieldMap, SelectField } from '@dxos/react-ui-form';
+import { getTypenameFromQuery } from '@dxos/schema';
+
+import { useProjectionModel } from '#hooks';
+import { type Kanban, KanbanSettingsSchema, KanbanViewSettingsSchema, UNCATEGORIZED_VALUE } from '#types';
+
+export type KanbanSettingsProps = AppSurface.ObjectPropertiesProps<Kanban.Kanban>;
+
+/**
+ * Settings panel for a Kanban. Renders fields common to every kanban
+ * (currently the "Hide uncategorized column" toggle); for view-variant
+ * kanbans an additional "Column field" picker drives the View's pivot
+ * field. Items-variant kanbans use a hardcoded `spec.pivotField`, so that
+ * field is omitted there.
+ */
+export const KanbanSettings = ({ subject: object }: KanbanSettingsProps) => {
+  const registry = useContext(RegistryContext);
+  const db = Obj.getDatabase(object);
+  const isView = object.spec.kind === 'view';
+  const [view, updateView] = useObject(object.spec.kind === 'view' ? object.spec.view : undefined);
+  const [, updateKanban] = useObject(object);
+  const currentTypename = view?.query ? getTypenameFromQuery(view.query.ast) : undefined;
+  const schema = useType(db, currentTypename);
+  const projection = useProjectionModel(schema, object, registry);
+
+  const fieldProjections = projection?.getFieldProjections() ?? [];
+  const selectFields = useMemo(
+    () =>
+      fieldProjections
+        .filter((field) => field.props.format === Format.TypeFormat.SingleSelect)
+        .map(({ field }) => ({ value: field.id, label: field.path })),
+    [fieldProjections],
+  );
+
+  const hideUncategorized = object.arrangement.columns[UNCATEGORIZED_VALUE]?.hidden ?? false;
+
+  const handleValuesChanged = useCallback(
+    (values: Partial<{ columnFieldId: string; hideUncategorized: boolean }>) => {
+      if (isView && values.columnFieldId != null) {
+        updateView((view) => {
+          view.projection.pivotFieldId = values.columnFieldId!;
+        });
+      }
+      if (values.hideUncategorized !== undefined) {
+        updateKanban((kanban) => {
+          const existing = kanban.arrangement.columns[UNCATEGORIZED_VALUE];
+          if (existing) {
+            existing.hidden = values.hideUncategorized;
+          } else {
+            kanban.arrangement.columns[UNCATEGORIZED_VALUE] = {
+              ids: [],
+              hidden: values.hideUncategorized,
+            };
+          }
+        });
+      }
+    },
+    [isView, updateView, updateKanban],
+  );
+
+  const initialValues = useMemo(
+    () => ({
+      ...(isView ? { columnFieldId: view?.projection.pivotFieldId } : {}),
+      hideUncategorized,
+    }),
+    [isView, view?.projection.pivotFieldId, hideUncategorized],
+  );
+
+  const fieldMap: FormFieldMap = useMemo(
+    () => ({ columnFieldId: (props) => <SelectField {...props} options={selectFields} /> }),
+    [selectFields],
+  );
+
+  // Schema is picked by `kanban.spec.kind` — they have different shapes,
+  // so cast for `Form.Root`'s single-schema prop.
+  const settingsSchema = (isView ? KanbanViewSettingsSchema : KanbanSettingsSchema) as any;
+
+  return (
+    <Form.Root schema={settingsSchema} values={initialValues} fieldMap={fieldMap} onValuesChanged={handleValuesChanged}>
+      <Form.FieldSet />
+    </Form.Root>
+  );
+};

package/src/containers/KanbanSettings/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { KanbanSettings as default } from './KanbanSettings';

package/src/containers/index.ts

@@ -4,5 +4,5 @@
 
 import { type ComponentType, lazy } from 'react';
 
-export const KanbanContainer: ComponentType<any> = lazy(() => import('./KanbanContainer'));
-export const KanbanViewEditor: ComponentType<any> = lazy(() => import('./KanbanViewEditor'));
+export const KanbanArticle: ComponentType<any> = lazy(() => import('./KanbanArticle'));
+export const KanbanSettings: ComponentType<any> = lazy(() => import('./KanbanSettings'));

package/src/hooks/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './useEchoChangeCallback';
+export * from './useItemsProjection';
 export * from './useKanbanBoardModel';
 export * from './useKanbanColumnEventHandler';
 export * from './useKanbanItemEventHandler';

package/src/hooks/useEchoChangeCallback.ts

@@ -6,16 +6,16 @@ import { useMemo } from 'react';
 
 import { Obj } from '@dxos/echo';
 
-import { type Kanban, type KanbanChangeCallback } from '../types';
+import { type Kanban, type KanbanChangeCallback } from '#types';
 
 /**
  * Creates a change callback for ECHO-backed kanban and items (plain function, no hooks).
  * Use this when the kanban and items are stored in the ECHO database.
  */
 export const createEchoChangeCallback = <T extends Obj.Unknown>(kanban: Kanban.Kanban): KanbanChangeCallback<T> => ({
-  kanban: (mutate) => Obj.change(kanban, (kanban) => mutate(kanban)),
+  kanban: (mutate) => Obj.update(kanban, (kanban) => mutate(kanban)),
   setItemField: (item, field, value) => {
-    Obj.change(item, (item: any) => {
+    Obj.update(item, (item: any) => {
       item[field] = value;
     });
   },

package/src/hooks/useItemsProjection.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { useMemo } from 'react';
+
+import type { ProjectionModel } from '@dxos/schema';
+
+import { type Kanban } from '#types';
+
+/**
+ * Minimal `ProjectionModel` for `spec.kind === 'items'` (no View). Supplies `pivotField`
+ * and column options from `arrangement.columns` keys—written by sync so columns exist
+ * before refs hydrate. Stubs `getFieldProjections` / `getHiddenProperties` for shared
+ * board/card UI; hides the pivot on the card body (column shows it); Expando cards render title only.
+ */
+export const useItemsProjection = (kanban: Kanban.KanbanItems): ProjectionModel => {
+  return useMemo(() => {
+    const pivotField = kanban.spec.pivotField;
+
+    const optionIds = Object.keys(kanban.arrangement?.columns ?? {});
+    const options = optionIds.map((id) => ({ id, title: id, color: 'neutral' as const }));
+
+    const fieldProjection: any = {
+      field: { id: pivotField, path: pivotField },
+      props: { property: pivotField, options },
+    };
+
+    const fields = Atom.make(() => [fieldProjection.field]);
+
+    const stub: Pick<ProjectionModel, 'tryGetFieldProjection' | 'getFieldProjections' | 'getHiddenProperties'> & {
+      fields: typeof fields;
+    } = {
+      fields,
+      tryGetFieldProjection: (id: string) => (id === pivotField ? fieldProjection : undefined),
+      getFieldProjections: () => [],
+      getHiddenProperties: () => [pivotField],
+    };
+
+    // TODO(wittjosiah): Refactor ProjectionModel to be an interface that we can fulfill.
+    return stub as unknown as ProjectionModel;
+  }, [kanban.arrangement?.columns, kanban.spec.pivotField]);
+};