@ankhorage/zora 21.0.23 → 21.1.0

package/src/features/tabletop/meta.ts

@@ -0,0 +1,254 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+export const cardBackMeta = {
+  name: 'CardBack',
+  category: 'component',
+  description: 'Renders one face-down playing card.',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Public card primitive composed by code-facing tabletop components, not a direct manifest node.',
+  blueprint: { label: 'Card back', defaultProps: { size: 'medium' } },
+  props: {
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['small', 'medium', 'large'],
+      default: 'medium',
+      authoring: { authority: 'instance' },
+    },
+    muted: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Muted',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;
+export const cardHandMeta = {
+  name: 'CardHand',
+  category: 'component',
+  description: 'Renders a compact caller-owned card hand.',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Public hand primitive composed by code-facing tabletop components, not a direct manifest node.',
+  blueprint: { label: 'Card hand', defaultProps: { cards: [], faceDownCards: 0, size: 'medium' } },
+  props: {
+    cards: {
+      type: 'array',
+      category: 'Cards',
+      label: 'Cards',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    faceDownCards: {
+      type: 'number',
+      category: 'Cards',
+      label: 'Face-down cards',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['small', 'medium', 'large'],
+      default: 'medium',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;
+export const playingCardMeta = {
+  name: 'PlayingCard',
+  category: 'component',
+  description: 'Renders one face-up caller-owned playing card.',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Public card primitive composed by code-facing tabletop components, not a direct manifest node.',
+  blueprint: {
+    label: 'Playing card',
+    defaultProps: { card: { rank: 'A', suit: 'spades' }, size: 'medium' },
+  },
+  bindings: {
+    props: { card: { label: 'Card', value: { type: 'object' }, acceptsFallback: true } },
+  },
+  props: {
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['small', 'medium', 'large'],
+      default: 'medium',
+      authoring: { authority: 'instance' },
+    },
+    selected: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Selected',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;
+export const tabletopTableMeta = {
+  name: 'TabletopTable',
+  category: 'component',
+  description:
+    'Arranges caller-owned player seats and shared cards around a responsive tabletop surface.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Tabletop table',
+    defaultProps: { seats: [], centerCards: [], shape: 'oval', cardSize: 'small' },
+  },
+  bindings: {
+    props: {
+      seats: {
+        label: 'Seats',
+        value: { type: 'array', itemType: 'object' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+      centerCards: {
+        label: 'Center cards',
+        value: { type: 'array', itemType: 'object' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+  },
+  props: {
+    seats: {
+      type: 'array',
+      category: 'Players',
+      label: 'Seats',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    centerCards: {
+      type: 'array',
+      category: 'Table',
+      label: 'Center cards',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    centerLabel: {
+      type: 'string',
+      category: 'Table',
+      label: 'Center label',
+      authoring: { authority: 'instance' },
+    },
+    centerSublabel: {
+      type: 'string',
+      category: 'Table',
+      label: 'Center sublabel',
+      authoring: { authority: 'instance' },
+    },
+    shape: {
+      type: 'enum',
+      category: 'Table',
+      label: 'Shape',
+      enum: ['circle', 'oval', 'rounded'],
+      default: 'oval',
+      authoring: { authority: 'instance' },
+    },
+    seatCount: {
+      type: 'enum',
+      category: 'Players',
+      label: 'Seat count',
+      enum: [2, 3, 4, 5, 6, 7, 8, 9, 10],
+      authoring: { authority: 'instance' },
+    },
+    cardSize: {
+      type: 'enum',
+      category: 'Cards',
+      label: 'Card size',
+      enum: ['small', 'medium', 'large'],
+      default: 'small',
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;
+export const pokerTrainingTableMeta = {
+  name: 'PokerTrainingTable',
+  category: 'pattern',
+  description: 'Maps serializable poker table data into the reusable tabletop presentation.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Poker training table',
+    defaultProps: { task: {}, defaultStackBigBlinds: 100, shape: 'oval', cardSize: 'small' },
+  },
+  bindings: {
+    props: {
+      task: {
+        label: 'Poker training task',
+        description: 'Table-relevant fields from a poker training task.',
+        value: {
+          type: 'object',
+          fields: [
+            { path: 'blinds', type: 'object', label: 'Blinds' },
+            { path: 'heroPosition', type: 'string', label: 'Hero position' },
+            { path: 'heroCards', type: 'array', label: 'Hero cards' },
+            { path: 'communityCards', type: 'array', label: 'Community cards' },
+            { path: 'pot', type: 'number', label: 'Pot' },
+            { path: 'players', type: 'array', label: 'Players' },
+          ],
+        },
+        acceptsFallback: true,
+      },
+    },
+  },
+  props: {
+    defaultStackBigBlinds: {
+      type: 'number',
+      category: 'Players',
+      label: 'Default stack in big blinds',
+      default: 100,
+      authoring: { authority: 'instance' },
+    },
+    shape: {
+      type: 'enum',
+      category: 'Table',
+      label: 'Shape',
+      enum: ['circle', 'oval', 'rounded'],
+      default: 'oval',
+      authoring: { authority: 'instance' },
+    },
+    cardSize: {
+      type: 'enum',
+      category: 'Cards',
+      label: 'Card size',
+      enum: ['small', 'medium', 'large'],
+      default: 'small',
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

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

@@ -0,0 +1,127 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import type {
+  CardHand as CardHandComponent,
+  PokerTrainingTable as PokerTrainingTableComponent,
+  TabletopTable as TabletopTableComponent,
+} from './public';
+import { createPokerTrainingTableState } from './utils/createPokerTrainingTableState';
+import { createTabletopGameSeats } from './utils/createTabletopGameSeats';
+import { getTabletopSeatPosition } from './utils/getTabletopSeatPosition';
+
+const webDistRoot = join(import.meta.dir, '../../../web-dist');
+const load = (path: string) => import(pathToFileURL(join(webDistRoot, path)).href);
+
+describe('Tabletop presentation', () => {
+  test('reconstructs the complete hero-oriented ring without training policy', () => {
+    const state = createPokerTrainingTableState({
+      tableSize: '6max',
+      heroPosition: 'CO',
+      heroCards: [{ rank: 'A', suit: 'spades' }],
+      blinds: { small: 1, big: 2 },
+      pot: 24,
+      players: [
+        { position: 'CO', stack: 200 },
+        { position: 'BTN', folded: true },
+      ],
+    });
+    expect(state.seatCount).toBe(6);
+    expect(state.seats.map((seat) => seat.id)).toEqual(['CO', 'BTN', 'SB', 'BB', 'UTG', 'HJ']);
+    expect(state.seats[0]).toMatchObject({
+      selected: true,
+      sublabel: '100 BB',
+      cards: [{ rank: 'A', suit: 'spades' }],
+    });
+    expect(state.seats[2]).toMatchObject({
+      disabled: true,
+      muted: true,
+      sublabel: '100 BB · Folded',
+    });
+    expect(state.seats[1]?.tokenLabel).toBe('D');
+    expect(state.centerLabel).toBe('Pot 24');
+    expect(state.centerSublabel).toBe('Blinds 1 / 2');
+    expect(state.accessibilityLabel).toContain('Hero CO');
+    expect(getTabletopSeatPosition(0, 6)).toEqual({ top: '84%', left: '50%' });
+  });
+
+  test('joins ordered seats with participant display overrides', () => {
+    expect(
+      createTabletopGameSeats({
+        seats: [
+          { id: 'north', defaultState: { label: 'North' } },
+          { id: 'south', defaultState: { label: 'South' } },
+        ],
+        participants: [{ seatId: 'south', state: { selected: true } }],
+      }),
+    ).toEqual([
+      { id: 'north', label: 'North', disabled: true, muted: true },
+      { id: 'south', label: 'South', selected: true },
+    ]);
+  });
+
+  test('renders card sizing, per-card IDs, seat accessibility, and table shapes', async () => {
+    const { CardHand } = (await load('components/card-hand/index.js')) as {
+      CardHand: typeof CardHandComponent;
+    };
+    const { TabletopTable } = (await load('components/tabletop-table/index.js')) as {
+      TabletopTable: typeof TabletopTableComponent;
+    };
+    const { PokerTrainingTable } = (await load('components/poker-training-table/index.js')) as {
+      PokerTrainingTable: typeof PokerTrainingTableComponent;
+    };
+    const markup = renderToStaticMarkup(
+      <>
+        <CardHand
+          cards={[{ rank: 'A', suit: 'spades' }]}
+          colorScheme={{ cardSurface: '#000000' }}
+          faceDownCards={1}
+          testID="hand"
+        />
+        <TabletopTable
+          shape="circle"
+          seats={[
+            { id: 'hero', label: 'Hero', sublabel: '100 BB', selected: true, tokenLabel: 'D' },
+          ]}
+          testID="table"
+        />
+        <PokerTrainingTable task={{ tableSize: '6max', heroPosition: 'CO' }} testID="poker" />
+      </>,
+    );
+    const browser = new Window();
+    browser.document.body.innerHTML = markup;
+    const card = browser.document.querySelector('[data-testid="hand-card-0"]');
+    expect(card?.getAttribute('aria-label')).toBe('ace of spades');
+    expect(card?.getAttribute('style')).toContain('height:56px');
+    expect(card?.getAttribute('style')).toContain('width:40px');
+    expect(card?.getAttribute('style')).toContain('background-color:rgba(0,0,0,1.00)');
+    expect(card?.textContent).toContain('A');
+    expect(card?.firstElementChild.getAttribute('style')).toContain('color:rgba(255,255,255,1.00)');
+    expect(
+      browser.document.querySelector('[data-testid="hand-hidden-0"]')?.getAttribute('aria-label'),
+    ).toBe('Hidden card');
+    expect(
+      browser.document.querySelector('[data-testid="table-seat-hero"]')?.getAttribute('aria-label'),
+    ).toBe('Hero, 100 BB, D, selected');
+    expect(browser.document.querySelectorAll('[data-testid^="poker-seat-"]')).toHaveLength(6);
+    expect(
+      browser.document.querySelector('[data-testid="poker"]')?.getAttribute('aria-label'),
+    ).toContain('Six-player poker table');
+    const circleTable = browser.document.querySelector('[data-testid="table"]');
+    expect(circleTable?.getAttribute('style')).toContain('aspect-ratio:1');
+    const circleSurface = circleTable?.firstElementChild.getAttribute('class');
+    browser.document.body.innerHTML = renderToStaticMarkup(
+      <TabletopTable seats={[]} shape="rounded" testID="table" />,
+    );
+    const roundedSurface = browser.document
+      .querySelector('[data-testid="table"]')
+      ?.firstElementChild.getAttribute('class');
+    expect(circleSurface).not.toBe(roundedSurface);
+    browser.close();
+  });
+});

package/src/features/tabletop/public.ts

@@ -0,0 +1,32 @@
+export type {
+  CardBackProps,
+  CardHandProps,
+  CreatePokerTrainingTableStateOptions,
+  CreateTabletopGameSeatsInput,
+  PlayingCardProps,
+  PlayingCardSuit,
+  PlayingCardValue,
+  PokerTrainingPlayer,
+  PokerTrainingTableProps,
+  PokerTrainingTableSize,
+  PokerTrainingTableState,
+  PokerTrainingTaskTableData,
+  TabletopCardSize,
+  TabletopColorOverrides,
+  TabletopColorScheme,
+  TabletopGameParticipantState,
+  TabletopGameSeatDefinition,
+  TabletopGameSeatPresentation,
+  TabletopSeatCount,
+  TabletopSeatState,
+  TabletopShape,
+  TabletopTableProps,
+} from '../../types/tabletop';
+export { CardBack } from './adapters/inbound/CardBack';
+export { CardHand } from './adapters/inbound/CardHand';
+export { PlayingCard } from './adapters/inbound/PlayingCard';
+export { PokerTrainingTable } from './adapters/inbound/PokerTrainingTable';
+export { TabletopTable } from './adapters/inbound/TabletopTable';
+export { createPokerTrainingTableState } from './utils/createPokerTrainingTableState';
+export { createTabletopColorScheme } from './utils/createTabletopColorScheme';
+export { createTabletopGameSeats } from './utils/createTabletopGameSeats';

package/src/features/tabletop/utils/createPokerTrainingTableState.ts

@@ -0,0 +1,152 @@
+import type {
+  CreatePokerTrainingTableStateOptions,
+  PokerTrainingPlayer,
+  PokerTrainingTableSize,
+  PokerTrainingTableState,
+  PokerTrainingTaskTableData,
+  TabletopGameParticipantState,
+} from '../../../types/tabletop';
+import { createTabletopGameSeats } from './createTabletopGameSeats';
+
+/***
+ * Adapts the table-relevant subset of a poker training task to generic tabletop presentation state.
+ *
+ * The canonical poker ring for the task table size is rotated so the hero occupies the first
+ * (bottom) tabletop seat. Players omitted by the task are reconstructed as folded with the
+ * configured default stack.
+ *
+ * Accepts serializable poker training task data plus presentation defaults for omitted fields and
+ * returns seats and shared-table content ready for `TabletopTable`.
+ */
+export function createPokerTrainingTableState(
+  task: PokerTrainingTaskTableData,
+  { defaultStackBigBlinds = 100 }: CreatePokerTrainingTableStateOptions = {},
+): PokerTrainingTableState {
+  const tableSize = task.tableSize ?? '9max';
+  const positions = tableSize === '6max' ? sixMaxPokerPositions : nineMaxPokerPositions;
+  const bigBlind = task.blinds?.big;
+  const heroPosition = task.heroPosition ?? task.players?.find((player) => player.isHero)?.position;
+  const orderedPositions = rotatePokerPositions(positions, heroPosition);
+  const defaultStack = `${formatAmount(defaultStackBigBlinds)} BB`;
+  const participants = (task.players ?? []).map((player) =>
+    createPokerParticipantState(player, task, bigBlind),
+  );
+  const seats = createTabletopGameSeats({
+    seats: orderedPositions.map((position) => ({
+      id: position,
+      defaultState: {
+        label: position,
+        tokenLabel: position === 'BTN' ? 'D' : undefined,
+      },
+    })),
+    participants,
+    missingParticipantState: {
+      disabled: true,
+      muted: true,
+      sublabel: `${defaultStack} · Folded`,
+    },
+  });
+
+  return {
+    seatCount: positions.length,
+    seats,
+    centerCards: task.communityCards ?? [],
+    centerLabel: task.pot === undefined ? undefined : `Pot ${formatAmount(task.pot)}`,
+    centerSublabel:
+      task.blinds === undefined
+        ? undefined
+        : `Blinds ${formatAmount(task.blinds.small)} / ${formatAmount(task.blinds.big)}`,
+    accessibilityLabel: createPokerAccessibilityLabel(tableSize, heroPosition, task),
+  };
+}
+
+const sixMaxPokerPositions = ['BTN', 'SB', 'BB', 'UTG', 'HJ', 'CO'] as const;
+const nineMaxPokerPositions = [
+  'BTN',
+  'SB',
+  'BB',
+  'UTG',
+  'UTG+1',
+  'UTG+2',
+  'MP',
+  'HJ',
+  'CO',
+] as const;
+
+/*** Rotates one canonical poker ring to place the hero at the bottom seat. */
+function rotatePokerPositions(
+  positions: readonly string[],
+  heroPosition: string | undefined,
+): readonly string[] {
+  const heroIndex = positions.findIndex((position) => position === heroPosition);
+  if (heroIndex <= 0) return positions;
+
+  return [...positions.slice(heroIndex), ...positions.slice(0, heroIndex)];
+}
+
+/*** Converts one poker participant record into a generic seat-state override. */
+function createPokerParticipantState(
+  player: PokerTrainingPlayer,
+  task: PokerTrainingTaskTableData,
+  bigBlind: number | undefined,
+): TabletopGameParticipantState {
+  const isHero = player.isHero === true || player.position === task.heroPosition;
+  const cards = player.cards ?? (isHero ? task.heroCards : undefined);
+  const folded = player.folded === true;
+
+  return {
+    seatId: player.position,
+    state: {
+      cards,
+      disabled: folded,
+      faceDownCards: cards === undefined && !folded && !isHero ? 2 : undefined,
+      muted: folded,
+      selected: isHero,
+      sublabel: formatPlayerSublabel(player, bigBlind),
+    },
+  };
+}
+
+/*** Formats stack and optional committed chips as a compact seat sublabel. */
+function formatPlayerSublabel(
+  player: PokerTrainingPlayer,
+  bigBlind: number | undefined,
+): string | undefined {
+  const stack = player.stack === undefined ? undefined : formatChipStack(player.stack, bigBlind);
+  const bet = player.bet === undefined ? undefined : `Bet ${formatChipStack(player.bet, bigBlind)}`;
+  const parts = [stack, bet, player.folded === true ? 'Folded' : undefined].filter(
+    (part): part is string => part !== undefined,
+  );
+
+  return parts.length === 0 ? undefined : parts.join(' · ');
+}
+
+/*** Formats chips as big blinds when a positive blind is known, otherwise as an amount. */
+function formatChipStack(amount: number, bigBlind: number | undefined): string {
+  if (bigBlind !== undefined && bigBlind > 0) {
+    return `${formatAmount(amount / bigBlind)} BB`;
+  }
+
+  return `${formatAmount(amount)} chips`;
+}
+
+/*** Formats a numeric poker amount consistently across native and web runtimes. */
+function formatAmount(amount: number): string {
+  return new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 }).format(amount);
+}
+
+/*** Summarizes the reconstructed table for assistive technologies. */
+function createPokerAccessibilityLabel(
+  tableSize: PokerTrainingTableSize,
+  heroPosition: string | undefined,
+  task: PokerTrainingTaskTableData,
+): string {
+  const parts = [`${tableSize === '6max' ? 'Six' : 'Nine'}-player poker table`];
+  if (heroPosition !== undefined) parts.push(`Hero ${heroPosition}`);
+  if (task.pot !== undefined) parts.push(`Pot ${formatAmount(task.pot)}`);
+  if (task.blinds !== undefined) {
+    parts.push(`Blinds ${formatAmount(task.blinds.small)} / ${formatAmount(task.blinds.big)}`);
+  }
+
+  return `${parts.join('. ')}.`;
+}