@ankhorage/zora-tabletop 0.1.0 → 0.1.2

package/src/features/game-presentations/adapters/inbound/createPokerTrainingTableState.test.ts

@@ -0,0 +1,130 @@
+import { expect, test } from 'bun:test';
+
+import type { PokerTrainingTaskTableData } from '../../../../types/pokerTraining';
+import { createPokerTrainingTableState } from './createPokerTrainingTableState';
+
+const liveTask: PokerTrainingTaskTableData = {
+  blinds: { small: 50, big: 100 },
+  heroPosition: 'BTN',
+  heroCards: [
+    { rank: 'K', suit: 'hearts' },
+    { rank: 'Q', suit: 'hearts' },
+  ],
+  communityCards: [
+    { rank: 'A', suit: 'clubs' },
+    { rank: '7', suit: 'hearts' },
+    { rank: '2', suit: 'spades' },
+    { rank: 'J', suit: 'diamonds' },
+  ],
+  pot: 1200,
+  players: [
+    { position: 'BB', stack: 10000 },
+    { position: 'BTN', stack: 10000, isHero: true },
+  ],
+};
+
+test('createPokerTrainingTableState reconstructs a sparse task as nine seats', () => {
+  const state = createPokerTrainingTableState(liveTask);
+
+  expect(state.seats).toHaveLength(9);
+  expect(state.seats.map((seat) => seat.id)).toEqual([
+    'BTN',
+    'SB',
+    'BB',
+    'UTG',
+    'UTG+1',
+    'MP',
+    'MP+1',
+    'HJ',
+    'CO',
+  ]);
+  expect(state.seats[0]).toMatchObject({
+    id: 'BTN',
+    cards: liveTask.heroCards,
+    selected: true,
+    sublabel: '100 BB',
+    tokenLabel: 'D',
+  });
+  expect(state.seats[2]).toMatchObject({
+    id: 'BB',
+    faceDownCards: 2,
+    sublabel: '100 BB',
+  });
+  expect(state.seats[1]).toMatchObject({
+    id: 'SB',
+    disabled: true,
+    muted: true,
+    sublabel: '100 BB · Folded',
+  });
+});
+
+test('createPokerTrainingTableState maps shared live task state', () => {
+  const state = createPokerTrainingTableState(liveTask);
+
+  expect(state.centerCards).toEqual(liveTask.communityCards);
+  expect(state.centerLabel).toBe('Pot 1,200');
+  expect(state.centerSublabel).toBe('Blinds 50 / 100');
+  expect(state.accessibilityLabel).toBe(
+    'Nine-player poker table. Hero BTN. Pot 1,200. Blinds 50 / 100.',
+  );
+});
+
+test('createPokerTrainingTableState rotates another hero to the bottom seat', () => {
+  const state = createPokerTrainingTableState({
+    ...liveTask,
+    heroPosition: 'CO',
+    players: [{ position: 'CO', stack: 5000, bet: 250, isHero: true }],
+  });
+
+  expect(state.seats[0]).toMatchObject({
+    id: 'CO',
+    selected: true,
+    sublabel: '50 BB · Bet 2.5 BB',
+  });
+  expect(state.seats.map((seat) => seat.id)).toEqual([
+    'CO',
+    'BTN',
+    'SB',
+    'BB',
+    'UTG',
+    'UTG+1',
+    'MP',
+    'MP+1',
+    'HJ',
+  ]);
+});
+
+test('createPokerTrainingTableState maps folded and visible opponent state', () => {
+  const visibleCards = [
+    { rank: 'A', suit: 'spades' },
+    { rank: 'A', suit: 'diamonds' },
+  ] as const;
+  const state = createPokerTrainingTableState({
+    ...liveTask,
+    players: [
+      { position: 'BB', stack: 9000, bet: 100, folded: true },
+      { position: 'HJ', stack: 8000, cards: visibleCards },
+    ],
+  });
+
+  const foldedSeat = state.seats.find((seat) => seat.id === 'BB');
+
+  expect(foldedSeat).toMatchObject({
+    disabled: true,
+    muted: true,
+    sublabel: '90 BB · Bet 1 BB · Folded',
+  });
+  expect(foldedSeat?.faceDownCards).toBeUndefined();
+  expect(state.seats.find((seat) => seat.id === 'HJ')).toMatchObject({
+    cards: visibleCards,
+    sublabel: '80 BB',
+  });
+});
+
+test('createPokerTrainingTableState uses a configurable folded stack', () => {
+  const state = createPokerTrainingTableState({}, { defaultStackBigBlinds: 75 });
+
+  expect(state.seats[0]?.sublabel).toBe('75 BB · Folded');
+  expect(state.centerLabel).toBeUndefined();
+  expect(state.centerSublabel).toBeUndefined();
+});

package/src/features/game-presentations/adapters/inbound/createPokerTrainingTableState.ts

@@ -0,0 +1,133 @@
+import type { TabletopGameParticipantState } from '../../../../types/gamePresentation';
+import type {
+  CreatePokerTrainingTableStateOptions,
+  PokerTrainingPlayer,
+  PokerTrainingTableState,
+  PokerTrainingTaskTableData,
+} from '../../../../types/pokerTraining';
+import { createTabletopGameSeats } from '../../domain/createTabletopGameSeats';
+
+/***
+ * Adapts the table-relevant subset of a poker training task to generic tabletop presentation state.
+ *
+ * The canonical poker ring 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.
+ *
+ * @param task - Serializable poker training task data received by the generated application.
+ * @param options - Presentation defaults for task fields that are intentionally omitted.
+ * @returns Seats and shared-table content ready for `TabletopTable`.
+ */
+export function createPokerTrainingTableState(
+  task: PokerTrainingTaskTableData,
+  { defaultStackBigBlinds = 100 }: CreatePokerTrainingTableStateOptions = {},
+): PokerTrainingTableState {
+  const bigBlind = task.blinds?.big;
+  const heroPosition = task.heroPosition ?? task.players?.find((player) => player.isHero)?.position;
+  const orderedPositions = rotatePokerPositions(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 {
+    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(heroPosition, task),
+  };
+}
+
+const pokerPositions = ['BTN', 'SB', 'BB', 'UTG', 'UTG+1', 'MP', 'MP+1', 'HJ', 'CO'] as const;
+
+/*** Rotates the canonical nine-seat poker ring to place the hero at the bottom seat. */
+function rotatePokerPositions(heroPosition: string | undefined): readonly string[] {
+  const heroIndex = pokerPositions.findIndex((position) => position === heroPosition);
+  if (heroIndex <= 0) return pokerPositions;
+
+  return [...pokerPositions.slice(heroIndex), ...pokerPositions.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(
+  heroPosition: string | undefined,
+  task: PokerTrainingTaskTableData,
+): string {
+  const parts = ['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('. ')}.`;
+}

package/src/features/game-presentations/adapters/inbound/pokerTrainingTableMeta.ts

@@ -0,0 +1,80 @@
+export const pokerTrainingTableMeta = {
+  name: 'PokerTrainingTable',
+  category: 'pattern',
+  description: 'Reconstructs a complete nine-seat poker table from sparse training task data.',
+  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,
+      },
+      disabled: {
+        label: 'Disabled',
+        value: { type: 'boolean' },
+        acceptsFallback: true,
+        acceptsTransforms: 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;

package/src/features/game-presentations/domain/createTabletopGameSeats.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createTabletopGameSeats } from './createTabletopGameSeats';
+
+describe('createTabletopGameSeats', () => {
+  test('maps current participants without embedding a specific card game', () => {
+    const seats = createTabletopGameSeats({
+      seats: [
+        { id: 'north', defaultState: { label: 'North', tokenLabel: 'Lead' } },
+        { id: 'east', defaultState: { label: 'East' } },
+        { id: 'south', defaultState: { label: 'South' } },
+        { id: 'west', defaultState: { label: 'West' } },
+      ],
+      participants: [
+        {
+          seatId: 'east',
+          state: {
+            cards: [{ rank: '7', suit: 'diamonds' }],
+            sublabel: 'Ready',
+          },
+        },
+      ],
+      missingParticipantState: { disabled: true, muted: true, sublabel: 'Out' },
+    });
+
+    expect(seats).toHaveLength(4);
+    expect(seats[0]).toMatchObject({
+      id: 'north',
+      label: 'North',
+      tokenLabel: 'Lead',
+      disabled: true,
+      muted: true,
+      sublabel: 'Out',
+    });
+    expect(seats[1]).toMatchObject({
+      id: 'east',
+      label: 'East',
+      cards: [{ rank: '7', suit: 'diamonds' }],
+      sublabel: 'Ready',
+    });
+  });
+
+  test('uses the last participant update and ignores seats outside the layout', () => {
+    const seats = createTabletopGameSeats({
+      seats: [{ id: 'one', defaultState: { label: 'One' } }],
+      participants: [
+        { seatId: 'one', state: { sublabel: 'Waiting' } },
+        { seatId: 'unknown', state: { sublabel: 'Ignored' } },
+        { seatId: 'one', state: { sublabel: 'Playing' } },
+      ],
+    });
+
+    expect(seats).toEqual([{ id: 'one', label: 'One', sublabel: 'Playing' }]);
+  });
+});

package/src/features/game-presentations/domain/createTabletopGameSeats.ts

@@ -0,0 +1,43 @@
+import type { TabletopSeatState } from '../../../types';
+import type { CreateTabletopGameSeatsInput } from '../../../types/gamePresentation';
+
+/***
+ * Joins an ordered game layout with the participant states currently present in a scene.
+ *
+ * Missing participants retain their seat definition and receive the configured fallback state,
+ * which lets card games represent folded, eliminated, disconnected, or otherwise inactive seats
+ * without embedding those game rules in the tabletop renderer.
+ *
+ * @param input - Ordered seats, participant overrides, and the fallback for missing participants.
+ * @returns Normalized tabletop seats in the same order as the supplied seat definitions.
+ * @example Generic four-seat game
+ * ```ts
+ * const seats = createTabletopGameSeats({
+ *   seats: [
+ *     { id: 'north', defaultState: { label: 'North' } },
+ *     { id: 'east', defaultState: { label: 'East' } },
+ *   ],
+ *   participants: [{ seatId: 'east', state: { sublabel: 'Ready' } }],
+ *   missingParticipantState: { muted: true },
+ * });
+ * ```
+ */
+export function createTabletopGameSeats({
+  seats,
+  participants,
+  missingParticipantState = { disabled: true, muted: true },
+}: CreateTabletopGameSeatsInput): readonly TabletopSeatState[] {
+  const participantsBySeat = new Map(
+    participants.map((participant) => [participant.seatId, participant] as const),
+  );
+
+  return seats.map((seat) => {
+    const participant = participantsBySeat.get(seat.id);
+
+    return {
+      id: seat.id,
+      ...seat.defaultState,
+      ...(participant === undefined ? missingParticipantState : participant.state),
+    };
+  });
+}

package/src/index.ts

@@ -8,6 +8,10 @@ export type { PlayingCardProps } from './components/playing-card';
 export { PlayingCard } from './components/playing-card';
 export type { TabletopTableProps } from './components/tabletop-table';
 export { TabletopTable } from './components/tabletop-table';
+export { createPokerTrainingTableState } from './features/game-presentations/adapters/inbound/createPokerTrainingTableState';
+export { PokerTrainingTable } from './features/game-presentations/adapters/inbound/PokerTrainingTable';
+export { pokerTrainingTableMeta } from './features/game-presentations/adapters/inbound/pokerTrainingTableMeta';
+export { createTabletopGameSeats } from './features/game-presentations/domain/createTabletopGameSeats';
 export { tabletopTableMeta } from './meta';
 export { ZORA_TABLETOP_COMPONENT_REGISTRY, ZORA_TABLETOP_PLUGIN } from './plugin';
 export { ZORA_PLUGIN_METADATA, ZORA_TABLETOP_COMPONENT_META } from './registry';
@@ -19,3 +23,16 @@ export type {
   TabletopSeatState,
   TabletopShape,
 } from './types';
+export type {
+  CreateTabletopGameSeatsInput,
+  TabletopGameParticipantState,
+  TabletopGameSeatDefinition,
+  TabletopGameSeatPresentation,
+} from './types/gamePresentation';
+export type {
+  CreatePokerTrainingTableStateOptions,
+  PokerTrainingPlayer,
+  PokerTrainingTableProps,
+  PokerTrainingTableState,
+  PokerTrainingTaskTableData,
+} from './types/pokerTraining';

package/src/meta.test.ts

@@ -1,6 +1,9 @@
+import { composeZoraPluginMetadata, ZORA_CORE_PLUGIN_METADATA } from '@ankhorage/zora/metadata';
 import { describe, expect, test } from 'bun:test';
 
+import { pokerTrainingTableMeta } from './features/game-presentations/adapters/inbound/pokerTrainingTableMeta';
 import { tabletopTableMeta } from './meta';
+import { ZORA_PLUGIN_METADATA, ZORA_TABLETOP_COMPONENT_META } from './registry';
 
 describe('ZORA tabletop component metadata', () => {
   test('exposes TabletopTable as a directly authorable manifest node', () => {
@@ -25,4 +28,40 @@ describe('ZORA tabletop component metadata', () => {
     expect(metadataSource).toContain('componentMeta: ZORA_TABLETOP_COMPONENT_META');
     expect(publicSource).toContain('ZORA_TABLETOP_PLUGIN');
   });
+
+  test('exposes PokerTrainingTable task data as one object binding', () => {
+    const taskValue = pokerTrainingTableMeta.bindings.props.task.value;
+
+    expect(taskValue.type).toBe('object');
+    expect(taskValue.fields.map((field) => field.path)).toEqual([
+      'blinds',
+      'heroPosition',
+      'heroCards',
+      'communityCards',
+      'pot',
+      'players',
+    ]);
+  });
+
+  test('registers the poker pattern with matching component metadata', async () => {
+    const source = await Bun.file('src/plugin.ts').text();
+
+    expect(source).toContain('{ PokerTrainingTable, TabletopTable }');
+    expect(Object.keys(ZORA_TABLETOP_COMPONENT_META)).toEqual([
+      'PokerTrainingTable',
+      'TabletopTable',
+    ]);
+  });
+});
+
+describe('ZORA 19 plugin composition', () => {
+  test('uses only declared core extension hosts', () => {
+    expect(() =>
+      composeZoraPluginMetadata([ZORA_CORE_PLUGIN_METADATA, ZORA_PLUGIN_METADATA]),
+    ).not.toThrow();
+    expect(ZORA_PLUGIN_METADATA.placements.map((placement) => placement.parents)).toEqual([
+      ['Card', 'Grid', 'Screen', 'ScreenSection', 'View'],
+      ['Card', 'Grid', 'Screen', 'ScreenSection', 'View'],
+    ]);
+  });
 });

package/src/plugin.ts

@@ -1,7 +1,8 @@
 import { TabletopTable } from './components/tabletop-table';
+import { PokerTrainingTable } from './features/game-presentations/adapters/inbound/PokerTrainingTable';
 import { ZORA_PLUGIN_METADATA } from './registry';
 
-export const ZORA_TABLETOP_COMPONENT_REGISTRY = { TabletopTable } as const;
+export const ZORA_TABLETOP_COMPONENT_REGISTRY = { PokerTrainingTable, TabletopTable } as const;
 
 export const ZORA_TABLETOP_PLUGIN = {
   ...ZORA_PLUGIN_METADATA,

package/src/registry.ts

@@ -1,15 +1,25 @@
+import { pokerTrainingTableMeta } from './features/game-presentations/adapters/inbound/pokerTrainingTableMeta';
 import { tabletopTableMeta } from './meta';
 
-export const ZORA_TABLETOP_COMPONENT_META = { TabletopTable: tabletopTableMeta } as const;
+export const ZORA_TABLETOP_COMPONENT_META = {
+  PokerTrainingTable: pokerTrainingTableMeta,
+  TabletopTable: tabletopTableMeta,
+} as const;
+
+const TABLETOP_PLACEMENT_PARENTS = ['Card', 'Grid', 'Screen', 'ScreenSection', 'View'] as const;
 
 export const ZORA_PLUGIN_METADATA = {
   packageName: '@ankhorage/zora-tabletop',
   displayName: 'ZORA Tabletop',
   componentMeta: ZORA_TABLETOP_COMPONENT_META,
   placements: [
+    {
+      child: 'PokerTrainingTable',
+      parents: TABLETOP_PLACEMENT_PARENTS,
+    },
     {
       child: 'TabletopTable',
-      parents: ['Box', 'Card', 'Container', 'Grid', 'Panel', 'Screen', 'ScreenSection', 'Stack'],
+      parents: TABLETOP_PLACEMENT_PARENTS,
     },
   ],
 } as const;

package/src/types/gamePresentation.ts

@@ -0,0 +1,19 @@
+import type { TabletopSeatState } from '../types';
+
+export type TabletopGameSeatPresentation = Omit<TabletopSeatState, 'id'>;
+
+export interface TabletopGameSeatDefinition {
+  readonly id: string;
+  readonly defaultState: TabletopGameSeatPresentation;
+}
+
+export interface TabletopGameParticipantState {
+  readonly seatId: string;
+  readonly state: Partial<TabletopGameSeatPresentation>;
+}
+
+export interface CreateTabletopGameSeatsInput {
+  readonly seats: readonly TabletopGameSeatDefinition[];
+  readonly participants: readonly TabletopGameParticipantState[];
+  readonly missingParticipantState?: Partial<TabletopGameSeatPresentation>;
+}

package/src/types/pokerTraining.ts

@@ -0,0 +1,51 @@
+import type { TabletopColorOverrides } from '../colors';
+import type {
+  PlayingCardValue,
+  TabletopCardSize,
+  TabletopSeatState,
+  TabletopShape,
+} from '../types';
+
+export interface PokerTrainingPlayer {
+  readonly position: string;
+  readonly stack?: number;
+  readonly bet?: number;
+  readonly cards?: readonly PlayingCardValue[];
+  readonly folded?: boolean;
+  readonly isHero?: boolean;
+}
+
+export interface PokerTrainingTaskTableData {
+  readonly blinds?: {
+    readonly small: number;
+    readonly big: number;
+  };
+  readonly heroPosition?: string;
+  readonly heroCards?: readonly PlayingCardValue[];
+  readonly communityCards?: readonly PlayingCardValue[];
+  readonly pot?: number;
+  readonly players?: readonly PokerTrainingPlayer[];
+}
+
+export interface CreatePokerTrainingTableStateOptions {
+  readonly defaultStackBigBlinds?: number;
+}
+
+export interface PokerTrainingTableState {
+  readonly seats: readonly TabletopSeatState[];
+  readonly centerCards: readonly PlayingCardValue[];
+  readonly centerLabel?: string;
+  readonly centerSublabel?: string;
+  readonly accessibilityLabel: string;
+}
+
+export interface PokerTrainingTableProps {
+  readonly task?: PokerTrainingTaskTableData;
+  readonly defaultStackBigBlinds?: number;
+  readonly shape?: TabletopShape;
+  readonly cardSize?: TabletopCardSize;
+  readonly disabled?: boolean;
+  readonly colorScheme?: TabletopColorOverrides;
+  readonly accessibilityLabel?: string;
+  readonly testID?: string;
+}