@ankhorage/zora 21.0.22 → 21.1.0

package/src/features/card/cardMeta.ts

@@ -1,12 +1,22 @@
 import type { ZoraComponentMeta } from '../authoring';
-import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
+import {
+  CHESS_ALLOWED_CHILDREN,
+  CONTAINER_ALLOWED_CHILDREN,
+  GAME_ALLOWED_CHILDREN,
+  TABLETOP_ALLOWED_CHILDREN,
+} from '../authoring/allowedChildren';
 import { COMPONENT_THEME_AUTHORING } from '../authoring/constants';
 
 export const cardMeta = {
   name: 'Card',
   category: 'component',
   directManifestNode: true,
-  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  allowedChildren: [
+    ...CONTAINER_ALLOWED_CHILDREN,
+    ...CHESS_ALLOWED_CHILDREN,
+    ...GAME_ALLOWED_CHILDREN,
+    ...TABLETOP_ALLOWED_CHILDREN,
+  ],
   blueprint: { label: 'Card', defaultProps: { title: 'Card' } },
   events: { press: { label: 'Press', eventType: 'card.press', payloadFields: [] } },
   props: {

package/src/features/chess/adapters/inbound/ChessBoard.tsx

@@ -0,0 +1,169 @@
+import React from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+import type { ChessBoardProps, ChessPieceState, ChessSquareId } from '../../../../types/chess';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { createBoardSquares } from '../../utils/createBoardSquares';
+import { createChessBoardColorScheme } from '../../utils/createChessBoardColorScheme';
+import { isLightSquare } from '../../utils/isLightSquare';
+
+const symbols = new Map<string, string>([
+  ['white:p', '♙'],
+  ['white:n', '♘'],
+  ['white:b', '♗'],
+  ['white:r', '♖'],
+  ['white:q', '♕'],
+  ['white:k', '♔'],
+  ['black:p', '♟'],
+  ['black:n', '♞'],
+  ['black:b', '♝'],
+  ['black:r', '♜'],
+  ['black:q', '♛'],
+  ['black:k', '♚'],
+]);
+
+/*** Renders caller-owned chess presentation state without chess rule execution. */
+export const ChessBoard = withZoraThemeScope(ChessBoardInner);
+
+/*** Renders the current presentation state without executing chess rules. */
+function ChessBoardInner({
+  pieces = [],
+  orientation = 'white',
+  selectedSquare = null,
+  legalTargets = [],
+  lastMove = null,
+  disabled = false,
+  showCoordinates = false,
+  colorScheme,
+  onSquarePress,
+  onMoveAttempt,
+  renderPiece,
+  interactionPolicy,
+  testID,
+}: ChessBoardProps) {
+  const { theme } = useZoraTheme();
+  const colors = createChessBoardColorScheme(theme, colorScheme);
+  const squares = createBoardSquares(orientation);
+  const piecesBySquare = new Map<ChessSquareId, ChessPieceState>(
+    pieces.map((piece) => [piece.square, piece]),
+  );
+  const legalTargetSet = new Set(legalTargets);
+  const pressSquare = (square: ChessSquareId) => {
+    if (disabled || interactionPolicy === 'passive') return;
+    onSquarePress?.(square);
+    if (selectedSquare !== null && selectedSquare !== square)
+      onMoveAttempt?.({ from: selectedSquare, to: square });
+  };
+  return (
+    <View
+      accessibilityLabel="Chess board"
+      style={[styles.board, { borderColor: colors.border, opacity: disabled ? 0.56 : 1 }]}
+      testID={testID}
+    >
+      {squares.map((square) => {
+        const piece = piecesBySquare.get(square);
+        const light = isLightSquare(square);
+        const isTarget = legalTargetSet.has(square);
+        const backgroundColor =
+          selectedSquare === square
+            ? colors.selectedSquare
+            : isTarget
+              ? colors.legalTarget
+              : lastMove?.from === square
+                ? colors.lastMoveFrom
+                : lastMove?.to === square
+                  ? colors.lastMoveTo
+                  : light
+                    ? colors.lightSquare
+                    : colors.darkSquare;
+        const pieceContent =
+          piece === undefined
+            ? null
+            : renderPiece
+              ? renderPiece({
+                  color: piece.color === 'white' ? colors.lightPiece : colors.darkPiece,
+                  piece: piece.piece,
+                  square,
+                })
+              : (symbols.get(`${piece.color}:${piece.piece.toLowerCase()}`) ?? piece.piece);
+        return (
+          <Pressable
+            accessibilityLabel={square}
+            accessibilityRole="button"
+            disabled={disabled || interactionPolicy === 'passive'}
+            key={square}
+            onPress={() => pressSquare(square)}
+            style={[styles.square, { backgroundColor }]}
+            testID={testID ? `${testID}-square-${square}` : undefined}
+          >
+            {showCoordinates ? (
+              <Text
+                style={[
+                  styles.coordinate,
+                  { color: light ? colors.lightSquareText : colors.darkSquareText },
+                ]}
+              >
+                {square}
+              </Text>
+            ) : null}
+            {piece === undefined ? null : (
+              <View pointerEvents="none" style={styles.pieceContainer}>
+                {renderPiece ? (
+                  pieceContent
+                ) : (
+                  <Text
+                    style={[
+                      styles.piece,
+                      { color: piece.color === 'white' ? colors.lightPiece : colors.darkPiece },
+                    ]}
+                  >
+                    {pieceContent}
+                  </Text>
+                )}
+              </View>
+            )}
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  board: {
+    aspectRatio: 1,
+    borderRadius: 12,
+    borderWidth: StyleSheet.hairlineWidth,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    overflow: 'hidden',
+    width: '100%',
+  },
+  coordinate: {
+    fontSize: 9,
+    fontWeight: '600',
+    left: 3,
+    opacity: 0.72,
+    position: 'absolute',
+    top: 2,
+    zIndex: 2,
+  },
+  piece: { fontSize: 32, fontWeight: '600', lineHeight: 38 },
+  pieceContainer: {
+    alignItems: 'center',
+    bottom: 0,
+    justifyContent: 'center',
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+  square: {
+    alignItems: 'center',
+    aspectRatio: 1,
+    width: '12.5%',
+    justifyContent: 'center',
+    position: 'relative',
+  },
+});

package/src/features/chess/adapters/inbound/OpeningBook.tsx

@@ -0,0 +1,131 @@
+import React from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+import type { OpeningBookMove, OpeningBookProps } from '../../../../types/chess';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { createOpeningBookColorScheme } from '../../utils/createOpeningBookColorScheme';
+
+/*** Renders caller-owned opening suggestions and their visual states. */
+export const OpeningBook = withZoraThemeScope(OpeningBookInner);
+
+/*** Formats an opening result percentage, accepting fractions or percentages. */
+function rate(label: string, value: number | undefined): string | undefined {
+  if (value === undefined || !Number.isFinite(value)) return undefined;
+  return `${label} ${Math.round(value <= 1 ? value * 100 : value)}%`;
+}
+
+/*** Resolves an opening move's stable row key. */
+function moveKey(move: OpeningBookMove): string {
+  return move.uci ?? move.fen ?? move.san;
+}
+
+/*** Renders the themed opening list without owning chess rules or data loading. */
+function OpeningBookInner({
+  moves = [],
+  title = 'Opening book',
+  loading = false,
+  errorText,
+  emptyText = 'No book moves for this position.',
+  selectedMove = null,
+  colorScheme,
+  onMovePress,
+  interactionPolicy,
+  testID,
+}: OpeningBookProps) {
+  const { theme } = useZoraTheme();
+  const colors = createOpeningBookColorScheme(theme, colorScheme);
+  const stateText = loading ? 'Loading opening moves…' : (errorText ?? emptyText);
+  const showState = loading || errorText !== undefined || moves.length === 0;
+  return (
+    <View
+      accessibilityLabel={title}
+      style={[
+        styles.root,
+        {
+          borderColor: colors.border,
+          backgroundColor: colors.surface,
+        },
+      ]}
+      testID={testID}
+    >
+      <Text style={[styles.title, { color: colors.titleText }]}>{title}</Text>
+      {!showState ? (
+        <View style={styles.moves}>
+          {moves.map((move) => {
+            const selected =
+              selectedMove !== null &&
+              (selectedMove === move.san || selectedMove === move.uci || selectedMove === move.fen);
+            const details = [
+              move.eco,
+              move.name,
+              move.games === undefined ? undefined : `${move.games} games`,
+            ].filter((part): part is string => typeof part === 'string' && part.length > 0);
+            const stats = [
+              rate('W', move.whiteWinRate),
+              rate('D', move.drawRate),
+              rate('B', move.blackWinRate),
+            ].filter((part): part is string => part !== undefined);
+            return (
+              <Pressable
+                accessibilityRole="button"
+                disabled={onMovePress === undefined || interactionPolicy === 'passive'}
+                key={moveKey(move)}
+                onPress={() => {
+                  if (interactionPolicy === 'passive') return;
+                  onMovePress?.(move);
+                }}
+                style={[
+                  styles.move,
+                  {
+                    backgroundColor: selected ? colors.selectedSurface : colors.surfaceHover,
+                    borderColor: colors.border,
+                  },
+                ]}
+                testID={testID ? `${testID}-move-${move.san}` : undefined}
+              >
+                <View style={styles.moveMain}>
+                  <Text style={[styles.san, { color: colors.primaryText }]}>{move.san}</Text>
+                  <Text style={[styles.meta, { color: colors.secondaryText }]}>
+                    {details.length > 0 ? details.join(' · ') : 'Book move'}
+                  </Text>
+                </View>
+                {stats.length > 0 ? (
+                  <View style={[styles.metric, { backgroundColor: colors.metricSurface }]}>
+                    <Text style={[styles.metricText, { color: colors.secondaryText }]}>
+                      {stats.join(' ')}
+                    </Text>
+                  </View>
+                ) : null}
+              </Pressable>
+            );
+          })}
+        </View>
+      ) : (
+        <Text style={[styles.stateText, { color: colors.secondaryText }]}>{stateText}</Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { borderRadius: 12, borderWidth: StyleSheet.hairlineWidth, gap: 10, padding: 12 },
+  title: { fontSize: 15, fontWeight: '700', lineHeight: 20 },
+  stateText: { fontSize: 13, lineHeight: 18 },
+  moves: { gap: 8 },
+  move: {
+    alignItems: 'center',
+    borderRadius: 10,
+    borderWidth: StyleSheet.hairlineWidth,
+    flexDirection: 'row',
+    gap: 10,
+    justifyContent: 'space-between',
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+  },
+  moveMain: { flex: 1, gap: 2 },
+  san: { fontSize: 16, fontWeight: '700', lineHeight: 20 },
+  meta: { fontSize: 12, lineHeight: 16 },
+  metric: { borderRadius: 999, paddingHorizontal: 8, paddingVertical: 4 },
+  metricText: { fontSize: 11, fontWeight: '600' },
+});

package/src/features/chess/meta.ts

@@ -0,0 +1,168 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+export const chessBoardMeta = {
+  name: 'ChessBoard',
+  category: 'component',
+  description:
+    'Renders caller-owned chess pieces, highlights, and move-attempt interactions without chess rules.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Chess board',
+    defaultProps: { pieces: [], orientation: 'white', showCoordinates: true },
+  },
+  events: {
+    squarePress: {
+      label: 'Square press',
+      eventType: 'chess.squarePress',
+      payloadFields: [{ path: 'square', type: 'string', label: 'Square' }],
+    },
+    moveAttempt: {
+      label: 'Move attempt',
+      eventType: 'chess.moveAttempt',
+      payloadFields: [
+        { path: 'from', type: 'string', label: 'From' },
+        { path: 'to', type: 'string', label: 'To' },
+      ],
+    },
+  },
+  bindings: {
+    props: {
+      pieces: {
+        label: 'Pieces',
+        value: { type: 'array', itemType: 'object' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+      legalTargets: {
+        label: 'Legal targets',
+        value: { type: 'array', itemType: 'string' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+  },
+  props: {
+    pieces: {
+      type: 'array',
+      category: 'Board',
+      label: 'Pieces',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    orientation: {
+      type: 'enum',
+      category: 'Board',
+      label: 'Orientation',
+      enum: ['white', 'black'],
+      default: 'white',
+      authoring: { authority: 'instance' },
+    },
+    selectedSquare: {
+      type: 'string',
+      category: 'Board',
+      label: 'Selected square',
+      authoring: { authority: 'instance' },
+    },
+    legalTargets: {
+      type: 'array',
+      category: 'Board',
+      label: 'Legal targets',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    showCoordinates: {
+      type: 'boolean',
+      category: 'Style',
+      label: 'Show coordinates',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;
+export const openingBookMeta = {
+  name: 'OpeningBook',
+  category: 'component',
+  description:
+    'Presents caller-owned opening suggestions and their loading, empty, selected, and press states.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Opening book',
+    defaultProps: {
+      moves: [],
+      title: 'Opening book',
+      emptyText: 'No book moves for this position.',
+    },
+  },
+  events: {
+    movePress: {
+      label: 'Move press',
+      eventType: 'chess.openingMovePress',
+      payloadFields: [
+        { path: 'san', type: 'string', label: 'SAN' },
+        { path: 'uci', type: 'string', label: 'UCI' },
+        { path: 'fen', type: 'string', label: 'Position' },
+      ],
+    },
+  },
+  bindings: {
+    props: {
+      moves: {
+        label: 'Moves',
+        value: { type: 'array', itemType: 'object' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+  },
+  props: {
+    moves: {
+      type: 'array',
+      category: 'Content',
+      label: 'Moves',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Opening book',
+      authoring: { authority: 'instance' },
+    },
+    emptyText: {
+      type: 'string',
+      category: 'Content',
+      label: 'Empty text',
+      default: 'No book moves for this position.',
+      authoring: { authority: 'instance' },
+    },
+    loading: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Loading',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    errorText: {
+      type: 'string',
+      category: 'State',
+      label: 'Error text',
+      authoring: { authority: 'instance' },
+    },
+    selectedMove: {
+      type: 'string',
+      category: 'State',
+      label: 'Selected move',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/chess/public.test.tsx

@@ -0,0 +1,165 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import type {
+  ChessBoard as ChessBoardComponent,
+  OpeningBook as OpeningBookComponent,
+} from './public';
+import { createBoardSquares } from './utils/createBoardSquares';
+import { createChessBoardColorScheme } from './utils/createChessBoardColorScheme';
+import { getSquareFile } from './utils/getSquareFile';
+import { getSquareRank } from './utils/getSquareRank';
+import { isLightSquare } from './utils/isLightSquare';
+
+const webDistRoot = join(import.meta.dir, '../../../web-dist');
+const load = (path: string) => import(pathToFileURL(join(webDistRoot, path)).href);
+
+describe('Chess presentation', () => {
+  test('keeps square order and theme-derived presentation independent of chess rules', () => {
+    expect(createBoardSquares('white').at(0)).toBe('a8');
+    expect(createBoardSquares('black').at(0)).toBe('h1');
+    expect(getSquareFile('e4')).toBe('e');
+    expect(getSquareRank('e4')).toBe('4');
+    expect(isLightSquare('a1')).toBe(false);
+    expect(typeof createChessBoardColorScheme).toBe('function');
+  });
+
+  test('renders custom React nodes, square IDs, and opening metadata through independent artifacts', async () => {
+    const { ChessBoard } = (await load('components/chess-board/index.js')) as {
+      ChessBoard: typeof ChessBoardComponent;
+    };
+    const { OpeningBook } = (await load('components/opening-book/index.js')) as {
+      OpeningBook: typeof OpeningBookComponent;
+    };
+    const markup = renderToStaticMarkup(
+      <>
+        <ChessBoard
+          colorScheme={{ selectedSquare: '#123456', legalTarget: '#234567' }}
+          legalTargets={['e4']}
+          pieces={[{ color: 'white', piece: 'p', square: 'e2' }]}
+          renderPiece={() => <div data-testid="custom-piece" />}
+          selectedSquare="e2"
+          showCoordinates
+          testID="board"
+        />
+        <OpeningBook
+          moves={[
+            {
+              san: 'Nf3',
+              eco: 'A04',
+              name: 'Reti Opening',
+              games: 42,
+              whiteWinRate: 0.52,
+              drawRate: 0.2,
+              blackWinRate: 0.28,
+            },
+          ]}
+          testID="book"
+        />
+      </>,
+    );
+    const browser = new Window();
+    browser.document.body.innerHTML = markup;
+    expect(browser.document.querySelectorAll('[data-testid^="board-square-"]')).toHaveLength(64);
+    expect(
+      browser.document.querySelector('[data-testid="board-square-e2"]')?.textContent,
+    ).toContain('e2');
+    expect(
+      browser.document.querySelector('[data-testid="custom-piece"]')?.parentElement?.className,
+    ).toContain('css-view');
+    expect(
+      browser.document.querySelector('[data-testid="board-square-e2"]')?.getAttribute('style'),
+    ).toContain('background-color:rgba(18,52,86,1.00)');
+    expect(
+      browser.document.querySelector('[data-testid="board-square-e4"]')?.getAttribute('style'),
+    ).toContain('background-color:rgba(35,69,103,1.00)');
+    expect(browser.document.querySelector('[data-testid="book-move-Nf3"]')?.textContent).toContain(
+      'A04 · Reti Opening · 42 games',
+    );
+    expect(browser.document.querySelector('[data-testid="book-move-Nf3"]')?.textContent).toContain(
+      'W 52% D 20% B 28%',
+    );
+    browser.close();
+  });
+
+  test('emits only caller-owned intents in active mode and suppresses them in passive mode', async () => {
+    const { ChessBoard } = (await load('components/chess-board/index.js')) as {
+      ChessBoard: typeof ChessBoardComponent;
+    };
+    const { OpeningBook } = (await load('components/opening-book/index.js')) as {
+      OpeningBook: typeof OpeningBookComponent;
+    };
+    const browser = new Window();
+    const keys = ['window', 'document', 'Node', 'navigator', 'IS_REACT_ACT_ENVIRONMENT'] as const;
+    const previous = keys.map(
+      (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+    );
+    Object.assign(globalThis, {
+      window: browser,
+      document: browser.document,
+      Node: browser.Node,
+      navigator: browser.navigator,
+      IS_REACT_ACT_ENVIRONMENT: true,
+    });
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const squares: string[] = [];
+    const moves: string[] = [];
+    const book: string[] = [];
+    const root = createRoot(host);
+    const render = (interactionPolicy: 'active' | 'passive') => (
+      <>
+        <ChessBoard
+          interactionPolicy={interactionPolicy}
+          selectedSquare="e2"
+          testID="board"
+          onSquarePress={(square) => squares.push(square)}
+          onMoveAttempt={(move) => moves.push(`${move.from}-${move.to}`)}
+        />
+        <OpeningBook
+          interactionPolicy={interactionPolicy}
+          moves={[{ san: 'e4' }]}
+          onMovePress={(move) => book.push(move.san)}
+          testID="book"
+        />
+      </>
+    );
+    try {
+      act(() => root.render(render('passive')));
+      act(() => {
+        host
+          .querySelector('[data-testid="board-square-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+        host
+          .querySelector('[data-testid="book-move-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+      });
+      expect([squares, moves, book]).toEqual([[], [], []]);
+      act(() => root.render(render('active')));
+      act(() => {
+        host
+          .querySelector('[data-testid="board-square-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+        host
+          .querySelector('[data-testid="book-move-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+      });
+      expect(squares).toEqual(['e4']);
+      expect(moves).toEqual(['e2-e4']);
+      expect(book).toEqual(['e4']);
+    } finally {
+      act(() => root.unmount());
+      browser.close();
+      for (const [key, descriptor] of previous) {
+        if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+        else Reflect.deleteProperty(globalThis, key);
+      }
+    }
+  });
+});

package/src/features/chess/public.ts

@@ -0,0 +1,27 @@
+export type {
+  ChessBoardColorOverrides,
+  ChessBoardColorScheme,
+  ChessBoardOrientation,
+  ChessBoardProps,
+  ChessMoveAttempt,
+  ChessPieceCode,
+  ChessPieceRenderContext,
+  ChessPieceRenderer,
+  ChessPieceState,
+  ChessPromotionPiece,
+  ChessSquareId,
+  OpeningBookColorOverrides,
+  OpeningBookColorScheme,
+  OpeningBookMove,
+  OpeningBookProps,
+} from '../../types/chess';
+export { ChessBoard } from './adapters/inbound/ChessBoard';
+export { OpeningBook } from './adapters/inbound/OpeningBook';
+export { chessSquares } from './utils/chessSquares';
+export { createBoardSquares } from './utils/createBoardSquares';
+export type { ChessColorThemeShape } from './utils/createChessBoardColorScheme';
+export { createChessBoardColorScheme } from './utils/createChessBoardColorScheme';
+export { createOpeningBookColorScheme } from './utils/createOpeningBookColorScheme';
+export { getSquareFile } from './utils/getSquareFile';
+export { getSquareRank } from './utils/getSquareRank';
+export { isLightSquare } from './utils/isLightSquare';

package/src/features/chess/utils/chessSquares.ts

@@ -0,0 +1,6 @@
+import type { ChessSquareId } from '../../../types/chess';
+
+/*** Lists every board square in ascending rank and file order. */
+export const chessSquares: readonly ChessSquareId[] = [1, 2, 3, 4, 5, 6, 7, 8].flatMap((rank) =>
+  [...'abcdefgh'].map((file) => `${file}${rank}` as ChessSquareId),
+);