@dxos/plugin-kanban 0.8.4-main.f9ba587 → 0.8.4-main.fcc0d83b33

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

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const KanbanContainer: ComponentType<any> = lazy(() => import('./KanbanContainer'));
+export const KanbanSettings: ComponentType<any> = lazy(() => import('./KanbanSettings'));

package/src/hooks/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useEchoChangeCallback';
+export * from './useItemsProjection';
+export * from './useKanbanBoardModel';
+export * from './useKanbanColumnEventHandler';
+export * from './useKanbanItemEventHandler';
+export * from './useProjectionModel';

package/src/hooks/useEchoChangeCallback.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { Obj } from '@dxos/echo';
+
+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.update(kanban, (kanban) => mutate(kanban)),
+  setItemField: (item, field, value) => {
+    Obj.update(item, (item: any) => {
+      item[field] = value;
+    });
+  },
+});
+
+/**
+ * Returns a memoized ECHO change callback for the given kanban.
+ * Returns null when kanban is undefined.
+ */
+export const useEchoChangeCallback = <T extends Obj.Unknown = Obj.Unknown>(
+  kanban: Kanban.Kanban | undefined,
+): KanbanChangeCallback<T> | null => useMemo(() => (kanban ? createEchoChangeCallback<T>(kanban) : null), [kanban]);

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.browser.test.ts

@@ -0,0 +1,235 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, Registry } from '@effect-atom/atom-react';
+import { act, renderHook } from '@testing-library/react';
+import * as Schema from 'effect/Schema';
+import { beforeEach, describe, test } from 'vitest';
+
+import { Filter, JsonSchema, Obj, Query, Type } from '@dxos/echo';
+import { type View } from '@dxos/echo';
+import { Format, FormatAnnotation, PropertyMetaAnnotationId } from '@dxos/echo/internal';
+import { ObjectId } from '@dxos/keys';
+import { ProjectionModel, ViewModel, createDirectChangeCallback } from '@dxos/schema';
+
+import { Kanban } from '#types';
+
+import { useKanbanBoardModel } from './useKanbanBoardModel';
+
+// TODO(wittjosiah): Consider adding single-select to TestSchema.Task and using that instead.
+const KanbanTaskSchema = Schema.Struct({
+  title: Schema.optional(Schema.String),
+  status: Schema.Literal('__uncategorized__', 'a', 'b').pipe(
+    FormatAnnotation.set(Format.TypeFormat.SingleSelect),
+    Schema.annotations({
+      title: 'Status',
+      [PropertyMetaAnnotationId]: {
+        singleSelect: {
+          options: [
+            { id: '__uncategorized__', title: 'Uncategorized', color: 'neutral' },
+            { id: 'a', title: 'A', color: 'blue' },
+            { id: 'b', title: 'B', color: 'green' },
+          ],
+        },
+      },
+    }),
+    Schema.optional,
+  ),
+}).pipe(
+  Type.object({
+    typename: 'com.example.type.kanban-task',
+    version: '0.1.0',
+  }),
+);
+
+type KanbanTask = Schema.Schema.Type<typeof KanbanTaskSchema>;
+
+describe('useKanbanBoardModel', () => {
+  let registry: Registry.Registry;
+  let view: View.View;
+  let kanban: Kanban.Kanban;
+  let projection: ProjectionModel;
+
+  beforeEach(() => {
+    registry = Registry.make();
+    const jsonSchema = JsonSchema.toJsonSchema(KanbanTaskSchema) as Parameters<typeof createDirectChangeCallback>[1];
+    view = ViewModel.make({
+      query: Query.select(Filter.type(KanbanTaskSchema)),
+      jsonSchema,
+      pivotFieldName: 'status',
+    });
+    kanban = Kanban.make({
+      view: view,
+      arrangement: {
+        order: ['a', 'b'],
+        columns: { a: { ids: [] }, b: { ids: [] } },
+      },
+    });
+    projection = new ProjectionModel({
+      registry,
+      view,
+      baseSchema: jsonSchema,
+      change: createDirectChangeCallback(view.projection, jsonSchema),
+    });
+  });
+
+  test('returns model with getColumns and getItems', ({ expect }) => {
+    const itemA = Obj.make(KanbanTaskSchema, { status: 'a' });
+    const itemB = Obj.make(KanbanTaskSchema, { status: 'b' });
+    const initialItems: KanbanTask[] = [itemA, itemB];
+    const itemsAtom = Atom.make<KanbanTask[]>(() => initialItems);
+
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    const model = result.current;
+    expect(model.getColumnId).toBeDefined();
+    expect(model.getItemId).toBeDefined();
+    expect(model.isColumn).toBeDefined();
+    expect(model.isItem).toBeDefined();
+
+    const columns = model.getColumns();
+    expect(columns.length).toBeGreaterThanOrEqual(1);
+    const columnValues = columns.map((col) => col.columnValue);
+    expect(columnValues).toContain('a');
+    expect(columnValues).toContain('b');
+
+    const colA = columns.find((c) => c.columnValue === 'a');
+    const colB = columns.find((c) => c.columnValue === 'b');
+    expect(colA).toBeDefined();
+    expect(colB).toBeDefined();
+
+    const itemsA = model.getItems(colA!);
+    const itemsB = model.getItems(colB!);
+    expect(itemsA.map((i) => i.id)).toContain(itemA.id);
+    expect(itemsB.map((i) => i.id)).toContain(itemB.id);
+  });
+
+  test('getItems updates when itemsAtom source changes', ({ expect }) => {
+    const initialItem = Obj.make(KanbanTaskSchema, { status: 'a' });
+    const initialItems: KanbanTask[] = [initialItem];
+    const initialItemsAtom = Atom.make<KanbanTask[]>(() => initialItems);
+
+    const { result, rerender } = renderHook(
+      ({ itemsAtom }) => useKanbanBoardModel(kanban, projection, itemsAtom, registry),
+      { initialProps: { itemsAtom: initialItemsAtom } },
+    );
+
+    const columns = result.current.getColumns();
+    const colA = columns.find((c) => c.columnValue === 'a');
+    expect(colA).toBeDefined();
+    expect(result.current.getItems(colA!).length).toBe(1);
+    expect(result.current.getItems(colA!).map((i) => i.id)).toEqual([initialItem.id]);
+
+    const secondItem = Obj.make(KanbanTaskSchema, { status: 'a' });
+    const newItems: KanbanTask[] = [initialItem, secondItem];
+    const newItemsAtom = Atom.make<KanbanTask[]>(() => newItems);
+    act(() => {
+      rerender({ itemsAtom: newItemsAtom });
+    });
+
+    expect(result.current.getItems(colA!).length).toBe(2);
+    expect(result.current.getItems(colA!).map((i) => i.id)).toEqual([initialItem.id, secondItem.id]);
+  });
+
+  test('columns atom updates when kanban arrangement changes', ({ expect }) => {
+    const itemsAtom = Atom.make<KanbanTask[]>(() => []);
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    let columnsUpdateCount = 0;
+    registry.subscribe(result.current.columns, () => {
+      columnsUpdateCount++;
+    });
+
+    const columnsBefore = result.current.getColumns();
+    const orderBefore = columnsBefore.map((c) => c.columnValue);
+    expect(orderBefore).toEqual(['__uncategorized__', 'a', 'b']);
+
+    act(() => {
+      Obj.update(kanban, (kanban) => {
+        kanban.arrangement.order = ['b', 'a'];
+      });
+    });
+
+    const columnsAfter = registry.get(result.current.columns) ?? [];
+    const orderAfter = columnsAfter.map((c) => c.columnValue);
+    expect(orderAfter).toEqual(['__uncategorized__', 'b', 'a']);
+    // TODO(wittjosiah): Try to reduce to 1.
+    expect(columnsUpdateCount).toBe(2);
+  });
+
+  test('getItems returns items in column ordered by arrangement ids', ({ expect }) => {
+    const item1 = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const item2 = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const item3 = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const items: KanbanTask[] = [item1, item2, item3];
+    const itemsAtom = Atom.make<KanbanTask[]>(() => items);
+
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    const columns = result.current.getColumns();
+    const colA = columns.find((c) => c.columnValue === 'a');
+    expect(colA).toBeDefined();
+    expect(result.current.getItems(colA!).length).toBe(3);
+
+    let itemsColAUpdateCount = 0;
+    registry.subscribe(result.current.items(colA!), () => {
+      itemsColAUpdateCount++;
+    });
+
+    act(() => {
+      Obj.update(kanban, (kanban) => {
+        kanban.arrangement.columns['a'] = {
+          ids: [item3.id, item1.id, item2.id],
+        };
+      });
+    });
+
+    const itemsAfter = result.current.getItems(colA!);
+    expect(itemsAfter.map((i) => i.id)).toEqual([item3.id, item1.id, item2.id]);
+    expect(itemsColAUpdateCount).toBe(1);
+  });
+
+  test('subscribing to one column items atom does not fire when another column changes', ({ expect }) => {
+    const itemA = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'a',
+    });
+    const itemB = Obj.make(KanbanTaskSchema, {
+      id: ObjectId.random(),
+      status: 'b',
+    });
+    const items: KanbanTask[] = [itemA, itemB];
+    const itemsAtom = Atom.make<KanbanTask[]>(() => items);
+
+    const { result } = renderHook(() => useKanbanBoardModel(kanban, projection, itemsAtom, registry));
+
+    const columns = result.current.getColumns();
+    const colA = columns.find((c) => c.columnValue === 'a');
+    const colB = columns.find((c) => c.columnValue === 'b');
+    expect(colA).toBeDefined();
+    expect(colB).toBeDefined();
+
+    let itemsColAUpdateCount = 0;
+    registry.subscribe(result.current.items(colA!), () => {
+      itemsColAUpdateCount++;
+    });
+
+    act(() => {
+      Obj.update(kanban, (kanban) => {
+        kanban.arrangement.columns['b'] = { ids: [itemB.id] };
+      });
+    });
+
+    expect(itemsColAUpdateCount).toBe(0);
+  });
+});

package/src/hooks/useKanbanBoardModel.ts

@@ -0,0 +1,157 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, type Registry } from '@effect-atom/atom-react';
+import { useMemo } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { AtomObj } from '@dxos/echo-atom';
+import type { BoardModel } from '@dxos/react-ui-mosaic';
+import type { ProjectionModel } from '@dxos/schema';
+
+import { type BaseKanbanItem, type ColumnStructure, type Kanban } from '#types';
+
+import {
+  computeColumnStructure,
+  getOrderByColumnFromArrangement,
+  getOrderFromArrangement,
+  orderItemsInColumn,
+} from '../util';
+
+/**
+ * Builds a board model that maps kanban arrangement and projection onto columns and per-column items.
+ *
+ * @template T - Item type (must have id; defaults to BaseKanbanItem).
+ * @param kanban - Kanban object (arrangement, view).
+ * @param projection - ProjectionModel for pivot field and options.
+ * @param itemsAtom - Atom holding the full item list.
+ * @param registry - Registry for reading atom values.
+ * @returns BoardModel with columns atom, items family, and getColumns/getItems.
+ */
+export function useKanbanBoardModel<T extends BaseKanbanItem = BaseKanbanItem>(
+  kanban: Kanban.Kanban,
+  projection: ProjectionModel,
+  itemsAtom: Atom.Atom<T[]>,
+  registry: Registry.Registry,
+): BoardModel<ColumnStructure, T> {
+  // 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?.spec?.kind === 'view' && kanban.spec.view
+        ? AtomObj.make(kanban.spec.view)
+        : Atom.make<undefined>(() => undefined),
+    [kanban?.spec],
+  );
+
+  /**
+   * 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) => {
+        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.
+  const effectiveByColumnAtom = useMemo(
+    () => Atom.make((get) => getOrderByColumnFromArrangement(get(arrangementAtom))),
+    [arrangementAtom],
+  );
+
+  // Column structure: depends on pivotFieldId (not full view), arrangement, and projection so columns only fire when pivot or arrangement changes.
+  const columnsAtom = useMemo(
+    () =>
+      Atom.make((get) => {
+        const pivotFieldId = get(pivotFieldIdAtom);
+        if (pivotFieldId === undefined) {
+          return [];
+        }
+
+        get(projection.fields);
+        const fieldProj = projection.tryGetFieldProjection(pivotFieldId);
+        if (!fieldProj) {
+          return [];
+        }
+
+        const selectOptions = fieldProj.props.options ?? [];
+        if (selectOptions.length === 0) {
+          return [];
+        }
+
+        const arrangement = get(arrangementAtom);
+        const order = getOrderFromArrangement(arrangement);
+        const byColumn = getOrderByColumnFromArrangement(arrangement);
+        return computeColumnStructure(order, byColumn, selectOptions);
+      }),
+    [pivotFieldIdAtom, arrangementAtom, projection],
+  );
+
+  // Per-column slice of arrangement so each column’s items atom only depends on that column’s ids.
+  const columnArrangementAtomFamily = useMemo(
+    () =>
+      Atom.family<string, Atom.Atom<ColumnStructure>>((columnValue: string) =>
+        Atom.make((get) => {
+          const byColumn = get(effectiveByColumnAtom);
+          return {
+            columnValue,
+            ids: [...(byColumn[columnValue]?.ids ?? [])],
+          };
+        }),
+      ),
+    [effectiveByColumnAtom],
+  );
+
+  // Items for a single column: filter all items by pivot field, sort by this column’s ids, then append new items.
+  const itemsAtomFamily = useMemo(
+    () =>
+      Atom.family<string, Atom.Atom<T[]>>((columnValue: string) =>
+        Atom.make((get) => {
+          const columnArr = get(columnArrangementAtomFamily(columnValue));
+          const allItems = get(itemsAtom);
+          const pivotFieldId = get(pivotFieldIdAtom);
+
+          if (pivotFieldId === undefined) {
+            return [];
+          }
+
+          // TODO(wittjosiah): Try to narrow this down further.
+          get(projection.fields);
+          const fieldProj = projection.tryGetFieldProjection(pivotFieldId);
+          if (!fieldProj) {
+            return [];
+          }
+
+          const selectOptions = fieldProj.props.options ?? [];
+          const pivotPath = fieldProj.props.property;
+          const validColumnValues = new Set(selectOptions.map((opt) => opt.id));
+          return orderItemsInColumn(allItems, columnArr.ids, columnValue, pivotPath, validColumnValues);
+        }),
+      ),
+    [columnArrangementAtomFamily, itemsAtom, pivotFieldIdAtom, projection],
+  );
+
+  return useMemo(
+    () => ({
+      getColumnId: (data) => data.columnValue,
+      getItemId: (data) => (data as T).id,
+      isColumn: (obj): obj is ColumnStructure =>
+        typeof obj === 'object' && obj !== null && 'columnValue' in obj && 'ids' in obj,
+      // TODO(wittjosiah): This should be restricted to objects of the type of the kanban view.
+      isItem: (obj): obj is T => Obj.isObject(obj),
+      columns: columnsAtom,
+      items: (column) => itemsAtomFamily(column.columnValue),
+      getColumns: () => registry.get(columnsAtom) ?? [],
+      getItems: (column) => registry.get(itemsAtomFamily(column.columnValue)) ?? [],
+    }),
+    [columnsAtom, itemsAtomFamily, registry],
+  );
+}