@ankhorage/zora 21.0.23 → 21.1.0

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

@@ -0,0 +1,64 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import type { ZoraProvider as ZoraProviderComponent } from '../theme/runtime';
+import type { GameEntity as GameEntityComponent, GameField as GameFieldComponent } from './public';
+
+const webDistRoot = join(import.meta.dir, '../../../web-dist');
+
+test('generic web materialization renders Game field and entity without a plugin catalog', async () => {
+  const manifest: unknown = await Bun.file(join(webDistRoot, 'manifest.json')).json();
+  if (
+    typeof manifest !== 'object' ||
+    manifest === null ||
+    !('artifacts' in manifest) ||
+    !Array.isArray(manifest.artifacts)
+  ) {
+    throw new Error('Expected a generated web artifact catalog.');
+  }
+  const artifactNames = Object.values(manifest.artifacts as readonly unknown[])
+    .filter(
+      (artifact) => typeof artifact === 'object' && artifact !== null && 'exportName' in artifact,
+    )
+    .map((artifact) => artifact.exportName);
+  const exports = new Set(artifactNames);
+  for (const name of [
+    'Game',
+    'GameField',
+    'GameEntity',
+    'GameInputZone',
+    'GameMeasurementProbe',
+    'GameOverlay',
+  ]) {
+    expect(exports.has(name), name).toBe(true);
+  }
+
+  const { GameField } = (await import(
+    pathToFileURL(join(webDistRoot, 'components/game-field/index.js')).href
+  )) as { GameField: typeof GameFieldComponent };
+  const { GameEntity } = (await import(
+    pathToFileURL(join(webDistRoot, 'components/game-entity/index.js')).href
+  )) as { GameEntity: typeof GameEntityComponent };
+  const { ZoraProvider } = (await import(
+    pathToFileURL(join(webDistRoot, 'runtime/ZoraProvider.js')).href
+  )) as { ZoraProvider: typeof ZoraProviderComponent };
+  const browser = new Window();
+  browser.document.body.innerHTML = renderToStaticMarkup(
+    <ZoraProvider mode="light">
+      <GameField testID="field">
+        <GameEntity x={25} y={40} testID="entity" />
+      </GameField>
+    </ZoraProvider>,
+  );
+  expect(browser.document.querySelector('[data-testid="field"]')).not.toBeNull();
+  expect(browser.document.querySelector('[data-testid="field"]')?.getAttribute('style')).toContain(
+    'min-height:320px',
+  );
+  expect(browser.document.querySelector('[data-testid="entity"]')).not.toBeNull();
+  browser.close();
+});

package/src/features/game/public.ts

@@ -0,0 +1,19 @@
+export type {
+  GameEntityEasing,
+  GameEntityMotionProps,
+  GameEntityProps,
+  GameFieldProps,
+  GameInputZoneProps,
+  GameKeyboardBinding,
+  GameMeasurementProbeProps,
+  GameOverlayPlacement,
+  GameOverlayProps,
+  GamePointerEvents,
+  GameProps,
+} from '../../types/gamePresentation';
+export { Game } from './adapters/inbound/Game';
+export { GameEntity } from './adapters/inbound/GameEntity';
+export { GameField } from './adapters/inbound/GameField';
+export { GameInputZone } from './adapters/inbound/GameInputZone';
+export { GameMeasurementProbe } from './adapters/inbound/GameMeasurementProbe';
+export { GameOverlay } from './adapters/inbound/GameOverlay';

package/src/features/game/utils/clampGamePercentage.ts

@@ -0,0 +1,4 @@
+/*** Clamp one game presentation coordinate to the inclusive field-percentage range. */
+export function clampGamePercentage(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}

package/src/features/game/utils/resolveGameEntityMotionPlan.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveGameEntityMotionPlan } from './resolveGameEntityMotionPlan';
+
+describe('resolveGameEntityMotionPlan configuration', () => {
+  test('preserves explicit transition and repeating alternate motion', () => {
+    expect(
+      resolveGameEntityMotionPlan(
+        {
+          transitionDurationMs: 70,
+          transitionEasing: 'ease-out',
+          motionOffsetY: 8,
+          motionDurationMs: 1200,
+          motionDelayMs: 100,
+          motionEasing: 'ease-in-out',
+          motionRepeat: true,
+          motionAlternate: true,
+        },
+        false,
+      ),
+    ).toEqual({
+      transitionDurationMs: 70,
+      transitionEasing: 'ease-out',
+      motionDurationMs: 1200,
+      motionDelayMs: 100,
+      motionEasing: 'ease-in-out',
+      motionEnabled: true,
+      motionRepeat: true,
+      motionAlternate: true,
+      motionPaused: false,
+    });
+  });
+
+  test('uses alternate only for repeating motion', () => {
+    expect(
+      resolveGameEntityMotionPlan(
+        { motionOffsetY: 5, motionDurationMs: 100, motionAlternate: true },
+        false,
+      ).motionAlternate,
+    ).toBe(false);
+  });
+});
+
+describe('resolveGameEntityMotionPlan reduced motion', () => {
+  test('disables decorative motion and transitions', () => {
+    const plan = resolveGameEntityMotionPlan(
+      { transitionDurationMs: 80, motionOffsetX: 12, motionDurationMs: 500 },
+      true,
+    );
+
+    expect(plan.transitionDurationMs).toBe(0);
+    expect(plan.motionEnabled).toBe(false);
+  });
+
+  test('keeps essential trajectories enabled', () => {
+    const plan = resolveGameEntityMotionPlan(
+      { motionOffsetY: 70, motionDurationMs: 600, motionEssential: true },
+      true,
+    );
+
+    expect(plan.motionEnabled).toBe(true);
+  });
+});

package/src/features/game/utils/resolveGameEntityMotionPlan.ts

@@ -0,0 +1,53 @@
+import type { GameEntityEasing, GameEntityMotionProps } from '../../../types/gamePresentation';
+
+export interface GameEntityMotionPlan {
+  readonly transitionDurationMs: number;
+  readonly transitionEasing: GameEntityEasing;
+  readonly motionDurationMs: number;
+  readonly motionDelayMs: number;
+  readonly motionEasing: GameEntityEasing;
+  readonly motionEnabled: boolean;
+  readonly motionRepeat: boolean;
+  readonly motionAlternate: boolean;
+  readonly motionPaused: boolean;
+}
+
+/*** Normalize serializable GameEntity motion props against the current reduced-motion preference. */
+export function resolveGameEntityMotionPlan(
+  props: GameEntityMotionProps,
+  reduceMotion: boolean,
+): GameEntityMotionPlan {
+  const essential = props.motionEssential === true;
+  const motionEnabled =
+    hasMotionOffset(props) &&
+    normalizeDuration(props.motionDurationMs) > 0 &&
+    (!reduceMotion || essential);
+
+  return {
+    transitionDurationMs: reduceMotion ? 0 : normalizeDuration(props.transitionDurationMs),
+    transitionEasing: props.transitionEasing ?? 'linear',
+    motionDurationMs: normalizeDuration(props.motionDurationMs),
+    motionDelayMs: normalizeDuration(props.motionDelayMs),
+    motionEasing: props.motionEasing ?? 'linear',
+    motionEnabled,
+    motionRepeat: props.motionRepeat === true,
+    motionAlternate: props.motionRepeat === true && props.motionAlternate === true,
+    motionPaused: props.motionPaused === true,
+  };
+}
+
+/*** Return whether any relative presentation offset requires a motion timeline. */
+function hasMotionOffset(props: GameEntityMotionProps): boolean {
+  return (
+    (props.motionOffsetX ?? 0) !== 0 ||
+    (props.motionOffsetY ?? 0) !== 0 ||
+    (props.motionOpacityDelta ?? 0) !== 0 ||
+    (props.motionScaleDelta ?? 0) !== 0 ||
+    (props.motionRotationDelta ?? 0) !== 0
+  );
+}
+
+/*** Clamp an optional duration to a finite non-negative millisecond value. */
+function normalizeDuration(value: number | undefined): number {
+  return value === undefined || !Number.isFinite(value) ? 0 : Math.max(0, value);
+}

package/src/features/game/utils/toGamePercentage.ts

@@ -0,0 +1,6 @@
+import { clampGamePercentage } from './clampGamePercentage';
+
+/*** Convert one game percentage coordinate to React Native percentage style syntax. */
+export function toGamePercentage(value: number): `${number}%` {
+  return `${clampGamePercentage(value)}%`;
+}

package/src/features/game/utils/useAnimatedGameEntityValue.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { Animated, Easing } from 'react-native';
+
+import type { GameEntityEasing } from '../../../types/gamePresentation';
+
+/*** Animate one bound numeric GameEntity presentation value toward its latest session-driven target. */
+export function useAnimatedGameEntityValue(
+  target: number,
+  durationMs: number,
+  easing: GameEntityEasing,
+): Animated.Value {
+  const [value] = React.useState(() => new Animated.Value(target));
+
+  React.useEffect(() => {
+    value.stopAnimation();
+
+    if (durationMs === 0) {
+      value.setValue(target);
+      return undefined;
+    }
+
+    const animation = Animated.timing(value, {
+      toValue: target,
+      duration: durationMs,
+      easing: resolveGameEntityEasing(easing),
+      useNativeDriver: false,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [durationMs, easing, target, value]);
+
+  return value;
+}
+
+/*** Map serializable easing names onto React Native easing functions. */
+function resolveGameEntityEasing(easing: GameEntityEasing) {
+  if (easing === 'ease-in') return Easing.in(Easing.ease);
+  if (easing === 'ease-out') return Easing.out(Easing.ease);
+  if (easing === 'ease-in-out') return Easing.inOut(Easing.ease);
+  return Easing.linear;
+}

package/src/features/game/utils/useGameEntityAnimatedStyle.ts

@@ -0,0 +1,87 @@
+import { Animated } from 'react-native';
+
+import type { GameEntityProps } from '../../../types/gamePresentation';
+import { resolveGameEntityMotionPlan } from './resolveGameEntityMotionPlan';
+import { useAnimatedGameEntityValue } from './useAnimatedGameEntityValue';
+import { useGameEntityMotionProgress } from './useGameEntityMotionProgress';
+import { useGameReducedMotion } from './useGameReducedMotion';
+
+interface GameEntityAnimatedValues {
+  readonly x: Animated.Value;
+  readonly y: Animated.Value;
+  readonly opacity: Animated.Value;
+  readonly scale: Animated.Value;
+  readonly rotation: Animated.Value;
+  readonly progress: Animated.Value;
+}
+
+/*** Compose bound GameEntity values with optional relative presentation motion. */
+export function useGameEntityAnimatedStyle(input: GameEntityProps) {
+  const reduceMotion = useGameReducedMotion();
+  const plan = resolveGameEntityMotionPlan(input, reduceMotion);
+  const values: GameEntityAnimatedValues = {
+    x: useAnimatedGameEntityValue(input.x ?? 0, plan.transitionDurationMs, plan.transitionEasing),
+    y: useAnimatedGameEntityValue(input.y ?? 0, plan.transitionDurationMs, plan.transitionEasing),
+    opacity: useAnimatedGameEntityValue(
+      input.opacity ?? 1,
+      plan.transitionDurationMs,
+      plan.transitionEasing,
+    ),
+    scale: useAnimatedGameEntityValue(
+      input.scale ?? 1,
+      plan.transitionDurationMs,
+      plan.transitionEasing,
+    ),
+    rotation: useAnimatedGameEntityValue(
+      input.rotation ?? 0,
+      plan.transitionDurationMs,
+      plan.transitionEasing,
+    ),
+    progress: useGameEntityMotionProgress(plan),
+  };
+
+  return createGameEntityAnimatedStyle(values, input);
+}
+
+/*** Build one animated React Native style from base values and relative motion progress. */
+function createGameEntityAnimatedStyle(values: GameEntityAnimatedValues, input: GameEntityProps) {
+  const left = Animated.add(values.x, Animated.multiply(values.progress, input.motionOffsetX ?? 0));
+  const top = Animated.add(values.y, Animated.multiply(values.progress, input.motionOffsetY ?? 0));
+  const opacity = Animated.add(
+    values.opacity,
+    Animated.multiply(values.progress, input.motionOpacityDelta ?? 0),
+  );
+  const scale = Animated.add(
+    values.scale,
+    Animated.multiply(values.progress, input.motionScaleDelta ?? 0),
+  );
+  const rotation = Animated.add(
+    values.rotation,
+    Animated.multiply(values.progress, input.motionRotationDelta ?? 0),
+  );
+
+  return {
+    left: left.interpolate({
+      inputRange: [-10_000, 10_000],
+      outputRange: ['-10000%', '10000%'],
+    }),
+    top: top.interpolate({
+      inputRange: [-10_000, 10_000],
+      outputRange: ['-10000%', '10000%'],
+    }),
+    opacity: opacity.interpolate({
+      inputRange: [0, 1],
+      outputRange: [0, 1],
+      extrapolate: 'clamp',
+    }),
+    transform: [
+      { scale },
+      {
+        rotate: rotation.interpolate({
+          inputRange: [-36_000, 36_000],
+          outputRange: ['-36000deg', '36000deg'],
+        }),
+      },
+    ],
+  };
+}

package/src/features/game/utils/useGameEntityMeasurement.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import type { View } from 'react-native';
+
+import { measureGameEntity } from '../adapters/inbound/measureGameEntity';
+import { GameRuntimeContext } from '../composition/GameRuntimeContext';
+
+/*** Register one optional measurable GameEntity view inside its local Game scope. */
+export function useGameEntityMeasurement(
+  elementRef: React.RefObject<View | null>,
+  measurementId: string | undefined,
+): void {
+  const runtime = React.useContext(GameRuntimeContext);
+  const registerMeasurement = runtime?.registerMeasurement;
+
+  React.useEffect(() => {
+    if (measurementId === undefined || registerMeasurement === undefined) return undefined;
+    return registerMeasurement(measurementId, () => measureGameEntity(elementRef.current));
+  }, [elementRef, measurementId, registerMeasurement]);
+}

package/src/features/game/utils/useGameEntityMotionProgress.ts

@@ -0,0 +1,114 @@
+import React from 'react';
+import { Animated, Easing } from 'react-native';
+
+import type { GameEntityEasing } from '../../../types/gamePresentation';
+import type { GameEntityMotionPlan } from './resolveGameEntityMotionPlan';
+
+interface MotionAnimationInput {
+  readonly durationMs: number;
+  readonly delayMs: number;
+  readonly easing: GameEntityEasing;
+  readonly repeat: boolean;
+  readonly alternate: boolean;
+}
+
+/*** Drive one optional relative GameEntity motion timeline without changing game-session state. */
+export function useGameEntityMotionProgress(plan: GameEntityMotionPlan): Animated.Value {
+  const [progress] = React.useState(() => new Animated.Value(0));
+  const signature = createMotionSignature(plan);
+  const previousSignature = React.useRef(signature);
+  const {
+    motionEnabled,
+    motionPaused,
+    motionDurationMs,
+    motionDelayMs,
+    motionEasing,
+    motionRepeat,
+    motionAlternate,
+  } = plan;
+
+  React.useEffect(() => {
+    progress.stopAnimation();
+
+    if (!motionEnabled) {
+      progress.setValue(0);
+      return undefined;
+    }
+
+    if (previousSignature.current !== signature) {
+      progress.setValue(0);
+      previousSignature.current = signature;
+    }
+
+    if (motionPaused) return undefined;
+
+    const animation = createMotionAnimation(progress, {
+      durationMs: motionDurationMs,
+      delayMs: motionDelayMs,
+      easing: motionEasing,
+      repeat: motionRepeat,
+      alternate: motionAlternate,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [
+    motionAlternate,
+    motionDelayMs,
+    motionDurationMs,
+    motionEasing,
+    motionEnabled,
+    motionPaused,
+    motionRepeat,
+    progress,
+    signature,
+  ]);
+
+  return progress;
+}
+
+/*** Create the one-shot or repeating React Native motion sequence for one entity. */
+function createMotionAnimation(progress: Animated.Value, input: MotionAnimationInput) {
+  const forward = () =>
+    Animated.timing(progress, {
+      toValue: 1,
+      duration: input.durationMs,
+      easing: resolveMotionEasing(input.easing),
+      useNativeDriver: false,
+    });
+  const reverse = () =>
+    Animated.timing(progress, {
+      toValue: 0,
+      duration: input.durationMs,
+      easing: resolveMotionEasing(input.easing),
+      useNativeDriver: false,
+    });
+  const movement = input.alternate
+    ? Animated.loop(Animated.sequence([forward(), reverse()]))
+    : input.repeat
+      ? Animated.loop(forward())
+      : forward();
+
+  return input.delayMs === 0
+    ? movement
+    : Animated.sequence([Animated.delay(input.delayMs), movement]);
+}
+
+/*** Create a stable signature for motion parameters that should restart the relative timeline. */
+function createMotionSignature(plan: GameEntityMotionPlan): string {
+  return [
+    plan.motionDurationMs,
+    plan.motionDelayMs,
+    plan.motionEasing,
+    plan.motionEnabled,
+    plan.motionRepeat,
+    plan.motionAlternate,
+  ].join(':');
+}
+
+/*** Map serializable timeline easing names onto React Native easing functions. */
+function resolveMotionEasing(easing: GameEntityEasing) {
+  if (easing === 'ease-in') return Easing.in(Easing.ease);
+  if (easing === 'ease-out') return Easing.out(Easing.ease);
+  if (easing === 'ease-in-out') return Easing.inOut(Easing.ease);
+  return Easing.linear;
+}

package/src/features/game/utils/useGameReducedMotion.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+/*** Track the cross-platform system reduced-motion preference for game presentation. */
+export function useGameReducedMotion(): boolean {
+  const [reduceMotion, setReduceMotion] = React.useState(false);
+
+  React.useEffect(() => {
+    void AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
+    const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);
+    return () => subscription.remove();
+  }, []);
+
+  return reduceMotion;
+}

package/src/features/layout/gridMeta.ts

@@ -1,12 +1,22 @@
 import type { ZoraComponentMeta } from '../../types/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 { LAYOUT_PROPS } from './constants';
 
 export const gridMeta = {
   name: 'Grid',
   category: 'foundation',
   directManifestNode: true,
-  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  allowedChildren: [
+    ...CONTAINER_ALLOWED_CHILDREN,
+    ...CHESS_ALLOWED_CHILDREN,
+    ...GAME_ALLOWED_CHILDREN,
+    ...TABLETOP_ALLOWED_CHILDREN,
+  ],
   props: {
     ...LAYOUT_PROPS,
     cols: { type: 'number', category: 'Layout', default: 1 },

package/src/features/layout/viewMeta.ts

@@ -1,12 +1,20 @@
 import type { ZoraComponentMeta } from '../../types/authoring';
-import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
+import {
+  CHESS_ALLOWED_CHILDREN,
+  CONTAINER_ALLOWED_CHILDREN,
+  GAME_ALLOWED_CHILDREN,
+} from '../authoring/allowedChildren';
 import { LAYOUT_PROPS } from './constants';
 
 export const viewMeta = {
   name: 'View',
   category: 'foundation',
   directManifestNode: true,
-  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  allowedChildren: [
+    ...CONTAINER_ALLOWED_CHILDREN,
+    ...CHESS_ALLOWED_CHILDREN,
+    ...GAME_ALLOWED_CHILDREN,
+  ],
   props: {
     ...LAYOUT_PROPS,
     direction: { type: 'enum', category: 'Layout', enum: ['row', 'column'] },

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -20,6 +20,7 @@ import { Breadcrumbs } from '../breadcrumbs/public';
 import { Button, ButtonGroup, IconButton } from '../button/public';
 import { Card, MediaCard, MetricCard, PostCard, ProductCard } from '../card/public';
 import { ChatListItem, MessageBubble } from '../chat/public';
+import { ChessBoard, OpeningBook } from '../chess/public';
 import { Chip, ChipGroup } from '../chip/public';
 import { CollectionEditor } from '../collection-editor/public';
 import { ContentRail } from '../content-rail/public';
@@ -34,6 +35,14 @@ import { SearchInput } from '../form/search-input/public';
 import { Select } from '../form/select/public';
 import { Switch } from '../form/switch/public';
 import { TextInput } from '../form/text-input/public';
+import {
+  Game,
+  GameEntity,
+  GameField,
+  GameInputZone,
+  GameMeasurementProbe,
+  GameOverlay,
+} from '../game/public';
 import { Gradient } from '../gradient/public';
 import { Hero } from '../hero/public';
 import { Icon } from '../icon/public';
@@ -53,6 +62,13 @@ import { ScreenSection, SectionHeader } from '../section/public';
 import { SelectableItem } from '../selection/public';
 import { Skeleton, SkeletonCard, SkeletonList, SkeletonText } from '../skeleton/public';
 import { Surface } from '../surface/public';
+import {
+  CardBack,
+  CardHand,
+  PlayingCard,
+  PokerTrainingTable,
+  TabletopTable,
+} from '../tabletop/public';
 import { Tab, TabList, TabPanel, Tabs } from '../tabs/public';
 import { ThemeModeToggle } from '../theme/adapters/inbound/ThemeModeToggle';
 import { TimePicker } from '../time-picker/public';
@@ -110,6 +126,12 @@ const _ZORA_COMPONENT_REGISTRY = {
   FormError,
   Field,
   Gradient,
+  Game,
+  GameEntity,
+  GameField,
+  GameInputZone,
+  GameMeasurementProbe,
+  GameOverlay,
   Heading,
   Icon,
   IconButton,
@@ -160,6 +182,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   SignInForm,
   SignUpForm,
   ChatListItem,
+  ChessBoard,
   CollectionEditor,
   ContentRail,
   EmptyState,
@@ -168,6 +191,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   ListItem,
   ListSection,
   MessageBubble,
+  OpeningBook,
   MissingElement,
   PostCard,
   ProductCard,
@@ -178,6 +202,11 @@ const _ZORA_COMPONENT_REGISTRY = {
   SectionHeader,
   SelectableItem,
   PaletteItem,
+  CardBack,
+  CardHand,
+  PlayingCard,
+  TabletopTable,
+  PokerTrainingTable,
   Timeline,
   TreeItem,
   TreeView,