@dxos/plugin-board 0.8.4-main.c1de068

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@dxos/plugin-board",
+  "version": "0.8.4-main.c1de068",
+  "description": "Surface plugin for card baords",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types/src/types/index.d.ts",
+      "browser": "./dist/lib/browser/types/index.mjs",
+      "node": "./dist/lib/node-esm/types/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "types": [
+        "dist/types/src/types/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@preact-signals/safe-react": "^0.9.0",
+    "@preact/signals-core": "^1.9.0",
+    "@preact/signals-react": "^3.2.0",
+    "effect": "3.17.0",
+    "@dxos/ai": "0.8.4-main.c1de068",
+    "@dxos/assistant": "0.8.4-main.c1de068",
+    "@dxos/app-framework": "0.8.4-main.c1de068",
+    "@dxos/async": "0.8.4-main.c1de068",
+    "@dxos/client": "0.8.4-main.c1de068",
+    "@dxos/blueprints": "0.8.4-main.c1de068",
+    "@dxos/echo": "0.8.4-main.c1de068",
+    "@dxos/effect": "0.8.4-main.c1de068",
+    "@dxos/echo-schema": "0.8.4-main.c1de068",
+    "@dxos/invariant": "0.8.4-main.c1de068",
+    "@dxos/log": "0.8.4-main.c1de068",
+    "@dxos/plugin-client": "0.8.4-main.c1de068",
+    "@dxos/plugin-graph": "0.8.4-main.c1de068",
+    "@dxos/plugin-space": "0.8.4-main.c1de068",
+    "@dxos/plugin-search": "0.8.4-main.c1de068",
+    "@dxos/random": "0.8.4-main.c1de068",
+    "@dxos/react-client": "0.8.4-main.c1de068",
+    "@dxos/react-ui": "0.8.4-main.c1de068",
+    "@dxos/react-ui-board": "0.8.4-main.c1de068",
+    "@dxos/react-ui-form": "0.8.4-main.c1de068",
+    "@dxos/react-ui-stack": "0.8.4-main.c1de068",
+    "@dxos/schema": "0.8.4-main.c1de068",
+    "@dxos/util": "0.8.4-main.c1de068"
+  },
+  "devDependencies": {
+    "@types/react": "~18.2.0",
+    "@types/react-dom": "~18.2.0",
+    "react": "~18.2.0",
+    "react-dom": "~18.2.0",
+    "vite": "5.4.7",
+    "@dxos/plugin-preview": "0.8.4-main.c1de068",
+    "@dxos/plugin-theme": "0.8.4-main.c1de068",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.c1de068",
+    "@dxos/react-ui-theme": "0.8.4-main.c1de068",
+    "@dxos/test-utils": "0.8.4-main.c1de068",
+    "@dxos/storybook-utils": "0.8.4-main.c1de068"
+  },
+  "peerDependencies": {
+    "effect": "^3.13.3",
+    "react": "~18.2.0",
+    "react-dom": "~18.2.0",
+    "@dxos/react-ui": "0.8.4-main.c1de068",
+    "@dxos/react-ui-theme": "0.8.4-main.c1de068"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/BoardPlugin.tsx

@@ -0,0 +1,58 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Capabilities, contributes, createIntent, defineModule, definePlugin, Events } from '@dxos/app-framework';
+import { ClientEvents } from '@dxos/plugin-client';
+import { SpaceCapabilities } from '@dxos/plugin-space';
+import { defineObjectForm } from '@dxos/plugin-space/types';
+import { translations as boardTranslations } from '@dxos/react-ui-board';
+
+import { IntentResolver, ReactSurface } from './capabilities';
+import { meta } from './meta';
+import { translations } from './translations';
+import { Board } from './types';
+
+export const BoardPlugin = () => {
+  return definePlugin(meta, [
+    defineModule({
+      id: `${meta.id}/module/translations`,
+      activatesOn: Events.SetupTranslations,
+      activate: () => contributes(Capabilities.Translations, [...translations, ...boardTranslations]),
+    }),
+    defineModule({
+      id: `${meta.id}/module/metadata`,
+      activatesOn: Events.SetupMetadata,
+      activate: () =>
+        // TODO(burdon): "Metadata" here seems non-descriptive; is this specifically for the type? ObjectMetadata?
+        contributes(Capabilities.Metadata, {
+          id: Board.Board.typename,
+          metadata: {
+            icon: 'ph--squares-four--regular',
+          },
+        }),
+    }),
+    defineModule({
+      id: `${meta.id}/module/object-form`,
+      activatesOn: ClientEvents.SetupSchema,
+      activate: () =>
+        contributes(
+          SpaceCapabilities.ObjectForm,
+          defineObjectForm({
+            objectSchema: Board.Board,
+            getIntent: () => createIntent(Board.Create),
+          }),
+        ),
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-surface`,
+      activatesOn: Events.SetupReactSurface,
+      activate: ReactSurface,
+    }),
+    defineModule({
+      id: `${meta.id}/module/intent-resolver`,
+      activatesOn: Events.SetupIntentResolver,
+      activate: IntentResolver,
+    }),
+  ]);
+};

package/src/capabilities/index.ts

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

package/src/capabilities/intent-resolver.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, createResolver } from '@dxos/app-framework';
+import { Obj } from '@dxos/echo';
+
+import { Board } from '../types';
+
+export default () => [
+  contributes(
+    Capabilities.IntentResolver,
+    createResolver({
+      intent: Board.Create,
+      resolve: ({ name }) => {
+        return {
+          data: {
+            object: Obj.make(Board.Board, {
+              name,
+              items: [],
+              layout: {
+                size: {
+                  width: 5,
+                  height: 5,
+                },
+                cells: {},
+              },
+            }),
+          },
+        };
+      },
+    }),
+  ),
+];

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { contributes, Capabilities, type PluginContext, createSurface } from '@dxos/app-framework';
+import { Obj } from '@dxos/echo';
+
+import { BoardContainer } from '../components';
+import { meta } from '../meta';
+import { Board } from '../types';
+
+export default (context: PluginContext) =>
+  contributes(Capabilities.ReactSurface, [
+    createSurface({
+      id: meta.id,
+      role: ['article', 'section'],
+      filter: (data): data is { subject: Board.Board } => Obj.instanceOf(Board.Board, data.subject),
+      component: ({ data, role }) => <BoardContainer board={data.subject} role={role} />,
+    }),
+  ]);

package/src/components/BoardContainer.stories.tsx

@@ -0,0 +1,142 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type StoryObj, type Meta } from '@storybook/react-vite';
+import React, { useEffect, useState } from 'react';
+
+import { IntentPlugin, SettingsPlugin } from '@dxos/app-framework';
+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 { SpacePlugin } from '@dxos/plugin-space';
+import { StorybookLayoutPlugin } from '@dxos/plugin-storybook-layout';
+import { ThemePlugin } from '@dxos/plugin-theme';
+import { faker } from '@dxos/random';
+import { type Client, useClient } from '@dxos/react-client';
+import { Filter, useSpaces, useQuery, Ref, type Space } from '@dxos/react-client/echo';
+import { translations as stackTranslations } from '@dxos/react-ui-stack';
+import { defaultTx } from '@dxos/react-ui-theme';
+import { DataType } from '@dxos/schema';
+import { withLayout } from '@dxos/storybook-utils';
+
+import { BoardContainer } from './BoardContainer';
+import { translations } from '../translations';
+import { Board } from '../types';
+
+faker.seed(0);
+
+//
+// Initialization utilities
+//
+
+const initializeBoard = async ({ space, client }: { space: Space; client: Client }) => {
+  // Create a new board
+  const board = Obj.make(Board.Board, {
+    name: 'Test Board',
+    items: [],
+    layout: {
+      size: { width: 7, height: 5 },
+      cells: {},
+    },
+  });
+
+  return { board };
+};
+
+//
+// Story components
+//
+
+const rollOrg = () =>
+  ({
+    name: faker.commerce.productName(),
+    description: faker.lorem.paragraph(),
+    image: faker.image.url(),
+    website: faker.internet.url(),
+    status: faker.helpers.arrayElement(DataType.OrganizationStatusOptions).id,
+    // TODO(thure): Why is this so difficult to type?
+  }) as unknown as DataType.Organization;
+
+const StorybookBoard = () => {
+  const _client = useClient();
+  const spaces = useSpaces();
+  const space = spaces[spaces.length - 1];
+  const boards = useQuery(space, 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' board={board} />;
+};
+
+type StoryProps = {};
+
+//
+// Story definitions
+//
+
+const meta: Meta<StoryProps> = {
+  title: 'plugins/plugin-board/Board',
+  component: StorybookBoard,
+  render: () => <StorybookBoard />,
+  parameters: { translations: [...translations, ...stackTranslations] },
+  decorators: [
+    withLayout({ fullscreen: true }),
+    withPluginManager({
+      plugins: [
+        ThemePlugin({ tx: defaultTx }),
+        ClientPlugin({
+          types: [DataType.Organization, DataType.Person, Board.Board],
+          onClientInitialized: async (_, client) => {
+            await client.halo.createIdentity();
+            const space = await client.spaces.create();
+            await space.waitUntilReady();
+            const { board } = await initializeBoard({
+              space,
+              client,
+            });
+            space.db.add(board);
+
+            // Add some sample items
+            Array.from({ length: 10 }).map((_, index) => {
+              const org = Obj.make(DataType.Organization, rollOrg());
+              space.db.add(org);
+              board.items.push(Ref.make(org));
+              board.layout.cells[org.id] = {
+                x: Math.floor(Math.random() * 5) - 2,
+                y: Math.floor(Math.random() * 5) - 2,
+                width: 1,
+                height: 1,
+              };
+              return org;
+            });
+          },
+        }),
+        StorybookLayoutPlugin(),
+        PreviewPlugin(),
+        SpacePlugin(),
+        IntentPlugin(),
+        SettingsPlugin(),
+      ],
+    }),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<StoryProps>;
+
+export const Default: Story = {};

package/src/components/BoardContainer.tsx

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { effect } from '@preact/signals-react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+import { createIntent, Surface, useIntentDispatcher } from '@dxos/app-framework';
+import { getSpace } from '@dxos/client/echo';
+import { type Obj, Ref, type Type } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { SpaceAction } from '@dxos/plugin-space/types';
+import { Board, type BoardController, type BoardRootProps } from '@dxos/react-ui-board';
+import { StackItem } from '@dxos/react-ui-stack';
+import { isNonNullable } from '@dxos/util';
+
+// TODO(thure): There is debate about having to rename either the type or the React component. A best practice should be chosen and either Board or Kanban (or both) should be refactored to apply it.
+import { type Board as BoardType } from '../types';
+
+export type BoardContainerProps = {
+  role: string;
+  board: BoardType.Board;
+};
+
+export const BoardContainer = ({ role, board }: BoardContainerProps) => {
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+  const controller = useRef<BoardController>(null);
+
+  // TODO(burdon): Create effect utility for reactive arrays.
+  const [items, setItems] = useState<Type.Expando[]>([]);
+  useEffect(() => {
+    let t: NodeJS.Timeout;
+    effect(() => {
+      const refs = [...board.items];
+      t = setTimeout(async () => {
+        const items = await Ref.Array.loadAll(refs);
+        setItems(items.filter(isNonNullable));
+      });
+    });
+
+    return () => clearTimeout(t);
+  }, [board.items]);
+
+  const handleAdd = useCallback<NonNullable<BoardRootProps['onAdd']>>(
+    async (position = { x: 0, y: 0 }) => {
+      const space = getSpace(board);
+      invariant(space);
+      await dispatch(
+        createIntent(SpaceAction.OpenCreateObject, {
+          target: space,
+          navigable: false,
+          onCreateObject: (object: Obj.Any) => {
+            board.items.push(Ref.make(object));
+            board.layout.cells[object.id] = { ...position, width: 1, height: 1 };
+            controller.current?.center(position);
+          },
+        }),
+      );
+    },
+    [board, controller, dispatch],
+  );
+
+  // 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);
+      if (idx !== -1) {
+        board.items.splice(idx, 1);
+      }
+      delete board.layout.cells[id];
+      setItems((items) => items.filter((item) => item.id !== id));
+    },
+    [board],
+  );
+
+  const handleMove = useCallback<NonNullable<BoardRootProps['onMove']>>(
+    (id, position) => {
+      const layout = board.layout.cells[id];
+      board.layout.cells[id] = { ...layout, ...position };
+    },
+    [board],
+  );
+
+  return (
+    <Board.Root ref={controller} layout={board.layout} onAdd={handleAdd} onDelete={handleDelete} onMove={handleMove}>
+      <StackItem.Content toolbar>
+        <Board.Controls />
+        <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 role='card--extrinsic' data={{ subject: item }} limit={1} />
+                </Board.Cell>
+              ))}
+            </Board.Content>
+          </Board.Viewport>
+        </Board.Container>
+      </StackItem.Content>
+    </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,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './meta';
+
+export * from './BoardPlugin';

package/src/meta.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type PluginMeta } from '@dxos/app-framework';
+
+export const meta: PluginMeta = {
+  id: 'dxos.org/plugin/board',
+  name: 'Board',
+  description:
+    'A spatial, infinite canvas app combining notes, media, and whiteboarding in a tactile, visual interface.',
+  icon: 'ph--squares-four--regular',
+  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-board',
+  screenshots: [],
+};

package/src/translations.ts

@@ -0,0 +1,27 @@
+//
+// 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',
+      },
+      [meta.id]: {
+        'plugin name': 'Board',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/index.ts

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

package/src/types/schema.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo-schema';
+import { BoardLayout } from '@dxos/react-ui-board';
+
+import { meta } from '../meta';
+
+export namespace Board {
+  //
+  // Types
+  //
+
+  // TODO(burdon): View?
+  export const Board = Schema.Struct({
+    name: Schema.optional(Schema.String),
+    items: Schema.mutable(Schema.Array(Type.Ref(Type.Expando))),
+    layout: Schema.mutable(BoardLayout),
+  }).pipe(
+    Type.Obj({
+      typename: 'dxos.org/type/Board',
+      version: '0.1.0',
+    }),
+    LabelAnnotation.set(['name']),
+  );
+
+  export interface Board extends Schema.Schema.Type<typeof Board> {}
+
+  //
+  // Actions
+  //
+
+  export class Create extends Schema.TaggedClass<Create>()(`${meta.id}/action/create`, {
+    input: Schema.Struct({
+      name: Schema.optional(Schema.String),
+    }),
+    output: Schema.Struct({
+      object: Board,
+    }),
+  }) {}
+}