@ankhorage/zora-tabletop 0.0.9 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora-tabletop",
   "type": "module",
-  "version": "0.0.9",
+  "version": "0.1.1",
   "description": "Tabletop and card-game UI primitives for React Native and React Native Web, built on ZORA.",
   "homepage": "https://github.com/ankhorage/zora-tabletop#readme",
   "bugs": {
@@ -41,6 +41,13 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./metadata": {
+      "react-native": "./src/registry.ts",
+      "browser": "./src/registry.ts",
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js",
+      "default": "./dist/registry.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -62,14 +69,14 @@
     "knip:check": "ankhorage-knip"
   },
   "peerDependencies": {
-    "@ankhorage/zora": ">=4.2.0",
+    "@ankhorage/zora": ">=4.2.2",
     "react": ">=18.2.0",
     "react-native": ">=0.72.0"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.11.0",
+    "@ankhorage/devtools": "^1.11.11",
     "@ankhorage/paradox": "^0.1.24",
-    "@ankhorage/zora": "^4.2.0",
+    "@ankhorage/zora": "^4.2.2",
     "@react-native-picker/picker": "2.11.4",
     "@react-native-vector-icons/fontawesome": "^13.1.3",
     "@react-native-vector-icons/fontawesome5": "^13.1.3",
@@ -86,5 +93,5 @@
     "react-native-web": "~0.21.0",
     "typescript": "~6.0.3"
   },
-  "packageManager": "bun@1.4.1"
+  "packageManager": "bun@1.4.2"
 }

package/src/features/game-presentations/adapters/inbound/PokerTrainingTable.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+
+import { TabletopTable } from '../../../../components/tabletop-table';
+import type { PokerTrainingTableProps } from '../../../../types/pokerTraining';
+import { createPokerTrainingTableState } from './createPokerTrainingTableState';
+
+/***
+ * Manifest-ready poker training pattern that reconstructs a complete table from task data.
+ *
+ * Bind the raw training task object to `task`; the pattern maps sparse active-player data to a
+ * full nine-seat presentation while leaving API execution in the generated application.
+ *
+ * @readme
+ * @example Training task binding
+ * ```tsx
+ * <PokerTrainingTable task={task} />
+ * ```
+ */
+export function PokerTrainingTable({
+  task = {},
+  defaultStackBigBlinds = 100,
+  accessibilityLabel,
+  ...tableProps
+}: PokerTrainingTableProps) {
+  const state = React.useMemo(
+    () => createPokerTrainingTableState(task, { defaultStackBigBlinds }),
+    [defaultStackBigBlinds, task],
+  );
+
+  return (
+    <TabletopTable
+      {...tableProps}
+      accessibilityLabel={accessibilityLabel ?? state.accessibilityLabel}
+      centerCards={state.centerCards}
+      centerLabel={state.centerLabel}
+      centerSublabel={state.centerSublabel}
+      seatCount={9}
+      seats={state.seats}
+    />
+  );
+}

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,13 @@ 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';
 export type {
   PlayingCardSuit,
   PlayingCardValue,
@@ -16,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

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'bun:test';
+
+import { pokerTrainingTableMeta } from './features/game-presentations/adapters/inbound/pokerTrainingTableMeta';
+import { tabletopTableMeta } from './meta';
+import { ZORA_TABLETOP_COMPONENT_META } from './registry';
+
+describe('ZORA tabletop component metadata', () => {
+  test('exposes TabletopTable as a directly authorable manifest node', () => {
+    expect(tabletopTableMeta.directManifestNode).toBe(true);
+    expect(tabletopTableMeta.blueprint.defaultProps).toMatchObject({
+      seats: [],
+      shape: 'oval',
+    });
+    expect(tabletopTableMeta.bindings.props.seats.value).toEqual({
+      type: 'array',
+      itemType: 'object',
+    });
+  });
+
+  test('exports one canonical plugin descriptor from the public API', async () => {
+    const source = await Bun.file('src/plugin.ts').text();
+    const metadataSource = await Bun.file('src/registry.ts').text();
+    const publicSource = await Bun.file('src/index.ts').text();
+
+    expect(metadataSource).toContain("packageName: '@ankhorage/zora-tabletop'");
+    expect(source).toContain('componentRegistry: ZORA_TABLETOP_COMPONENT_REGISTRY');
+    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',
+    ]);
+  });
+});