boardweaver/react reference

Every hook and helper a client can import from boardweaver/react. How to use them together is in The React client.

Hooks

<History style? kindStyles? renderLink? /> draws the match's log with Boardweaver's own log component: style is a CSSProperties without display and flexDirection over the list, kindStyles a Record<string, CSSProperties> over each line by its kind, and renderLink(link: LinkPart): ReactNode draws a link's content in place of its parts. How it behaves: The log in the game.

type HistoryItemStep = { index: number; lines: FormattedLine[]; endsLogRow: boolean; position: number | null };
type HistoryItem =
  | { kind: "opening"; historyId: HistoryId; lines: FormattedLine[]; position: number | null }
  | { kind: "decision"; historyId: HistoryId; actorPlayerId: PlayerId | null; createdAt: Timestamp; steps: HistoryItemStep[] }
  | { kind: "undo"; historyId: HistoryId; actorPlayerId: PlayerId | null; createdAt: Timestamp; undoes: UndoneStep; position: number | null };

lineText(line: FormattedLine): string is a log line's parts as one string, with each player's name and each link's text: "Ana plays the Fireball".

apiVersion is the module's version, "4.3.0". Within a major version the module only grows: a later version adds hooks and fields and never removes them.

Moving pieces

<MoveArea>, <Movable> and <MoveTarget> let the player move a piece in two ways: click it and then click its target, or drag it onto its target. They also animate every piece the game logic moves. The game logic's offers are the only rules: prefer these components to drag and drop or move animation code of your own, and never decide in the client where a piece may go.

import { MoveArea, Movable, MoveTarget } from "boardweaver/react";

<MoveArea>
  <MoveTarget spaceId="hand-2">
    {opponentHand.map((_, index) => (
      <Movable key={index} spaceId="hand-2" index={index}>
        <CardBack />
      </Movable>
    ))}
  </MoveTarget>
  {hand.map((card, index) => (
    <Movable key={index} spaceId="hand-1" index={index}>
      {({ picked, overlay, overTarget }) => <Card card={card} raised={picked || overlay} ready={overTarget} />}
    </Movable>
  ))}
  {slots.map((slot) => (
    <MoveTarget key={slot.spaceId} spaceId={slot.spaceId}>
      {({ isTarget, isOver, dragging }) => <Slot slot={slot} lit={isTarget} hovered={isOver} dashed={dragging} />}
    </MoveTarget>
  ))}
  <MoveTarget spaceId="orbital-1s" index={0}>
    <Movable spaceId="orbital-1s" index={0}>
      <Electron />
    </Movable>
  </MoveTarget>
</MoveArea>

children is the element's own look, or a function of its state:

By default Boardweaver draws an outline on a picked piece, a dashed outline on every offered target while a piece is picked up, and a solid outline and tint on the target under a dragged piece. The dragged copy is raised a little with a shadow, and outlined while it is over a target. The piece in its place is faded while it is dragged. Pass highlight={false} to draw all of this yourself from the state. Each component renders one div, which is the piece's or the target's box: give it its size with className or style, or in CSS with [data-piece] (every Movable) and [data-move-target] (every MoveTarget), and draw the piece to fill it. The dragged copy and a flying copy are drawn at that box's size. The div also sets data-movable, data-picked, data-dragging, data-target and data-over while each state is true, for styling a state, never a size. A drag starts only after the pointer moves a few pixels, so a click never becomes a drag. Draw a Command offer, such as Pass or Confirm, as a button.

Every piece the game logic moves flies from its old place to its new one, drawn with its Movable look (with overlay true): another player's steps, and Back and Forward in replay. The piece the player dragged does not fly, since it is already where it was dropped, but every other piece the same step moves does. A move the player makes by clicking a piece and then a MoveTarget always flies, at the playback speed, from the piece to the target, even when the game logic records no move, such as a card that stays in the hand while a copy of it is planned on a slot: the copy lands on the Movable that appeared inside the target with that step, hidden until it lands, or fades out over the target when none did. The moves fly one at a time, in the order the game logic made them, so the player can follow each one: each copy waits in the piece's old place until the move before it lands, and the board waits until the last one lands. The piece in its new place is hidden until the copy lands. A move flies only when the game logic records it as a move (move_piece or move_piece_to, Changing the state) and both places are drawn with a Movable, or one of them with a MoveTarget for a hidden space. A piece flying to or from a hidden space keeps its own size, centered on the space, and is drawn as it looked before the move. A piece moved from one hidden space to another, such as a card drawn into an opponent's hand, does not fly, since neither place shows it. Boardweaver skips the flight while the player prefers reduced motion, and on a reconnect, a seek or a skip to now. A change that is not a piece moving, such as damage or a score, is not animated: animate it yourself (Optional animation helpers). To show it in its place in the sequence, start it after the moves before it: inside MoveArea, useTransitionOverlays() gives each flying move's delay, and each move flies for moveDuration.

Types

Import any of these with import type { ... } from "boardweaver/react".

The board: State, Player, Space, Piece, Arrangement, PlayerId, Score, Scores.

type State = { activePlayerIds: number[]; players: Player[]; spaces: Space[]; metaData?: Record<string, unknown> };
type Player = { playerId: number; bot?: string | null; publicState?: Record<string, unknown>; privateState?: Record<string, unknown> };
type Space = { spaceId: string; kind: string; owner?: number | null; arrangement?: "ordered" | "collection"; pieces?: Piece[]; publicState?: Record<string, unknown>; privateState?: Record<string, unknown> };
type Piece = { publicKind: string; privateKind?: string | null; owner?: number | null; publicState?: Record<string, unknown>; privateState?: Record<string, unknown> };

Moves: Action, Offer, Intent, Input, InputValue, Outcome.

type Action =
  | { type: "SpaceClick"; spaceId: string }
  | { type: "PieceClick"; spaceId: string; index: number }
  | { type: "Command"; name: string; value?: string | number | null };
type Offer = { action: Action; intent: "choice" | "confirm" | "cancel"; label?: Message | null; input?: Input | null; reveals?: boolean };
type Input = { type: "Text"; maxLen: number; suggestions: string[] } | { type: "Integer"; min: number; max: number; step?: number | null };

Outcome from act and undo is { id, type: "applied" }, { id, type: "sent" }, { id, type: "undone" } or { id, type: "failed", reason: FailureReason, applied? }, where applied counts the steps of a list that joined before one failed. The type also has committed and deferred, which act and undo never answer.

Changes: LastChange, Direction, PlaybackStatus, PlaybackView, PlaybackSpeed, WasmStepView ({ actorPlayerId?; intent?; lines: FormattedLine[]; movements: ViewedMovement[] }), FormattedLine, LinePart, PlayerPart, LinkPart, WasmLastUndo, ViewedMovement, Spot.

type FormattedLine = { playerId: number | null; kind: string | null; parts: LinePart[] };
type LinePart = string | PlayerPart | LinkPart;
type PlayerPart = { playerId: number; name: string };
type LinkPart = { key: string; parts: LinePart[] };
type Spot = { type: "At"; spaceId: string; index: number } | { type: "Hidden"; spaceId: string };
type ViewedMovement =
  | { type: "Moved"; from: Spot; to: Spot; piece: Piece }
  | { type: "Added"; at: Spot; piece: Piece }
  | { type: "Removed"; from: Spot; piece: Piece }
  | { type: "Flipped"; at: Spot; piece: Piece }
  | { type: "Shuffled"; spaceId: string };

Animation: BoardTransition, PieceTransition, TransitionEndpoint, TransitionOutcome, TransitionReason, AnimationRun, AnimationEffect, AnimationRectangle, AnimationOverlay, AnimationAnchor, AnimationElement, TransitionProviderProps.

Drafts and failures: DraftView, DraftStepView, PendingView, PendingKind, UndoAvailable, UndoneStep, CoreFailure, FailureReason, Refusal, Unresolved, AbandonedStep, AbandonReason, HistoryId, Timestamp.

FailureReason.code is one of:

Refusal.refused is NOT_OFFERED, INPUT_DOES_NOT_FIT, GAME (with the game logic's reason, a Message), NEEDS_SERVER, ENDS_DECISION, DECISION_OPEN or UNRESOLVED (with a reason of GONE, NO_SUCH_PIECE or NO_SUCH_SPACE).

Messages: Message ({ key: string; args?: Record<string, Arg> }) and Arg ({ player } | { message } | { link: { key, text } } | { number } | { text }), the text the game logic writes, which useMessageText() writes out.

Hook results: MatchInfo, SelfState, UndoControl, Pending, Failures, Playback, MatchEnd.

Platform: PlaybackOptions, HistoryOptions, HistoryControl, HistoryItem, HistoryItemStep, HistoryProps, LogLinkEvent, PlayerProfile, MatchStatus, ColorMode, GameTheme, Viewport, Sounds, SoundType, PlaySoundOptions, SoundHandle, AudioSettings.