@dxos/plugin-board 0.8.4-main.1068cf700f

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@dxos/plugin-board",
+  "version": "0.8.4-main.1068cf700f",
+  "description": "Surface plugin for card baords",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs",
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts"
+    },
+    "./types": {
+      "browser": "./dist/lib/browser/types/index.mjs",
+      "node": "./dist/lib/node-esm/types/index.mjs",
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "types": [
+        "dist/types/src/types/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "effect": "3.19.16",
+    "@dxos/ai": "0.8.4-main.1068cf700f",
+    "@dxos/app-framework": "0.8.4-main.1068cf700f",
+    "@dxos/assistant": "0.8.4-main.1068cf700f",
+    "@dxos/async": "0.8.4-main.1068cf700f",
+    "@dxos/blueprints": "0.8.4-main.1068cf700f",
+    "@dxos/echo": "0.8.4-main.1068cf700f",
+    "@dxos/client": "0.8.4-main.1068cf700f",
+    "@dxos/echo-react": "0.8.4-main.1068cf700f",
+    "@dxos/app-toolkit": "0.8.4-main.1068cf700f",
+    "@dxos/invariant": "0.8.4-main.1068cf700f",
+    "@dxos/log": "0.8.4-main.1068cf700f",
+    "@dxos/effect": "0.8.4-main.1068cf700f",
+    "@dxos/operation": "0.8.4-main.1068cf700f",
+    "@dxos/plugin-graph": "0.8.4-main.1068cf700f",
+    "@dxos/plugin-search": "0.8.4-main.1068cf700f",
+    "@dxos/plugin-space": "0.8.4-main.1068cf700f",
+    "@dxos/random": "0.8.4-main.1068cf700f",
+    "@dxos/plugin-client": "0.8.4-main.1068cf700f",
+    "@dxos/react-client": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui-attention": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui-board": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui-form": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui-stack": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui-mosaic": "0.8.4-main.1068cf700f",
+    "@dxos/schema": "0.8.4-main.1068cf700f",
+    "@dxos/util": "0.8.4-main.1068cf700f",
+    "@dxos/types": "0.8.4-main.1068cf700f"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vite": "7.1.9",
+    "@dxos/plugin-testing": "0.8.4-main.1068cf700f",
+    "@dxos/plugin-preview": "0.8.4-main.1068cf700f",
+    "@dxos/plugin-theme": "0.8.4-main.1068cf700f",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.1068cf700f",
+    "@dxos/storybook-utils": "0.8.4-main.1068cf700f",
+    "@dxos/test-utils": "0.8.4-main.1068cf700f",
+    "@dxos/ui-theme": "0.8.4-main.1068cf700f"
+  },
+  "peerDependencies": {
+    "effect": "3.19.16",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-main.1068cf700f",
+    "@dxos/ui-theme": "0.8.4-main.1068cf700f"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/BoardPlugin.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { type CreateObject } from '@dxos/plugin-space/types';
+import { translations as boardTranslations } from '@dxos/react-ui-board';
+
+import { ReactSurface } from './capabilities';
+import { meta } from './meta';
+import { translations } from './translations';
+import { Board } from './types';
+
+export const BoardPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addMetadataModule({
+    metadata: {
+      id: Board.Board.typename,
+      metadata: {
+        icon: 'ph--squares-four--regular',
+        iconHue: 'green',
+        createObject: ((props) => Effect.sync(() => Board.makeBoard(props))) satisfies CreateObject,
+        addToCollectionOnCreate: true,
+      },
+    },
+  }),
+  AppPlugin.addSchemaModule({ schema: [Board.Board] }),
+  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
+  AppPlugin.addTranslationsModule({ translations: [...translations, ...boardTranslations] }),
+  Plugin.make,
+);

package/src/capabilities/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './react-surface';

package/src/capabilities/react-surface/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));

package/src/capabilities/react-surface/react-surface.tsx

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { Obj } from '@dxos/echo';
+
+import { BoardContainer } from '../../components';
+import { meta } from '../../meta';
+import { Board } from '../../types';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: meta.id,
+        role: ['article', 'section'],
+        filter: (data): data is { subject: Board.Board } => Obj.instanceOf(Board.Board, data.subject),
+        component: ({ role, data }) => <BoardContainer role={role} subject={data.subject} />,
+      }),
+    ]),
+  ),
+);

package/src/components/BoardContainer.stories.tsx

@@ -0,0 +1,121 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect, useState } from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Obj } from '@dxos/echo';
+import { ClientPlugin } from '@dxos/plugin-client';
+import { PreviewPlugin } from '@dxos/plugin-preview';
+import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
+import { faker } from '@dxos/random';
+import { Filter, Ref, useQuery, useSpaces } from '@dxos/react-client/echo';
+import { withTheme } from '@dxos/react-ui/testing';
+import { translations as stackTranslations } from '@dxos/react-ui-stack';
+import { Organization, Person } from '@dxos/types';
+
+import { translations } from '../translations';
+import { Board } from '../types';
+
+import { BoardContainer } from './BoardContainer';
+
+faker.seed(0);
+
+const createBoard = () =>
+  Obj.make(Board.Board, {
+    name: 'Test Board',
+    items: [],
+    layout: {
+      size: { width: 7, height: 5 },
+      cells: {},
+    },
+  });
+
+const createOrg = () =>
+  Obj.make(Organization.Organization, {
+    name: faker.commerce.productName(),
+    description: faker.lorem.paragraph(),
+    image: faker.image.url(),
+    website: faker.internet.url(),
+    // TODO(burdon): Fix.
+    // status: faker.helpers.arrayElement(Organization.StatusOptions).id,
+  });
+
+const DefaultStory = () => {
+  const spaces = useSpaces();
+  const space = spaces[spaces.length - 1];
+  const boards = useQuery(space?.db, Filter.type(Board.Board));
+  const [board, setBoard] = useState<Board.Board>();
+
+  useEffect(() => {
+    if (boards.length && !board) {
+      const board = boards[0];
+      setBoard(board);
+    }
+  }, [boards]);
+
+  if (!board) {
+    return null;
+  }
+
+  return <BoardContainer role='board' subject={board} />;
+};
+
+//
+// Story definitions
+//
+
+const meta = {
+  title: 'plugins/plugin-board/Board',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Organization.Organization, Person.Person, Board.Board],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              yield* Effect.promise(() => client.halo.createIdentity());
+              const space = yield* Effect.promise(() => client.spaces.create());
+              yield* Effect.promise(() => space.waitUntilReady());
+              const board = space.db.add(createBoard());
+
+              Obj.change(board, (b) => {
+                // Add some sample items
+                Array.from({ length: 10 }).map(() => {
+                  const org = createOrg();
+                  space.db.add(org);
+                  b.items.push(Ref.make(org));
+                  b.layout.cells[org.id] = {
+                    x: Math.floor(Math.random() * 5) - 2,
+                    y: Math.floor(Math.random() * 5) - 2,
+                    width: 1,
+                    height: 1,
+                  };
+                  return org;
+                });
+              });
+            }),
+        }),
+
+        StorybookPlugin({}),
+        PreviewPlugin(),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations: [...translations, ...stackTranslations],
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/BoardContainer.tsx

@@ -0,0 +1,151 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { type SurfaceComponentProps } from '@dxos/app-toolkit/ui';
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { useObject, useObjects } from '@dxos/echo-react';
+import { invariant } from '@dxos/invariant';
+import { useQuery } from '@dxos/react-client/echo';
+import { Layout } from '@dxos/react-ui';
+import { useAttention } from '@dxos/react-ui-attention';
+import { Board, type BoardController, type BoardRootProps, type Position } from '@dxos/react-ui-board';
+import { ObjectPicker, type ObjectPickerContentProps } from '@dxos/react-ui-form';
+import { isNonNullable } from '@dxos/util';
+
+import { type Board as BoardType } from '../types';
+
+const DEFAULT_POSITION = { x: 0, y: 0 } satisfies Position;
+
+type PickerState = {
+  position: Position;
+};
+
+export type BoardContainerProps = SurfaceComponentProps<BoardType.Board>;
+
+export const BoardContainer = ({ role, subject: board }: BoardContainerProps) => {
+  const controller = useRef<BoardController>(null);
+  const [boardItems] = useObject(board, 'items');
+  const items = useObjects(boardItems ?? []);
+  const addTriggerRef = useRef<HTMLButtonElement | null>(null);
+  const [pickerState, setPickerState] = useState<PickerState | null>(null);
+  const attendableId = Obj.getDXN(board).toString();
+  const { hasAttention } = useAttention(attendableId);
+
+  const db = Obj.getDatabase(board);
+  // TODO(burdon): Use search.
+  const objects = useQuery(db, Filter.everything());
+  const options = useMemo<ObjectPickerContentProps['options']>(
+    () =>
+      objects
+        .filter((obj) => obj.id !== board.id)
+        .map((obj) => {
+          const label = Obj.getLabel(obj);
+          if (label) {
+            return {
+              id: obj.id,
+              label,
+              hue: 'neutral' as const,
+            };
+          }
+        })
+        .filter(isNonNullable)
+        .sort(({ label: a }, { label: b }) => a.toLocaleLowerCase().localeCompare(b.toLocaleLowerCase())),
+    [objects],
+  );
+
+  const handleAdd = useCallback<NonNullable<BoardRootProps['onAdd']>>(
+    async (anchor, position = DEFAULT_POSITION) => {
+      const db = Obj.getDatabase(board);
+      invariant(db);
+      addTriggerRef.current = anchor;
+      setPickerState({
+        position,
+      });
+    },
+    [board],
+  );
+
+  // TODO(burdon): Use intents so can be undone.
+  const handleDelete = useCallback<NonNullable<BoardRootProps['onDelete']>>(
+    (id) => {
+      // TODO(burdon): Impl. DXN.equals and pass in DXN from `id`.
+      const idx = board.items.findIndex((ref) => ref.dxn.asEchoDXN()?.echoId === id);
+      Obj.change(board, (b) => {
+        if (idx !== -1) {
+          b.items.splice(idx, 1);
+        }
+        delete b.layout.cells[id];
+      });
+    },
+    [board],
+  );
+
+  const handleMove = useCallback<NonNullable<BoardRootProps['onMove']>>(
+    (id, position) => {
+      const layout = board.layout.cells[id];
+      Obj.change(board, (b) => {
+        b.layout.cells[id] = { ...layout, ...position };
+      });
+    },
+    [board],
+  );
+
+  const handleSelect = useCallback<NonNullable<ObjectPickerContentProps['onSelect']>>(
+    (id) => {
+      if (!pickerState) {
+        return;
+      }
+
+      // Find the selected object by id from the space.
+      const selectedObject = objects.find((obj) => obj.id === id);
+      if (!Obj.isObject(selectedObject)) {
+        return;
+      }
+
+      // Create a reference to the selected object and add it to the board.
+      Obj.change(board, (b) => {
+        b.items.push(Ref.make(selectedObject));
+
+        // Set the layout position for the new item.
+        b.layout.cells[selectedObject.id.toString()] = pickerState.position;
+      });
+
+      // Close the picker.
+      setPickerState(null);
+    },
+    [pickerState, objects, board],
+  );
+
+  return (
+    <Board.Root ref={controller} layout={board.layout} onAdd={handleAdd} onDelete={handleDelete} onMove={handleMove}>
+      <ObjectPicker.Root
+        open={!!pickerState}
+        onOpenChange={(nextOpen: boolean) => {
+          setPickerState(nextOpen ? { position: DEFAULT_POSITION } : null);
+        }}
+      >
+        <Layout.Main role={role} toolbar>
+          <Board.Toolbar disabled={!hasAttention} />
+          <Board.Container>
+            <Board.Viewport classNames='border-none'>
+              <Board.Backdrop />
+              <Board.Content>
+                {items?.map((item, index) => (
+                  <Board.Cell item={item} key={index} layout={board.layout?.cells[item.id] ?? { x: 0, y: 0 }}>
+                    <Surface.Surface role='card--content' data={{ subject: item }} limit={1} />
+                  </Board.Cell>
+                ))}
+              </Board.Content>
+            </Board.Viewport>
+          </Board.Container>
+        </Layout.Main>
+        <ObjectPicker.Content options={options} onSelect={handleSelect} classNames='popover-card-width' />
+        <ObjectPicker.VirtualTrigger virtualRef={addTriggerRef} />
+      </ObjectPicker.Root>
+    </Board.Root>
+  );
+};

package/src/components/index.ts

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

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './components';
+export * from './meta';
+export * from './types';
+
+export * from './BoardPlugin';

package/src/meta.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
+
+export const meta: Plugin.Meta = {
+  id: 'dxos.org/plugin/board',
+  name: 'Board',
+  description: trim`
+    Infinite canvas workspace that combines sticky notes, media, and whiteboarding tools.
+    Arrange and connect ideas freely in a visual space perfect for brainstorming and creative collaboration.
+  `,
+  icon: 'ph--squares-four--regular',
+  iconHue: 'green',
+  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-board',
+  screenshots: [],
+};

package/src/translations.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Resource } from '@dxos/react-ui';
+
+import { meta } from './meta';
+import { Board } from './types';
+
+export const translations = [
+  {
+    'en-US': {
+      [Board.Board.typename]: {
+        'typename label': 'Board',
+        'typename label_zero': 'Boards',
+        'typename label_one': 'Board',
+        'typename label_other': 'Boards',
+        'object name placeholder': 'New board',
+        'rename object label': 'Rename board',
+        'delete object label': 'Delete board',
+        'object deleted label': 'Board deleted',
+      },
+      [meta.id]: {
+        'plugin name': 'Board',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/Board.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Obj, Type } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
+import { BoardLayout, defaultLayout } from '@dxos/react-ui-board';
+
+/**
+ * Board and layout.
+ */
+export const Board = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  items: Type.Ref(Type.Obj).pipe(Schema.Array, FormInputAnnotation.set(false)),
+  layout: BoardLayout.pipe(FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'dxos.org/type/Board',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+);
+
+export interface Board extends Schema.Schema.Type<typeof Board> {}
+
+export const makeBoard = (props: Partial<Obj.MakeProps<typeof Board>> = {}) =>
+  Obj.make(Board, {
+    items: [],
+    layout: defaultLayout,
+    ...props,
+  });

package/src/types/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as Board from './Board';