@dxos/plugin-kanban 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/containers/KanbanContainer/KanbanContainer.tsx

@@ -2,31 +2,42 @@
 // Copyright 2024 DXOS.org
 //
 
-import { RegistryContext } from '@effect-atom/atom-react';
+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 { type AppSurface } from '@dxos/app-toolkit/ui';
-import { Filter, Obj, Query, Type } from '@dxos/echo';
-import { AtomQuery } from '@dxos/echo-atom';
+import { Filter, Obj, Query, type Ref, Type } from '@dxos/echo';
+import { AtomObj, AtomQuery } from '@dxos/echo-atom';
 import { useObject, useSchema } from '@dxos/react-client/echo';
 import { Panel, Toolbar } from '@dxos/react-ui';
 import { getTagFromQuery, getTypenameFromQuery } from '@dxos/schema';
 
 import { KanbanBoard } from '#components';
-import { useEchoChangeCallback, useProjectionModel } from '#hooks';
+import { useEchoChangeCallback, useItemsProjection, useProjectionModel } from '#hooks';
 import { KanbanOperation } from '#operations';
-import { type Kanban } from '#types';
+import { Kanban } from '#types';
 
 export type KanbanContainerProps = AppSurface.ObjectArticleProps<Kanban.Kanban>;
 
-export const KanbanContainer = ({ role, subject: object }: KanbanContainerProps) => {
+export const KanbanContainer = (props: KanbanContainerProps) => {
+  // 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) ? (
+    <ItemsKanbanContainer {...props} subject={props.subject} />
+  ) : (
+    <ViewKanbanContainer {...props} />
+  );
+};
+
+const ViewKanbanContainer = ({ role, subject: object }: KanbanContainerProps) => {
   const registry = useContext(RegistryContext);
   const schemas = useCapabilities(AppCapabilities.Schema);
   const db = Obj.getDatabase(object);
   const { invokePromise } = useOperationInvoker();
-  const [view] = useObject(object.view);
+  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;
 
@@ -94,3 +105,74 @@ export const KanbanContainer = ({ role, subject: object }: KanbanContainerProps)
     </Panel.Root>
   );
 };
+
+type ItemsKanbanContainerProps = Omit<KanbanContainerProps, 'subject'> & { subject: Kanban.KanbanItems };
+
+const ItemsKanbanContainer = ({ role, subject: object }: ItemsKanbanContainerProps) => {
+  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()?.echoId`) 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/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, useSchema } 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 = useSchema(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

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

@@ -13,9 +13,9 @@ import { type Kanban, type KanbanChangeCallback } from '#types';
  * 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]);
+};

package/src/hooks/{useKanbanBoardModel.test.ts → useKanbanBoardModel.browser.test.ts}

@@ -146,7 +146,7 @@ describe('useKanbanBoardModel', () => {
     expect(orderBefore).toEqual(['__uncategorized__', 'a', 'b']);
 
     act(() => {
-      Obj.change(kanban, (kanban) => {
+      Obj.update(kanban, (kanban) => {
         kanban.arrangement.order = ['b', 'a'];
       });
     });
@@ -187,7 +187,7 @@ describe('useKanbanBoardModel', () => {
     });
 
     act(() => {
-      Obj.change(kanban, (kanban) => {
+      Obj.update(kanban, (kanban) => {
         kanban.arrangement.columns['a'] = {
           ids: [item3.id, item1.id, item2.id],
         };
@@ -225,7 +225,7 @@ describe('useKanbanBoardModel', () => {
     });
 
     act(() => {
-      Obj.change(kanban, (kanban) => {
+      Obj.update(kanban, (kanban) => {
         kanban.arrangement.columns['b'] = { ids: [itemB.id] };
       });
     });

package/src/hooks/useKanbanBoardModel.ts

@@ -38,14 +38,27 @@ export function useKanbanBoardModel<T extends BaseKanbanItem = BaseKanbanItem>(
   // Source atoms: reactive reads from the kanban object; items come from the passed-in atom (e.g. AtomQuery or in-memory).
   const arrangementAtom = useMemo(() => AtomObj.makeProperty(kanban, 'arrangement'), [kanban]);
   const viewSnapshotAtom = useMemo(
-    () => (kanban?.view ? AtomObj.make(kanban.view) : Atom.make<undefined>(() => undefined)),
-    [kanban?.view],
+    () =>
+      kanban?.spec?.kind === 'view' && kanban.spec.view
+        ? AtomObj.make(kanban.spec.view)
+        : Atom.make<undefined>(() => undefined),
+    [kanban?.spec],
   );
 
-  /** Only changes when view.projection.pivotFieldId changes; keeps columns from firing on other view updates. */
+  /**
+   * Only changes when the discriminator-relevant pivot input changes.
+   * View-variant: derived from `view.projection.pivotFieldId`.
+   * Items-variant: the kanban's `spec.pivotField` (the property name itself acts as the field id).
+   */
   const pivotFieldIdAtom = useMemo(
-    () => Atom.make((get) => get(viewSnapshotAtom)?.projection?.pivotFieldId as string | undefined),
-    [viewSnapshotAtom],
+    () =>
+      Atom.make((get) => {
+        if (kanban?.spec.kind === 'items') {
+          return kanban.spec.pivotField;
+        }
+        return get(viewSnapshotAtom)?.projection?.pivotFieldId as string | undefined;
+      }),
+    [kanban?.spec, viewSnapshotAtom],
   );
 
   // Effective per-column ids: from kanban.arrangement.columns; empty when arrangement has no columns.

package/src/hooks/useProjectionModel.ts

@@ -30,11 +30,11 @@ export const useProjectionModel = <S extends Type.AnyEntity>(
 
   useAsyncEffect(
     async (controller) => {
-      if (!schema || !kanban) {
+      if (!schema || !kanban || kanban.spec.kind !== 'view') {
         return;
       }
       try {
-        const view = await kanban.view.load();
+        const view = await kanban.spec.view.load();
         if (controller.signal.aborted) {
           return;
         }

package/src/index.ts

@@ -2,6 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './meta';
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
 
-export * from './KanbanPlugin';
+export const KanbanPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export * from './meta';

package/src/operations/definitions.ts

@@ -3,8 +3,8 @@
 import * as Schema from 'effect/Schema';
 
 import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
 import { View } from '@dxos/echo';
-import { Operation } from '@dxos/operation';
 
 import { meta } from '#meta';
 

package/src/operations/delete-card-field.ts

@@ -3,10 +3,10 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
 import { JsonSchema, Obj } from '@dxos/echo';
 import { type EchoSchema } from '@dxos/echo/internal';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
 import { ProjectionModel, createEchoChangeCallback, getTypenameFromQuery } from '@dxos/schema';
 
 import { DeleteCardField } from './definitions';

package/src/operations/delete-card.ts

@@ -2,9 +2,9 @@
 
 import * as Effect from 'effect/Effect';
 
+import { Operation } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
 
 import { DeleteCard } from './definitions';
 

package/src/operations/index.ts

@@ -1,6 +1,6 @@
 // Copyright 2025 DXOS.org
 
-import { OperationHandlerSet } from '@dxos/operation';
+import { OperationHandlerSet } from '@dxos/compute';
 
 export * as KanbanOperation from './definitions';
 

package/src/operations/restore-card-field.ts

@@ -3,10 +3,10 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
 import { JsonSchema, Obj } from '@dxos/echo';
 import { type EchoSchema } from '@dxos/echo/internal';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
 import { ProjectionModel, createEchoChangeCallback, getTypenameFromQuery } from '@dxos/schema';
 
 import { RestoreCardField } from './definitions';

package/src/operations/restore-card.ts

@@ -2,9 +2,9 @@
 
 import * as Effect from 'effect/Effect';
 
+import { Operation } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
 
 import { RestoreCard } from './definitions';
 

package/src/types/Kanban.ts

@@ -9,10 +9,15 @@ import { View } from '@dxos/echo';
 import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
 import { ViewAnnotation } from '@dxos/schema';
 
-/** Per-column entry (ids order, optional hidden). */
+/**
+ * Per-column entry: ordered card ids plus an optional `hidden` flag that
+ * removes the column from the rendered board (and from the model's column
+ * list). Today only the uncategorized column is exposed in settings, but
+ * the data structure supports per-column hiding generally.
+ */
 const ArrangementColumnEntry = Schema.Struct({
   ids: Schema.Array(Obj.ID),
-  hidden: Schema.optional(Schema.Boolean),
+  hidden: Schema.Boolean.pipe(Schema.optional),
 });
 
 /** Keyed by columnValue. */
@@ -29,43 +34,118 @@ export const Arrangement = Schema.Struct({
 
 export type Arrangement = Schema.Schema.Type<typeof Arrangement>;
 
-export const Kanban = Schema.Struct({
-  name: Schema.optional(Schema.String),
+/**
+ * v1: pre-existing Kanban shape. Retained as the source for the v1→v2 migration.
+ */
+export const KanbanV1 = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
+  arrangement: Arrangement,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.kanban',
+    version: '0.1.0',
+  }),
+);
 
+//
+// v2 — `spec` is a discriminated union of how items are sourced.
+//
+// Mirrors the canonical DXOS pattern (see `Trigger.Spec` in
+// `@dxos/functions/src/types/Trigger.ts` and `Sequence.Source` in
+// `@dxos/plugin-zen`): the `Type.object` schema is a flat `Schema.Struct`,
+// and the discriminated union lives one level down as a single field whose
+// variants are tagged with a `kind` literal.
+//
+
+/** View-variant: items come from running the View's query (the original behaviour). */
+export const KanbanViewSpec = Schema.Struct({
+  kind: Schema.Literal('view').pipe(FormInputAnnotation.set(false)),
   view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
+});
+export type KanbanViewSpec = Schema.Schema.Type<typeof KanbanViewSpec>;
+
+/** Items-variant: kanban owns its items as an explicit ref array (used by externally-synced kanbans). */
+export const KanbanItemsSpec = Schema.Struct({
+  kind: Schema.Literal('items').pipe(FormInputAnnotation.set(false)),
+  /** Property path on each item that drives column membership (e.g. `'listName'`). */
+  pivotField: Schema.String,
+  /** Items owned directly by the kanban. */
+  items: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(FormInputAnnotation.set(false)),
+});
+export type KanbanItemsSpec = Schema.Schema.Type<typeof KanbanItemsSpec>;
+
+/** Discriminated union of source specs. Distinguished by `kind`. */
+export const KanbanSpec = Schema.Union(KanbanViewSpec, KanbanItemsSpec);
+export type KanbanSpec = Schema.Schema.Type<typeof KanbanSpec>;
 
-  /** Column display order and per-column card ids. */
+export const Kanban = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
   arrangement: Arrangement,
+  /** How this kanban sources its items. Discriminated by `spec.kind`. */
+  spec: KanbanSpec,
 }).pipe(
   Type.object({
     typename: 'org.dxos.type.kanban',
-    version: '0.1.0',
+    version: '0.2.0',
   }),
   LabelAnnotation.set(['name']),
-  ViewAnnotation.set(true),
+  ViewAnnotation.set(['spec', 'view']),
   Annotation.IconAnnotation.set({
     icon: 'ph--kanban--regular',
     hue: 'green',
   }),
 );
 
-/** Instance type; use Kanban.Kanban in type position so namespace has .Kanban as type and .KanbanSchema as schema. */
+/** Instance type; narrow on `kanban.spec.kind` (or use the guards below). */
 export interface Kanban extends Schema.Schema.Type<typeof Kanban> {}
 
-type MakeProps = Omit<Partial<Obj.MakeProps<typeof Kanban>>, 'view'> & {
+/** Narrowed view-variant kanban. */
+export type KanbanView = Kanban & { spec: KanbanViewSpec };
+
+/** Narrowed items-variant kanban. */
+export type KanbanItems = Kanban & { spec: KanbanItemsSpec };
+
+export const isKanbanView = (kanban: Kanban): kanban is KanbanView => kanban.spec.kind === 'view';
+export const isKanbanItems = (kanban: Kanban): kanban is KanbanItems => kanban.spec.kind === 'items';
+
+type MakeViewProps = {
+  name?: string;
   view: View.View;
+  arrangement?: Arrangement;
 };
 
 /**
- * Make a kanban as a view of a data set.
+ * Make a view-variant kanban (items sourced via the View's query).
  */
-export const make = (props: MakeProps): Kanban => {
+export const make = (props: MakeViewProps): Kanban => {
   const { name, view, arrangement } = props;
   const order = arrangement?.order ?? [];
   const columns = arrangement?.columns ?? {};
   return Obj.make(Kanban, {
     name,
-    view: Ref.make(view),
     arrangement: { order, columns },
+    spec: { kind: 'view' as const, view: Ref.make(view) },
+  });
+};
+
+type MakeItemsProps = {
+  name?: string;
+  arrangement?: Arrangement;
+  pivotField: string;
+  items?: ReadonlyArray<Ref.Ref<Obj.Unknown>>;
+};
+
+/**
+ * Make an items-variant kanban (items list owned by the kanban itself, e.g. populated by a sync integration).
+ */
+export const makeItems = (props: MakeItemsProps): Kanban => {
+  const { name, arrangement, pivotField, items = [] } = props;
+  const order = arrangement?.order ?? [];
+  const columns = arrangement?.columns ?? {};
+  return Obj.make(Kanban, {
+    name,
+    arrangement: { order, columns },
+    spec: { kind: 'items' as const, pivotField, items },
   });
 };