@ankhorage/zora 21.0.23 → 21.1.0

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

@@ -0,0 +1,232 @@
+import {
+  getReadableForeground,
+  parseHexColor as parseCanonicalHexColor,
+} from '@ankhorage/color-theory';
+
+import type { TabletopColorOverrides, TabletopColorScheme } from '../../../types/tabletop';
+
+interface TabletopColorThemeShape {
+  semantics: {
+    action: {
+      primary: {
+        base: string;
+        softBg: string;
+      };
+    };
+    content: {
+      default: string;
+      muted: string;
+    };
+    neutral: {
+      border: string;
+      divider: string;
+      surface: string;
+      surfaceHover: string;
+    };
+    warning: {
+      base: string;
+      softBg: string;
+    };
+  };
+}
+
+interface RgbColor {
+  readonly red: number;
+  readonly green: number;
+  readonly blue: number;
+}
+
+const MINIMUM_READABLE_CONTRAST = 4.5;
+
+/***
+ * Creates the theme-derived color palette used by tabletop primitives.
+ *
+ * Use `createTabletopColorScheme` when custom components need to align with the
+ * same card, table, seat, token, and contrast-aware foreground colors as the
+ * built-in tabletop components.
+ *
+ */
+export function createTabletopColorScheme(
+  theme: TabletopColorThemeShape,
+  overrides: TabletopColorOverrides = {},
+): TabletopColorScheme {
+  const cardSurface = overrides.cardSurface ?? theme.semantics.neutral.surface;
+  const seatSurface = overrides.seatSurface ?? theme.semantics.neutral.surface;
+  const tableFelt = overrides.tableFelt ?? theme.semantics.action.primary.softBg;
+  const tokenSurface = overrides.tokenSurface ?? theme.semantics.warning.softBg;
+
+  const cardText =
+    overrides.cardText ??
+    resolveReadableTextColor(
+      cardSurface,
+      theme.semantics.content.default,
+      theme.semantics.content.muted,
+    );
+  const seatText =
+    overrides.seatText ??
+    resolveReadableTextColor(
+      seatSurface,
+      theme.semantics.content.default,
+      theme.semantics.content.muted,
+    );
+  const tableText =
+    overrides.tableText ??
+    resolveReadableTextColor(
+      tableFelt,
+      theme.semantics.content.default,
+      theme.semantics.content.muted,
+    );
+  const tokenText =
+    overrides.tokenText ??
+    resolveReadableTextColor(
+      tokenSurface,
+      theme.semantics.content.default,
+      theme.semantics.content.muted,
+    );
+
+  return {
+    cardBack: overrides.cardBack ?? theme.semantics.warning.base,
+    cardBackBorder: overrides.cardBackBorder ?? theme.semantics.neutral.border,
+    cardBorder: overrides.cardBorder ?? theme.semantics.neutral.border,
+    cardSurface,
+    cardText,
+    mutedText:
+      overrides.mutedText ??
+      resolveReadableTextColor(cardSurface, theme.semantics.content.muted, cardText),
+    redSuitText:
+      overrides.redSuitText ??
+      resolveReadableTextColor(cardSurface, theme.semantics.warning.base, cardText),
+    seatBorder: overrides.seatBorder ?? theme.semantics.neutral.divider,
+    seatMutedText:
+      overrides.seatMutedText ??
+      resolveReadableTextColor(seatSurface, theme.semantics.content.muted, seatText),
+    seatSelectedBorder: overrides.seatSelectedBorder ?? theme.semantics.action.primary.base,
+    seatSurface,
+    seatText,
+    tableBorder: overrides.tableBorder ?? theme.semantics.warning.base,
+    tableFelt,
+    tableInnerBorder: overrides.tableInnerBorder ?? theme.semantics.neutral.divider,
+    tableMutedText:
+      overrides.tableMutedText ??
+      resolveReadableTextColor(tableFelt, theme.semantics.content.muted, tableText),
+    tableText,
+    tokenSurface,
+    tokenText,
+  };
+}
+
+/*** Chooses the most legible supplied foreground for a themed surface. */
+function resolveReadableTextColor(background: string, preferred: string, fallback: string): string {
+  const preferredContrast = getContrastRatio(background, preferred);
+  if (preferredContrast !== null && preferredContrast >= MINIMUM_READABLE_CONTRAST) {
+    return preferred;
+  }
+
+  const parsedBackground = parseHexColor(background);
+  const normalizedBackground =
+    parsedBackground === null ? null : parseCanonicalHexColor(toHexColor(parsedBackground));
+  const strongestForeground =
+    normalizedBackground === null
+      ? undefined
+      : getReadableForeground(normalizedBackground).foreground;
+  const candidates = uniqueColors([
+    preferred,
+    fallback,
+    ...(strongestForeground === undefined ? [] : [strongestForeground]),
+  ]);
+  const [readableCandidate] = candidates
+    .map((candidate) => ({ candidate, contrast: getContrastRatio(background, candidate) }))
+    .filter(
+      (entry): entry is { readonly candidate: string; readonly contrast: number } =>
+        entry.contrast !== null,
+    )
+    .sort((left, right) => right.contrast - left.contrast);
+
+  return readableCandidate?.candidate ?? preferred;
+}
+
+/*** Converts a parsed color to Color Theory's canonical six-digit input. */
+function toHexColor(color: RgbColor): string {
+  return `#${[color.red, color.green, color.blue].map((channel) => channel.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/*** Removes duplicate contrast candidates without changing their order. */
+function uniqueColors(colors: readonly string[]): string[] {
+  return [...new Set(colors)];
+}
+
+/*** Measures contrast when both colors can be parsed as hex. */
+function getContrastRatio(background: string, foreground: string): number | null {
+  const backgroundColor = parseHexColor(background);
+  const foregroundColor = parseHexColor(foreground);
+
+  if (backgroundColor === null || foregroundColor === null) return null;
+
+  const backgroundLuminance = getRelativeLuminance(backgroundColor);
+  const foregroundLuminance = getRelativeLuminance(foregroundColor);
+  const lighter = Math.max(backgroundLuminance, foregroundLuminance);
+  const darker = Math.min(backgroundLuminance, foregroundLuminance);
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/*** Parses the hex colors supported by the tabletop palette. */
+function parseHexColor(color: string): RgbColor | null {
+  const value = color.trim();
+  const hex = value.startsWith('#') ? value.slice(1) : '';
+  if (!isSupportedHexLength(hex) || !isHexColorValue(hex)) return null;
+
+  if (hex.length === 3) {
+    const red = hex.slice(0, 1);
+    const green = hex.slice(1, 2);
+    const blue = hex.slice(2, 3);
+
+    return {
+      red: parseInt(red + red, 16),
+      green: parseInt(green + green, 16),
+      blue: parseInt(blue + blue, 16),
+    };
+  }
+
+  return {
+    red: parseInt(hex.slice(0, 2), 16),
+    green: parseInt(hex.slice(2, 4), 16),
+    blue: parseInt(hex.slice(4, 6), 16),
+  };
+}
+
+/*** Checks the supported short, full, and alpha hex lengths. */
+function isSupportedHexLength(hex: string): boolean {
+  return hex.length === 3 || hex.length === 6 || hex.length === 8;
+}
+
+/*** Rejects non-hexadecimal color digits. */
+function isHexColorValue(hex: string): boolean {
+  return [...hex].every((character) => isHexCharacter(character));
+}
+
+/*** Checks whether a character is a hexadecimal digit. */
+function isHexCharacter(character: string): boolean {
+  const code = character.charCodeAt(0);
+  const isDigit = code >= 48 && code <= 57;
+  const isUpperHex = code >= 65 && code <= 70;
+  const isLowerHex = code >= 97 && code <= 102;
+
+  return isDigit || isUpperHex || isLowerHex;
+}
+
+/*** Computes relative luminance for one RGB color. */
+function getRelativeLuminance(color: RgbColor): number {
+  const red = normalizeColorChannel(color.red);
+  const green = normalizeColorChannel(color.green);
+  const blue = normalizeColorChannel(color.blue);
+
+  return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+}
+
+/*** Converts an RGB channel into linear light. */
+function normalizeColorChannel(value: number): number {
+  const normalized = value / 255;
+  if (normalized <= 0.03928) return normalized / 12.92;
+  return ((normalized + 0.055) / 1.055) ** 2.4;
+}

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

@@ -0,0 +1,31 @@
+import type { CreateTabletopGameSeatsInput, TabletopSeatState } from '../../../types/tabletop';
+
+/***
+ * 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.
+ *
+ * Accepts ordered seats, participant overrides, and the fallback for missing participants, then
+ * returns normalized tabletop seats in the same order as the supplied seat definitions.
+ */
+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/features/tabletop/utils/getPlayingCardLabel.ts

@@ -0,0 +1,8 @@
+import type { PlayingCardValue } from '../../../types/tabletop';
+
+const rankLabels: Readonly<Record<string, string>> = { A: 'ace', J: 'jack', K: 'king', Q: 'queen' };
+
+/*** Gives a face-up card a spoken rank and suit. */
+export function getPlayingCardLabel(card: PlayingCardValue): string {
+  return `${rankLabels[card.rank] ?? card.rank} of ${card.suit}`;
+}

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

@@ -0,0 +1,45 @@
+import type { TabletopCardSize } from '../../../types/tabletop';
+
+interface TabletopCardDimensions {
+  readonly width: number;
+  readonly height: number;
+  readonly radius: number;
+  readonly rankFontSize: number;
+  readonly suitFontSize: number;
+}
+
+const cardDimensions: Readonly<Record<TabletopCardSize, TabletopCardDimensions>> = {
+  large: {
+    width: 56,
+    height: 80,
+    radius: 8,
+    rankFontSize: 20,
+    suitFontSize: 16,
+  },
+  medium: {
+    width: 40,
+    height: 56,
+    radius: 6,
+    rankFontSize: 15,
+    suitFontSize: 12,
+  },
+  small: {
+    width: 28,
+    height: 40,
+    radius: 5,
+    rankFontSize: 11,
+    suitFontSize: 9,
+  },
+};
+
+/*** Returns the published dimensions for a tabletop card size. */
+export function getTabletopCardDimensions(size: TabletopCardSize): TabletopCardDimensions {
+  switch (size) {
+    case 'small':
+      return cardDimensions.small;
+    case 'large':
+      return cardDimensions.large;
+    case 'medium':
+      return cardDimensions.medium;
+  }
+}

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

@@ -0,0 +1,100 @@
+import type { TabletopSeatCount } from '../../../types/tabletop';
+
+type TabletopSeatPositionValue = `${number}%`;
+
+interface TabletopSeatPosition {
+  readonly top: TabletopSeatPositionValue;
+  readonly left: TabletopSeatPositionValue;
+}
+
+const fallbackSeatPosition: TabletopSeatPosition = { top: '82%', left: '50%' };
+
+const seatPositions: Readonly<Record<TabletopSeatCount, readonly TabletopSeatPosition[]>> = {
+  2: [fallbackSeatPosition, { top: '18%', left: '50%' }],
+  3: [fallbackSeatPosition, { top: '28%', left: '18%' }, { top: '28%', left: '82%' }],
+  4: [
+    fallbackSeatPosition,
+    { top: '50%', left: '12%' },
+    { top: '18%', left: '50%' },
+    { top: '50%', left: '88%' },
+  ],
+  5: [
+    { top: '84%', left: '50%' },
+    { top: '62%', left: '12%' },
+    { top: '18%', left: '24%' },
+    { top: '18%', left: '76%' },
+    { top: '62%', left: '88%' },
+  ],
+  6: [
+    { top: '84%', left: '50%' },
+    { top: '68%', left: '16%' },
+    { top: '26%', left: '16%' },
+    { top: '16%', left: '50%' },
+    { top: '26%', left: '84%' },
+    { top: '68%', left: '84%' },
+  ],
+  7: [
+    { top: '86%', left: '50%' },
+    { top: '70%', left: '14%' },
+    { top: '34%', left: '10%' },
+    { top: '14%', left: '34%' },
+    { top: '14%', left: '66%' },
+    { top: '34%', left: '90%' },
+    { top: '70%', left: '86%' },
+  ],
+  8: [
+    { top: '86%', left: '50%' },
+    { top: '72%', left: '16%' },
+    { top: '50%', left: '8%' },
+    { top: '20%', left: '20%' },
+    { top: '14%', left: '50%' },
+    { top: '20%', left: '80%' },
+    { top: '50%', left: '92%' },
+    { top: '72%', left: '84%' },
+  ],
+  9: [
+    { top: '88%', left: '50%' },
+    { top: '78%', left: '12%' },
+    { top: '50%', left: '4%' },
+    { top: '18%', left: '10%' },
+    { top: '8%', left: '28%' },
+    { top: '8%', left: '50%' },
+    { top: '8%', left: '72%' },
+    { top: '18%', left: '90%' },
+    { top: '50%', left: '96%' },
+  ],
+  10: [
+    { top: '88%', left: '50%' },
+    { top: '80%', left: '20%' },
+    { top: '58%', left: '6%' },
+    { top: '30%', left: '8%' },
+    { top: '10%', left: '30%' },
+    { top: '8%', left: '50%' },
+    { top: '10%', left: '70%' },
+    { top: '30%', left: '92%' },
+    { top: '58%', left: '94%' },
+    { top: '80%', left: '80%' },
+  ],
+};
+
+/*** Clamps the requested tabletop seat count to a supported ring. */
+function normalizeTabletopSeatCount(count: number): TabletopSeatCount {
+  const rounded = Math.round(count);
+  if (rounded <= 2) return 2;
+  if (rounded >= 10) return 10;
+
+  return rounded as TabletopSeatCount;
+}
+
+/*** Returns the canonical seat positions for a ring size. */
+function getTabletopSeatPositions(count: number): readonly TabletopSeatPosition[] {
+  return seatPositions[normalizeTabletopSeatCount(count)];
+}
+
+/*** Returns a seat's canonical position with the hero at the bottom. */
+export function getTabletopSeatPosition(index: number, count: number): TabletopSeatPosition {
+  const positions = getTabletopSeatPositions(count);
+  const position = positions[index % positions.length];
+
+  return position ?? fallbackSeatPosition;
+}

package/src/index.ts

@@ -125,6 +125,34 @@ export type {
   MessageBubbleStatus,
 } from './features/chat/public';
 export { ChatListItem, MessageBubble } from './features/chat/public';
+export type {
+  ChessBoardColorOverrides,
+  ChessBoardColorScheme,
+  ChessBoardOrientation,
+  ChessBoardProps,
+  ChessMoveAttempt,
+  ChessPieceCode,
+  ChessPieceRenderContext,
+  ChessPieceRenderer,
+  ChessPieceState,
+  ChessPromotionPiece,
+  ChessSquareId,
+  OpeningBookColorOverrides,
+  OpeningBookColorScheme,
+  OpeningBookMove,
+  OpeningBookProps,
+} from './features/chess/public';
+export type { ChessColorThemeShape } from './features/chess/public';
+export { ChessBoard, OpeningBook } from './features/chess/public';
+export {
+  chessSquares,
+  createBoardSquares,
+  createChessBoardColorScheme,
+  createOpeningBookColorScheme,
+  getSquareFile,
+  getSquareRank,
+  isLightSquare,
+} from './features/chess/public';
 export type { ChipProps } from './features/chip/public';
 export type { ChipGroupItem, ChipGroupProps } from './features/chip/public';
 export { Chip } from './features/chip/public';
@@ -214,6 +242,27 @@ export {
   type TextInputProps,
   type TextInputTrailingAction,
 } from './features/form/text-input/public';
+export type {
+  GameEntityEasing,
+  GameEntityMotionProps,
+  GameEntityProps,
+  GameFieldProps,
+  GameInputZoneProps,
+  GameKeyboardBinding,
+  GameMeasurementProbeProps,
+  GameOverlayPlacement,
+  GameOverlayProps,
+  GamePointerEvents,
+  GameProps,
+} from './features/game/public';
+export {
+  Game,
+  GameEntity,
+  GameField,
+  GameInputZone,
+  GameMeasurementProbe,
+  GameOverlay,
+} from './features/game/public';
 export type {
   GradientColor,
   GradientColors,
@@ -342,6 +391,40 @@ export {
 } from './features/skeleton/public';
 export type { SurfaceProps, SurfaceVariant } from './features/surface/public';
 export { Surface } from './features/surface/public';
+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 './features/tabletop/public';
+export {
+  CardBack,
+  CardHand,
+  createPokerTrainingTableState,
+  createTabletopColorScheme,
+  createTabletopGameSeats,
+  PlayingCard,
+  PokerTrainingTable,
+  TabletopTable,
+} from './features/tabletop/public';
 export {
   Tab,
   TabList,

package/src/types/chess.ts

@@ -0,0 +1,95 @@
+import type React from 'react';
+
+import type { ZoraBaseProps } from './base';
+
+export type ChessBoardOrientation = 'white' | 'black';
+export type ChessPieceCode = string;
+export type ChessSquareId =
+  `${'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h'}${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}`;
+export type ChessPromotionPiece = 'q' | 'r' | 'b' | 'n';
+
+export interface ChessMoveAttempt {
+  readonly from: ChessSquareId;
+  readonly to: ChessSquareId;
+  readonly promotion?: ChessPromotionPiece;
+}
+
+export interface ChessPieceState {
+  readonly color: 'black' | 'white';
+  readonly piece: ChessPieceCode;
+  readonly square: ChessSquareId;
+}
+
+export interface ChessPieceRenderContext {
+  readonly color: string;
+  readonly piece: ChessPieceCode;
+  readonly square: ChessSquareId;
+}
+
+export type ChessPieceRenderer = (context: ChessPieceRenderContext) => React.ReactNode;
+
+export interface ChessBoardColorScheme {
+  readonly lightSquare: string;
+  readonly darkSquare: string;
+  readonly lightSquareText: string;
+  readonly darkSquareText: string;
+  readonly selectedSquare: string;
+  readonly legalTarget: string;
+  readonly lastMoveFrom: string;
+  readonly lastMoveTo: string;
+  readonly border: string;
+  readonly coordinateText: string;
+  readonly lightPiece: string;
+  readonly darkPiece: string;
+}
+
+export type ChessBoardColorOverrides = Partial<ChessBoardColorScheme>;
+
+export interface OpeningBookColorScheme {
+  readonly border: string;
+  readonly surface: string;
+  readonly surfaceHover: string;
+  readonly selectedSurface: string;
+  readonly titleText: string;
+  readonly primaryText: string;
+  readonly secondaryText: string;
+  readonly metricSurface: string;
+}
+export type OpeningBookColorOverrides = Partial<OpeningBookColorScheme>;
+
+export interface ChessBoardProps extends ZoraBaseProps {
+  readonly pieces?: readonly ChessPieceState[];
+  readonly orientation?: ChessBoardOrientation;
+  readonly selectedSquare?: ChessSquareId | null;
+  readonly legalTargets?: readonly ChessSquareId[];
+  readonly lastMove?: ChessMoveAttempt | null;
+  readonly disabled?: boolean;
+  readonly showCoordinates?: boolean;
+  readonly colorScheme?: ChessBoardColorOverrides;
+  readonly onSquarePress?: (square: ChessSquareId) => void;
+  readonly onMoveAttempt?: (move: ChessMoveAttempt) => void;
+  readonly renderPiece?: ChessPieceRenderer;
+}
+
+export interface OpeningBookMove {
+  readonly san: string;
+  readonly uci?: string;
+  readonly fen?: string;
+  readonly name?: string;
+  readonly eco?: string;
+  readonly games?: number;
+  readonly whiteWinRate?: number;
+  readonly drawRate?: number;
+  readonly blackWinRate?: number;
+}
+
+export interface OpeningBookProps extends ZoraBaseProps {
+  readonly moves?: readonly OpeningBookMove[];
+  readonly title?: string;
+  readonly loading?: boolean;
+  readonly errorText?: string;
+  readonly emptyText?: string;
+  readonly selectedMove?: string | null;
+  readonly colorScheme?: OpeningBookColorOverrides;
+  readonly onMovePress?: (move: OpeningBookMove) => void;
+}