@dxos/plugin-chess 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/capabilities/react-surface.tsx

@@ -2,29 +2,34 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
-import { Obj } from '@dxos/echo';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 
-import { ChessContainer, ChessComponent } from '../components';
-import { meta } from '../meta';
-import { ChessType } from '../types';
+import { ChessArticle, ChessCard } from '#containers';
+import { Chess } from '#types';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: meta.id,
-      role: ['article', 'section'],
-      // TODO(burdon): Could this be standardized so that we don't require a subject property (like below)?
-      filter: (data): data is { subject: ChessType } => Obj.instanceOf(ChessType, data.subject),
-      component: ({ data, role }) => <ChessContainer game={data.subject} role={role} />,
-    }),
-    createSurface({
-      id: 'plugin-chess',
-      // TODO(burdon): Change role to card?
-      role: 'canvas-node',
-      filter: Obj.instanceOf(ChessType),
-      component: ({ data }) => <ChessComponent game={data} />,
-    }),
-  ]);
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'game',
+        filter: AppSurface.oneOf(
+          AppSurface.object(AppSurface.Article, Chess.Game),
+          AppSurface.object(AppSurface.Section, Chess.Game),
+        ),
+        component: ({ data, role }) => (
+          <ChessArticle role={role} subject={data.subject} attendableId={data.attendableId} />
+        ),
+      }),
+      Surface.create({
+        id: 'game-card',
+        filter: AppSurface.object(AppSurface.Card, Chess.Game),
+        component: ({ data, role }) => <ChessCard role={role} subject={data.subject} />,
+      }),
+    ]),
+  ),
+);

package/src/cli/index.ts

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

package/src/cli/plugin.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+import { SpaceOperation } from '@dxos/plugin-space/operations';
+import { type CreateObject } from '@dxos/plugin-space/types';
+
+import { meta } from '#meta';
+import { Chess } from '#types';
+
+// TODO(wittjosiah): Factor out shared modules.
+export const ChessPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addMetadataModule({
+    metadata: {
+      id: Chess.Game.typename,
+      metadata: {
+        createObject: ((props, options) =>
+          Effect.gen(function* () {
+            const object = Chess.make(props);
+            return yield* Operation.invoke(SpaceOperation.AddObject, {
+              object,
+              target: options.target,
+              hidden: true,
+              targetNodeId: options.targetNodeId,
+            });
+          })) satisfies CreateObject,
+      },
+    },
+  }),
+  AppPlugin.addSchemaModule({ schema: [Chess.Game] }),
+  Plugin.make,
+);

package/src/components/Chessboard/Chessboard.stories.tsx

@@ -0,0 +1,94 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+
+import { withClientProvider } from '@dxos/react-client/testing';
+import { type Player } from '@dxos/react-ui-gameboard';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Chess } from '#types';
+
+import { translations } from '../../translations';
+import { Chessboard, type ChessboardController, type ChessboardInfoProps } from './Chessboard';
+
+const SAMPLE_PGN =
+  '1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 4. c3 Nf6 5. d4 exd4 6. cxd4 Bb4+ 7. Nc3 d5 8. exd5 Nxd5 9. O-O Be6 10. Qb3 Na5 11. Qa4+ c6 12. Bxd5 Bxc3 13. Bxe6 fxe6 *';
+
+const PROMOTION_PGN =
+  '1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 4. c3 Nf6 5. d4 exd4 6. cxd4 Bb4+ 7. Nc3 d5 8. exd5 Nxd5 9. O-O Be6 10. Qb3 Na5 11. Qa4+ c6 12. Bxd5 Bxc3 13. Bxe6 fxe6 14. d5 Qg5 15. dxe6 Kf8 16. e7+ Kg8 *';
+
+type DefaultStoryProps = {
+  pgn?: string;
+};
+
+const DefaultStory = ({ pgn }: DefaultStoryProps) => {
+  const game = useMemo(() => Chess.make(pgn ? { pgn } : undefined), [pgn]);
+  const [orientation, setOrientation] = useState<Player>('white');
+  const [showInfo, setShowInfo] = useState(true);
+  const controller = useRef<ChessboardController>(null);
+
+  const handleSelect = useCallback<NonNullable<ChessboardInfoProps['onSelect']>>((index) => {
+    controller.current?.setMoveNumber(index);
+  }, []);
+
+  return (
+    <Chessboard.Root game={game} ref={controller}>
+      <div className='flex h-full w-full gap-4 p-4 overflow-hidden'>
+        <Chessboard.Content classNames='grow'>
+          <Chessboard.Board classNames='border rounded-xs' orientation={orientation} />
+        </Chessboard.Content>
+        {showInfo && (
+          <div className='flex flex-col justify-center items-center overflow-hidden'>
+            <Chessboard.Info
+              orientation={orientation}
+              min={8}
+              max={8}
+              onOrientationChange={setOrientation}
+              onClose={() => setShowInfo(false)}
+              onSelect={handleSelect}
+            />
+          </div>
+        )}
+      </div>
+    </Chessboard.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-chess/components/Chessboard',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withClientProvider({ createIdentity: true })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const WithPgn: Story = {
+  args: {
+    pgn: SAMPLE_PGN,
+  },
+};
+
+export const Promotion: Story = {
+  args: {
+    pgn: PROMOTION_PGN,
+  },
+};
+
+export const NewGame: Story = {
+  args: {
+    pgn: undefined,
+  },
+};

package/src/components/Chessboard/Chessboard.tsx

@@ -0,0 +1,180 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import React, {
+  type PropsWithChildren,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from 'react';
+
+import { addEventListener } from '@dxos/async';
+import { useObject } from '@dxos/echo-react';
+import { type ThemedClassName } from '@dxos/react-ui';
+import {
+  type ChessModel,
+  Gameboard,
+  type GameboardRootProps,
+  Chessboard as NaturalChessboard,
+  type ChessboardProps as NaturalChessboardProps,
+  getRawPgn,
+  useGameboardContext,
+} from '@dxos/react-ui-gameboard';
+import { useSoundEffect } from '@dxos/react-ui-sfx';
+
+import { type Chess } from '#types';
+
+import { Info, type InfoProps } from './Info';
+import { ExtendedChessModel } from './types';
+
+export interface ChessboardController {
+  setMoveNumber(index: number): void;
+}
+
+//
+// Root
+//
+
+type RootProps = PropsWithChildren<{
+  game: Chess.Game;
+}>;
+
+const Root = forwardRef<ChessboardController, RootProps>(({ game, children }, forwardedRef) => {
+  const registry = useContext(RegistryContext);
+  const model = useMemo(() => new ExtendedChessModel(registry, game), [registry]);
+  const click = useSoundEffect('Click');
+  const [pgn, updatePgn] = useObject(game, 'pgn');
+
+  // Controller.
+  useImperativeHandle(forwardedRef, () => {
+    return {
+      setMoveNumber: (index) => model.setMoveIndex(index),
+    };
+  }, [model]);
+
+  // TODO(wittjosiah): Rather than useEffect to sync ECHO object to model, create an alternative model implementation.
+  //   This model would take the ECHO object and derive game state directly from that.
+  //   Mutation methods would mutate the ECHO object and other state would be derived from that.
+
+  // External change.
+  // NOTE: Warning if user has not interacted with the board.
+  useEffect(() => {
+    if (model.pgn !== getRawPgn(pgn ?? '')) {
+      const silent = model.pgn === '*';
+      model.update(pgn);
+      if (!silent) {
+        void click.play();
+      }
+    }
+  }, [pgn]);
+
+  // Move.
+  const handleDrop = useCallback<NonNullable<GameboardRootProps<ChessModel>['onDrop']>>(
+    (move) => {
+      if (!model.makeMove(move)) {
+        return false;
+      }
+
+      void click.play();
+      updatePgn(() => model.pgn);
+      return true;
+    },
+    [model],
+  );
+
+  return (
+    <Gameboard.Root model={model} onDrop={handleDrop}>
+      {children}
+    </Gameboard.Root>
+  );
+});
+
+//
+// Content
+//
+
+type Role = 'card--content';
+
+type ContentProps = ThemedClassName<PropsWithChildren<{ role?: Role }>>;
+
+const Content = ({ classNames, children }: ContentProps) => {
+  return (
+    <Gameboard.Content grow contain classNames={classNames}>
+      {children}
+    </Gameboard.Content>
+  );
+};
+
+//
+// Board
+//
+
+const BOARD_NAME = 'Chessboard.Board';
+
+type BoardProps = NaturalChessboardProps;
+
+const Board = (props: BoardProps) => {
+  const registry = useContext(RegistryContext);
+  const { model } = useGameboardContext<ChessModel>(BOARD_NAME);
+
+  // Keyboard navigation.
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!ref.current) {
+      return;
+    }
+
+    // Participate in keyboard navigation (set tabIndex={0})
+    ref.current.setAttribute('data-arrow-keys', 'all');
+
+    return addEventListener(ref.current, 'keydown', (ev) => {
+      const moveIndex = registry.get(model.moveIndex);
+      switch (ev.key) {
+        case 'ArrowUp':
+          model.setMoveIndex(0);
+          break;
+        case 'ArrowDown':
+          model.setMoveIndex(model.game.history().length);
+          break;
+        case 'ArrowLeft':
+          if (moveIndex > 0) {
+            model.setMoveIndex(moveIndex - 1);
+          }
+          break;
+        case 'ArrowRight':
+          if (moveIndex < model.game.history().length) {
+            model.setMoveIndex(moveIndex + 1);
+          }
+          break;
+      }
+    });
+  }, [registry, model]);
+
+  return <NaturalChessboard {...props} ref={ref} />;
+};
+
+Board.displayName = BOARD_NAME;
+
+//
+// Chessboard
+//
+
+export const Chessboard = {
+  Root: Root,
+  Content: Content,
+  Board: Board,
+  Info: Info,
+};
+
+export type {
+  RootProps as ChessboardRootProps,
+  ContentProps as ChessboardContentProps,
+  BoardProps as ChessboardBoardProps,
+  InfoProps as ChessboardInfoProps,
+};

package/src/components/Chessboard/Info.tsx

@@ -0,0 +1,253 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import React, { type JSX, type PropsWithChildren, useEffect, useMemo, useRef } from 'react';
+
+import { generateName } from '@dxos/display-name';
+import { Obj } from '@dxos/echo';
+import { type SpaceMember, useMembers } from '@dxos/react-client/echo';
+import { Icon, IconButton, Select, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { type Player, useGameboardContext } from '@dxos/react-ui-gameboard';
+import { mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { type ExtendedChessModel } from './types';
+
+const INFO_NAME = 'Chessboard.Info';
+
+export type InfoProps = ThemedClassName<
+  {
+    orientation?: Player;
+    onOrientationChange?: (orientation: Player) => void;
+    onClose?: () => void;
+  } & Pick<HistoryProps, 'min' | 'max' | 'onSelect'>
+>;
+
+export const Info = ({ classNames, orientation = 'white', onOrientationChange, onClose, ...props }: InfoProps) => {
+  const { t } = useTranslation(meta.id);
+  const { model } = useGameboardContext<ExtendedChessModel>(INFO_NAME);
+  const db = Obj.getDatabase(model.object);
+  const members = useMembers(db?.spaceId);
+
+  return (
+    <div
+      className={mx(
+        'grid grid-rows-[min-content_1fr_min-content] w-full min-w-[18rem] p-2 overflow-hidden bg-group-surface rounded-xs',
+        classNames,
+      )}
+    >
+      <PlayerIndicator
+        model={model}
+        player={orientation === 'white' ? 'black' : 'white'}
+        icon={
+          onClose && (
+            <IconButton
+              variant='ghost'
+              icon='ph--x--regular'
+              iconOnly
+              label={t('close-info.button')}
+              size={4}
+              onClick={onClose}
+            />
+          )
+        }
+      >
+        <PlayerSelector
+          value={model.object.players?.[orientation === 'white' ? 'black' : 'white']}
+          onValueChange={(value) => {
+            Obj.change(model.object, (obj) => {
+              obj.players![orientation === 'white' ? 'black' : 'white'] = value;
+            });
+          }}
+          members={members}
+        />
+      </PlayerIndicator>
+
+      <History model={model} {...props} />
+
+      <PlayerIndicator
+        model={model}
+        player={orientation}
+        icon={
+          onOrientationChange && (
+            <IconButton
+              classNames={mx('transition duration-200 ease-linear', orientation === 'white' && 'rotate-180')}
+              icon='ph--arrows-clockwise--regular'
+              iconOnly
+              label={t('flip-board.button')}
+              size={4}
+              onClick={() => onOrientationChange(orientation === 'white' ? 'black' : 'white')}
+            />
+          )
+        }
+      >
+        <PlayerSelector
+          value={model.object.players?.[orientation]}
+          onValueChange={(value) => {
+            Obj.change(model.object, (obj) => {
+              obj.players![orientation] = value;
+            });
+          }}
+          members={members}
+        />
+      </PlayerIndicator>
+    </div>
+  );
+};
+
+Info.displayName = INFO_NAME;
+
+//
+// History
+//
+
+type HistoryProps = ThemedClassName<{
+  model: ExtendedChessModel;
+  min?: number;
+  max?: number;
+  onSelect?: (index: number) => void;
+}>;
+
+const History = ({ classNames, model, min, max, onSelect }: HistoryProps) => {
+  const { t } = useTranslation(meta.id);
+  const moveIndex = useAtomValue(model.moveIndex);
+  const label = model.game.isGameOver()
+    ? model.game.isCheckmate()
+      ? t('game.checkmate.label')
+      : model.game.isStalemate()
+        ? t('game.stalemate.label')
+        : t('game.draw.label')
+    : model.game.isCheck()
+      ? t('game.check.label')
+      : undefined;
+
+  const history = model.game.history();
+  const moves = useMemo(
+    () =>
+      history.reduce(
+        (acc, move, index) => {
+          if (index % 2 === 0) {
+            acc.push([{ index, move }]);
+          } else {
+            acc[acc.length - 1].push({ index, move });
+          }
+          return acc;
+        },
+        [] as { index: number; move: string }[][],
+      ),
+    [history.length],
+  );
+
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    scrollerRef.current?.scrollTo({ top: scrollerRef.current.scrollHeight });
+  }, [history.length]);
+
+  useEffect(() => {
+    const div = scrollerRef.current?.querySelector(`[data-index="${moveIndex - 1}"]`);
+    scrollerRef.current?.classList.add('scrollbar-none');
+    div?.scrollIntoView({ behavior: 'smooth' });
+    scrollerRef.current?.classList.remove('scrollbar-none');
+  }, [moveIndex]);
+
+  return (
+    <div
+      ref={scrollerRef}
+      className={mx('overflow-y-auto', classNames)}
+      style={{
+        minHeight: min === undefined ? 'auto' : `${min * 24}px`,
+        maxHeight: max === undefined ? 'auto' : `${max * 24}px`,
+      }}
+    >
+      {moves.map(([a, b], index) => (
+        <div key={index} className='grid grid-cols-[3rem_1fr_1fr_1rem] gap-2 ps-4'>
+          <div className='content-center text-xs text-subdued'>{index + 1}</div>
+          {a && (
+            <div
+              data-index={a.index}
+              className={mx('ps-2 text-sm cursor-pointer', a.index === moveIndex - 1 && 'bg-primary-500')}
+              onClick={() => onSelect?.(a.index + 1)}
+            >
+              {a.move}
+            </div>
+          )}
+          {b && (
+            <div
+              data-index={b.index}
+              className={mx('ps-2 text-sm cursor-pointer', b.index === moveIndex - 1 && 'bg-primary-500')}
+              onClick={() => onSelect?.(b.index + 1)}
+            >
+              {b.move}
+            </div>
+          )}
+        </div>
+      ))}
+      {label && <div className='text-center'>{label}</div>}
+    </div>
+  );
+};
+
+//
+// PlayerIndicator
+//
+
+type PlayerIndicatorProps = PropsWithChildren<{
+  model: ExtendedChessModel;
+  player: Player;
+  icon?: JSX.Element;
+}>;
+
+const PlayerIndicator = ({ children, model, player, icon }: PlayerIndicatorProps) => {
+  const turn = player === (model.game.turn() === 'w' ? 'white' : 'black');
+  return (
+    <div className='grid grid-cols-[2rem_1fr_2rem] gap-2 h-(--dx-rail-size) px-1 flex items-center overflow-hidden'>
+      <div className='place-items-center'>
+        <Icon
+          icon={turn ? 'ph--circle--fill' : 'ph--circle--thin'}
+          size={6}
+          classNames={mx(turn && (model.game.isCheckmate() ? 'text-error-500' : 'text-success-text'))}
+        />
+      </div>
+      <div className='truncate overflow-hidden items-center'>{children}</div>
+      {icon}
+    </div>
+  );
+};
+
+//
+// PlayerSelector
+//
+
+type PlayerSelectorProps = {
+  value?: string;
+  onValueChange: (player: string) => void;
+  members: SpaceMember[];
+};
+
+const PlayerSelector = ({ value, onValueChange, members }: PlayerSelectorProps) => {
+  const { t } = useTranslation(meta.id);
+  return (
+    <Select.Root value={value} onValueChange={onValueChange}>
+      <Select.TriggerButton placeholder={t('select-player.button')} />
+      <Select.Portal>
+        <Select.Content>
+          <Select.Viewport>
+            {members.map((member) => {
+              const memberKey = member.identity.identityKey.toHex();
+              const displayName = member.identity?.profile?.displayName || generateName(memberKey);
+              return (
+                <Select.Option key={memberKey} value={memberKey}>
+                  {displayName}
+                </Select.Option>
+              );
+            })}
+          </Select.Viewport>
+          <Select.Arrow />
+        </Select.Content>
+      </Select.Portal>
+    </Select.Root>
+  );
+};

package/src/components/Chessboard/index.ts

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

package/src/components/Chessboard/types.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Registry } from '@effect-atom/atom-react';
+
+import { ChessModel } from '@dxos/react-ui-gameboard';
+
+import { type Chess } from '#types';
+
+export class ExtendedChessModel extends ChessModel {
+  constructor(
+    registry: Registry.Registry,
+    readonly object: Chess.Game,
+  ) {
+    super(registry);
+  }
+}

package/src/components/index.ts

@@ -1,9 +1,5 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import { lazy } from 'react';
-
-export * from './ChessComponent';
-
-export const ChessContainer = lazy(() => import('./ChessContainer'));
+export * from './Chessboard';