@joystyk/cards-ui 0.0.0 → 0.2.0

package/dist/layout.d.ts

@@ -0,0 +1,122 @@
+import type { Rank, Suit } from '@joystyk/kit/cards';
+/** A face-up card: its stable id (an animation key) and its face. */
+export type FaceCard = {
+    readonly id: string;
+    readonly rank: Rank;
+    readonly suit: Suit;
+};
+/** A face-down card. It carries no id, so nothing about it reaches the page. */
+export type DownCard = {
+    readonly hidden: true;
+};
+export type PileCard = FaceCard | DownCard;
+/**
+ * How a pile shows its cards:
+ * - `down`: a column, each card lower than the last, so every face-up card shows its strip;
+ * - `right`: fanned to the right (a draw-3 waste, completed runs), showing the last `show`;
+ * - `stack`: squared up, only the top card visible (stock, foundations, free cells).
+ */
+export type Fan = 'down' | 'right' | 'stack';
+export type PileSpec = {
+    /** Unique within the table: `t3`, `waste`, `f0`. Moves name piles by it. */
+    readonly id: string;
+    /** The accessible name, already in words: "Column 3: 2 face-down cards, then 9 of spades." */
+    readonly label: string;
+    /** Bottom to top. */
+    readonly cards: readonly PileCard[];
+    readonly fan: Fan;
+    /** For `right` and `stack`: how many cards from the top are drawn. Default 1 for a stack, 3 fanned. */
+    readonly show?: number;
+    /** How many cards from the top may be picked up together; 0 for none. */
+    readonly pickable: number;
+    /** Said when the player asks for more cards than `pickable` (Spider: "different suits"). */
+    readonly limit?: string;
+    /** Legal destinations by pick-up size: `targets[k - 1]` lists the piles `k` cards may go to. */
+    readonly targets?: readonly (readonly string[])[];
+    /** Clicking the pile, or Enter on it, runs its action instead of picking up (the stock). */
+    readonly action?: boolean;
+    /** What an empty pile shows: "A" on a foundation, "K" on a column, "↺" on a stock that can redeal. */
+    readonly mark?: string;
+    /** A styling hook for the game's theme: `stock`, `waste`, `foundation`, `column`, `cell`, `runs`. */
+    readonly kind: string;
+    /** The number key that jumps to this pile: "1" … "9", "0". */
+    readonly key?: string;
+    /** How many grid columns the pile spans. Default 1. */
+    readonly span?: number;
+    /** Said after "Picked up …" from this pile: "Up to 5 can move." */
+    readonly note?: string;
+    /** Half-card horizontal steps and half-card rows in a freely placed region. */
+    readonly position?: {
+        readonly row: number;
+        readonly column: number;
+    };
+    /** A visible, non-color cue, such as a Pyramid partner's value. */
+    readonly badge?: string;
+    /** Up/Down reads individual cards without changing the one-card action. */
+    readonly inspect?: boolean;
+};
+/** Where a region sits on the table grid. Tab order follows the region list, not the place. */
+export type Place = 'top-start' | 'top-end' | 'main' | 'bottom-start' | 'bottom-end';
+export type RegionSpec = {
+    readonly id: string;
+    /** "Stock and waste", "Foundations", "Tableau". */
+    readonly label: string;
+    readonly place: Place;
+    readonly piles: readonly PileSpec[];
+    readonly placement?: 'free';
+};
+/** A suggested move, outlined on the table. */
+export type HintSpec = {
+    readonly from: string;
+    readonly to: string;
+    readonly count: number;
+};
+export type TableLayout = {
+    /** The table's name: "Klondike table". */
+    readonly label: string;
+    /** Grid columns the cards are sized for: 7 for Klondike, 8 for FreeCell, 10 for Spider. */
+    readonly columns: number;
+    readonly regions: readonly RegionSpec[];
+    readonly hint: HintSpec | null;
+    /**
+     * Single-key shortcuts that act on the focused pile (Klondike's `F`, FreeCell's `C`). The
+     * table reports them as `Key` outputs with the pile and count; other keys bubble to the game.
+     */
+    readonly keys: readonly string[];
+    /** Number shortcuts activate the named pile (rather than just focusing it). */
+    readonly activateNumbers?: boolean;
+    /** Changes whenever the cards do (the session revision). A change drops any pick-up. */
+    readonly version: number;
+};
+/** Card backs: Klondike's lattice, Spider's fine-line web, FreeCell's cells. All original. */
+export type Back = 'lattice' | 'web' | 'cells' | 'terraces' | 'contours' | 'dunes';
+export type TableOptions = {
+    /** WCAG 2.1.4: false turns off number keys and the layout's single-key shortcuts. */
+    readonly singleKeys: boolean;
+    /** Reduced motion: cards move instantly. */
+    readonly calm: boolean;
+    /** Blue diamonds and green clubs, for players who struggle with red and black. */
+    readonly fourColor: boolean;
+    readonly back: Back;
+};
+export declare const DEFAULT_OPTIONS: TableOptions;
+export declare const EMPTY_LAYOUT: TableLayout;
+export declare const isFaceCard: (card: PileCard | undefined) => card is FaceCard;
+/** A light shape check for the `layout` property (development builds validate properties). */
+export declare const isTableLayout: (value: unknown) => value is TableLayout;
+export declare const isTableOptions: (value: unknown) => value is TableOptions;
+/** Every pile with its region index and position, in Tab order. */
+export declare const allPiles: (layout: TableLayout) => readonly {
+    readonly region: number;
+    readonly index: number;
+    readonly pile: PileSpec;
+}[];
+export declare const findPile: (layout: TableLayout, id: string) => {
+    readonly region: number;
+    readonly index: number;
+    readonly pile: PileSpec;
+} | null;
+/** The face-up cards at the top of a pile, `count` of them, bottom first. */
+export declare const topCards: (pile: PileSpec, count: number) => FaceCard[];
+/** True when `count` cards from `from` may go to `to`. */
+export declare const isTarget: (pile: PileSpec, count: number, to: string) => boolean;

package/dist/layout.js

@@ -0,0 +1,35 @@
+//#region src/layout.ts
+var DEFAULT_OPTIONS = {
+	singleKeys: true,
+	calm: false,
+	fourColor: false,
+	back: "lattice"
+};
+var EMPTY_LAYOUT = {
+	label: "Card table",
+	columns: 7,
+	regions: [],
+	hint: null,
+	keys: [],
+	version: 0
+};
+var isFaceCard = (card) => card !== void 0 && !("hidden" in card);
+var isRecord = (value) => typeof value === "object" && value !== null;
+/** A light shape check for the `layout` property (development builds validate properties). */
+var isTableLayout = (value) => isRecord(value) && typeof value["label"] === "string" && typeof value["columns"] === "number" && Array.isArray(value["regions"]) && typeof value["version"] === "number";
+var isTableOptions = (value) => isRecord(value) && typeof value["singleKeys"] === "boolean" && typeof value["calm"] === "boolean" && typeof value["fourColor"] === "boolean" && typeof value["back"] === "string";
+/** Every pile with its region index and position, in Tab order. */
+var allPiles = (layout) => layout.regions.flatMap((region, r) => region.piles.map((pile, index) => ({
+	region: r,
+	index,
+	pile
+})));
+var findPile = (layout, id) => allPiles(layout).find((entry) => entry.pile.id === id) ?? null;
+/** The face-up cards at the top of a pile, `count` of them, bottom first. */
+var topCards = (pile, count) => pile.cards.slice(Math.max(0, pile.cards.length - count)).filter(isFaceCard);
+/** True when `count` cards from `from` may go to `to`. */
+var isTarget = (pile, count, to) => pile.targets?.[count - 1]?.includes(to) === true;
+//#endregion
+export { DEFAULT_OPTIONS, EMPTY_LAYOUT, allPiles, findPile, isFaceCard, isTableLayout, isTableOptions, isTarget, topCards };
+
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","names":[],"sources":["../src/layout.ts"],"sourcesContent":["// The table a card game hands to <jy-card-table>: regions of piles, each pile's cards bottom\n// to top, and what the player may do with them. It is plain JSON built from the game's view\n// on every snapshot, so the table never needs the rules: the game says how many cards a pile\n// lets go of and where each pick-up may land, and the table turns pointer and keyboard input\n// into moves (klondike.md, \"Interaction and accessibility\").\nimport type { Rank, Suit } from '@joystyk/kit/cards';\n\n/** A face-up card: its stable id (an animation key) and its face. */\nexport type FaceCard = { readonly id: string; readonly rank: Rank; readonly suit: Suit };\n\n/** A face-down card. It carries no id, so nothing about it reaches the page. */\nexport type DownCard = { readonly hidden: true };\n\nexport type PileCard = FaceCard | DownCard;\n\n/**\n * How a pile shows its cards:\n * - `down`: a column, each card lower than the last, so every face-up card shows its strip;\n * - `right`: fanned to the right (a draw-3 waste, completed runs), showing the last `show`;\n * - `stack`: squared up, only the top card visible (stock, foundations, free cells).\n */\nexport type Fan = 'down' | 'right' | 'stack';\n\nexport type PileSpec = {\n  /** Unique within the table: `t3`, `waste`, `f0`. Moves name piles by it. */\n  readonly id: string;\n  /** The accessible name, already in words: \"Column 3: 2 face-down cards, then 9 of spades.\" */\n  readonly label: string;\n  /** Bottom to top. */\n  readonly cards: readonly PileCard[];\n  readonly fan: Fan;\n  /** For `right` and `stack`: how many cards from the top are drawn. Default 1 for a stack, 3 fanned. */\n  readonly show?: number;\n  /** How many cards from the top may be picked up together; 0 for none. */\n  readonly pickable: number;\n  /** Said when the player asks for more cards than `pickable` (Spider: \"different suits\"). */\n  readonly limit?: string;\n  /** Legal destinations by pick-up size: `targets[k - 1]` lists the piles `k` cards may go to. */\n  readonly targets?: readonly (readonly string[])[];\n  /** Clicking the pile, or Enter on it, runs its action instead of picking up (the stock). */\n  readonly action?: boolean;\n  /** What an empty pile shows: \"A\" on a foundation, \"K\" on a column, \"↺\" on a stock that can redeal. */\n  readonly mark?: string;\n  /** A styling hook for the game's theme: `stock`, `waste`, `foundation`, `column`, `cell`, `runs`. */\n  readonly kind: string;\n  /** The number key that jumps to this pile: \"1\" … \"9\", \"0\". */\n  readonly key?: string;\n  /** How many grid columns the pile spans. Default 1. */\n  readonly span?: number;\n  /** Said after \"Picked up …\" from this pile: \"Up to 5 can move.\" */\n  readonly note?: string;\n  /** Half-card horizontal steps and half-card rows in a freely placed region. */\n  readonly position?: { readonly row: number; readonly column: number };\n  /** A visible, non-color cue, such as a Pyramid partner's value. */\n  readonly badge?: string;\n  /** Up/Down reads individual cards without changing the one-card action. */\n  readonly inspect?: boolean;\n};\n\n/** Where a region sits on the table grid. Tab order follows the region list, not the place. */\nexport type Place = 'top-start' | 'top-end' | 'main' | 'bottom-start' | 'bottom-end';\n\nexport type RegionSpec = {\n  readonly id: string;\n  /** \"Stock and waste\", \"Foundations\", \"Tableau\". */\n  readonly label: string;\n  readonly place: Place;\n  readonly piles: readonly PileSpec[];\n  readonly placement?: 'free';\n};\n\n/** A suggested move, outlined on the table. */\nexport type HintSpec = { readonly from: string; readonly to: string; readonly count: number };\n\nexport type TableLayout = {\n  /** The table's name: \"Klondike table\". */\n  readonly label: string;\n  /** Grid columns the cards are sized for: 7 for Klondike, 8 for FreeCell, 10 for Spider. */\n  readonly columns: number;\n  readonly regions: readonly RegionSpec[];\n  readonly hint: HintSpec | null;\n  /**\n   * Single-key shortcuts that act on the focused pile (Klondike's `F`, FreeCell's `C`). The\n   * table reports them as `Key` outputs with the pile and count; other keys bubble to the game.\n   */\n  readonly keys: readonly string[];\n  /** Number shortcuts activate the named pile (rather than just focusing it). */\n  readonly activateNumbers?: boolean;\n  /** Changes whenever the cards do (the session revision). A change drops any pick-up. */\n  readonly version: number;\n};\n\n/** Card backs: Klondike's lattice, Spider's fine-line web, FreeCell's cells. All original. */\nexport type Back = 'lattice' | 'web' | 'cells' | 'terraces' | 'contours' | 'dunes';\n\nexport type TableOptions = {\n  /** WCAG 2.1.4: false turns off number keys and the layout's single-key shortcuts. */\n  readonly singleKeys: boolean;\n  /** Reduced motion: cards move instantly. */\n  readonly calm: boolean;\n  /** Blue diamonds and green clubs, for players who struggle with red and black. */\n  readonly fourColor: boolean;\n  readonly back: Back;\n};\n\nexport const DEFAULT_OPTIONS: TableOptions = { singleKeys: true, calm: false, fourColor: false, back: 'lattice' };\n\nexport const EMPTY_LAYOUT: TableLayout = {\n  label: 'Card table',\n  columns: 7,\n  regions: [],\n  hint: null,\n  keys: [],\n  version: 0,\n};\n\nexport const isFaceCard = (card: PileCard | undefined): card is FaceCard => card !== undefined && !('hidden' in card);\n\nconst isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;\n\n/** A light shape check for the `layout` property (development builds validate properties). */\nexport const isTableLayout = (value: unknown): value is TableLayout =>\n  isRecord(value) &&\n  typeof value['label'] === 'string' &&\n  typeof value['columns'] === 'number' &&\n  Array.isArray(value['regions']) &&\n  typeof value['version'] === 'number';\n\nexport const isTableOptions = (value: unknown): value is TableOptions =>\n  isRecord(value) &&\n  typeof value['singleKeys'] === 'boolean' &&\n  typeof value['calm'] === 'boolean' &&\n  typeof value['fourColor'] === 'boolean' &&\n  typeof value['back'] === 'string';\n\n/** Every pile with its region index and position, in Tab order. */\nexport const allPiles = (\n  layout: TableLayout,\n): readonly { readonly region: number; readonly index: number; readonly pile: PileSpec }[] =>\n  layout.regions.flatMap((region, r) => region.piles.map((pile, index) => ({ region: r, index, pile })));\n\nexport const findPile = (\n  layout: TableLayout,\n  id: string,\n): { readonly region: number; readonly index: number; readonly pile: PileSpec } | null =>\n  allPiles(layout).find((entry) => entry.pile.id === id) ?? null;\n\n/** The face-up cards at the top of a pile, `count` of them, bottom first. */\nexport const topCards = (pile: PileSpec, count: number): FaceCard[] =>\n  pile.cards.slice(Math.max(0, pile.cards.length - count)).filter(isFaceCard);\n\n/** True when `count` cards from `from` may go to `to`. */\nexport const isTarget = (pile: PileSpec, count: number, to: string): boolean =>\n  pile.targets?.[count - 1]?.includes(to) === true;\n"],"mappings":";AAyGA,IAAa,kBAAgC;CAAE,YAAY;CAAM,MAAM;CAAO,WAAW;CAAO,MAAM;AAAU;AAEhH,IAAa,eAA4B;CACvC,OAAO;CACP,SAAS;CACT,SAAS,CAAC;CACV,MAAM;CACN,MAAM,CAAC;CACP,SAAS;AACX;AAEA,IAAa,cAAc,SAAiD,SAAS,KAAA,KAAa,EAAE,YAAY;AAEhH,IAAM,YAAY,UAAqD,OAAO,UAAU,YAAY,UAAU;;AAG9G,IAAa,iBAAiB,UAC5B,SAAS,KAAK,KACd,OAAO,MAAM,aAAa,YAC1B,OAAO,MAAM,eAAe,YAC5B,MAAM,QAAQ,MAAM,UAAU,KAC9B,OAAO,MAAM,eAAe;AAE9B,IAAa,kBAAkB,UAC7B,SAAS,KAAK,KACd,OAAO,MAAM,kBAAkB,aAC/B,OAAO,MAAM,YAAY,aACzB,OAAO,MAAM,iBAAiB,aAC9B,OAAO,MAAM,YAAY;;AAG3B,IAAa,YACX,WAEA,OAAO,QAAQ,SAAS,QAAQ,MAAM,OAAO,MAAM,KAAK,MAAM,WAAW;CAAE,QAAQ;CAAG;CAAO;AAAK,EAAE,CAAC;AAEvG,IAAa,YACX,QACA,OAEA,SAAS,MAAM,CAAC,CAAC,MAAM,UAAU,MAAM,KAAK,OAAO,EAAE,KAAK;;AAG5D,IAAa,YAAY,MAAgB,UACvC,KAAK,MAAM,MAAM,KAAK,IAAI,GAAG,KAAK,MAAM,SAAS,KAAK,CAAC,CAAC,CAAC,OAAO,UAAU;;AAG5E,IAAa,YAAY,MAAgB,OAAe,OACtD,KAAK,UAAU,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM"}

package/dist/solitaire.d.ts

@@ -0,0 +1,155 @@
+import { type AnyGameSession, type Json, type Mounted, type PlatformApi, type Preferences, type Validator } from '@joystyk/contracts';
+import { type Back, type TableLayout, type TableOptions } from './layout.js';
+import type { TableOut } from './controller.js';
+export type SetupField = {
+    readonly name: string;
+    readonly label: string;
+    readonly value: string;
+    readonly choices?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+};
+export type SolitaireData = {
+    readonly title: string;
+    readonly theme: 'noon' | 'dawn' | 'dusk';
+    readonly back: Back;
+    readonly layout: TableLayout;
+    readonly status: string;
+    readonly line: string;
+    readonly meters: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+    readonly fields: readonly SetupField[];
+    readonly setupAllowed: boolean;
+    readonly actions: readonly {
+        readonly label: string;
+        readonly command: Json;
+        readonly disabled: boolean;
+    }[];
+    readonly scorecard?: readonly {
+        readonly hole: number;
+        readonly strokes: number | null;
+        readonly total: number | null;
+        readonly par: number;
+        readonly cleared: boolean;
+    }[];
+    readonly recordGroup: string;
+    readonly moves: number;
+    readonly score: number;
+    readonly bestRun: number;
+    readonly cleared: number;
+    readonly keys: string;
+    readonly history?: readonly string[];
+    readonly round?: {
+        readonly strokes: number;
+        readonly bestHole: number;
+        readonly par: number;
+    };
+};
+export type SolitaireAdapter<V, E> = {
+    readonly view: Validator<V>;
+    readonly event: Validator<E>;
+    readonly describe: (view: V, events: readonly E[], revision: number) => SolitaireData;
+    readonly table: (view: V, out: TableOut) => Json | null;
+    readonly shortcut: (view: V, key: string) => Json | null;
+    readonly setup: (view: V, values: Readonly<Record<string, string>>) => Json | null;
+    /** Optional worker validation/certification before a setup command is sent. */
+    readonly prepareSetup?: (command: Json) => Promise<Json>;
+    readonly dispose?: () => void;
+};
+type Snapshot = {
+    readonly data: SolitaireData;
+    readonly revision: number;
+    readonly canUndo: boolean;
+    readonly result: string | null;
+    readonly summary: string;
+    readonly notice: string;
+    readonly elapsedMs: number;
+    readonly undosUsed: number;
+    readonly assisted: boolean;
+    readonly paused: boolean;
+};
+export type RecordRow = {
+    readonly played: number;
+    readonly won: number;
+    readonly bestScore: number | null;
+    readonly fewestMoves: number | null;
+    readonly bestMs: number | null;
+    readonly bestRun: number;
+    readonly cleared: number;
+    readonly cleanWins: number;
+    readonly streak: number;
+    readonly longestStreak: number;
+    readonly completed: number;
+    readonly totalStrokes: number;
+    readonly bestRound: number | null;
+    readonly bestHole: number | null;
+    readonly underPar: number;
+};
+type Records = Readonly<Record<string, RecordRow>>;
+export declare const decode: <T>(schema: Validator<T>, raw: unknown) => T | null;
+type Action = {
+    readonly kind: 'command';
+    readonly command: Json;
+} | {
+    readonly kind: 'undo' | 'resign';
+} | {
+    readonly kind: 'table';
+    readonly out: TableOut;
+} | {
+    readonly kind: 'key';
+    readonly key: string;
+} | {
+    readonly kind: 'setup';
+    readonly values: Readonly<Record<string, string>>;
+};
+type State = {
+    readonly snapshot: Snapshot | null;
+    readonly options: TableOptions;
+    readonly dark: boolean;
+    readonly message: string;
+    readonly dialog: 'none' | 'keys' | 'confirm';
+    readonly elapsedMs: number;
+    readonly records: Records;
+    readonly sound: boolean;
+};
+type Msg = {
+    readonly _tag: 'Snapshot';
+    readonly snapshot: Snapshot;
+} | {
+    readonly _tag: 'Preferences';
+    readonly p: Preferences;
+} | {
+    readonly _tag: 'Records';
+    readonly records: Records;
+} | {
+    readonly _tag: 'Tick';
+    readonly ms: number;
+} | {
+    readonly _tag: 'Action';
+    readonly action: Action;
+} | {
+    readonly _tag: 'Table';
+    readonly out: TableOut;
+} | {
+    readonly _tag: 'Key';
+    readonly key: string;
+    readonly ctrl: boolean;
+} | {
+    readonly _tag: 'Dialog';
+    readonly dialog: State['dialog'];
+} | {
+    readonly _tag: 'Color';
+    readonly on: boolean;
+} | {
+    readonly _tag: 'Sound';
+    readonly on: boolean;
+} | {
+    readonly _tag: 'Message';
+    readonly message: string;
+};
+export declare const SolitaireBoard: import("@gyral/core").GyralElementClass<State, Msg, object, never, "Key" | "Cancel" | "Action" | "Table" | "Color" | "Sound" | "Undo" | "Hint" | "New" | "Keys" | "Confirm" | "Setup">;
+export declare const mountSolitaire: <V, E>(slot: HTMLElement, session: AnyGameSession, platform: PlatformApi, adapter: SolitaireAdapter<V, E>) => Mounted;
+export { workerSetup } from './worker-setup.js';