@yamat47/playmaker 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takuya Yamaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @yamat47/playmaker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+アメリカンフットボールのプレー図を作成・表示する、UI フレームワーク非依存の TypeScript ライブラリ。
+コンテナ要素に図を描き、編集 UI を置き、編集のたびに `PlayData` を渡す。永続化や共有は持たない。
+
+- デモ: https://playmaker-demo.yamat47.me/
+- ソースと詳しい使い方: https://github.com/yamat47/playmaker
+
+## インストール
+
+```sh
+npm install @yamat47/playmaker
+```
+
+```ts
+import { Playmaker, type PlayData } from "@yamat47/playmaker";
+import "@yamat47/playmaker/styles.css";
+
+const playmaker = new Playmaker(document.getElementById("play")!, {
+  mode: "edit", // "edit"（既定・編集 UI あり）/ "view"（読み取り専用）
+  initialData: saved, // 永続化しておいた PlayData（省略可）
+  onChange: (data: PlayData) => save(JSON.stringify(data)),
+});
+```
+
+バンドラを通さず、CDN から読むこともできる。依存は無く、フォントは JS に同梱してある。
+URL の `0.1.0` は使う版に置き換える。
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@yamat47/playmaker@0.1.0/dist/playmaker.css" />
+<div id="play" style="width: 960px; height: 600px"></div>
+<script type="module">
+  import { Playmaker } from "https://cdn.jsdelivr.net/npm/@yamat47/playmaker@0.1.0/dist/playmaker.js";
+  new Playmaker(document.getElementById("play"));
+</script>
+```
+
+モダンブラウザと PC のマウス操作を想定する。
+
+## できること
+
+- 選手（丸・四角）とラベル、ルート・ブロック・モーションの線を置き、ドラッグで動かす
+- 位置は 0.5 ヤードの格子に揃う
+- 同梱のフォーメーションとプレーのプリセットを読み込む（`FORMATION_PRESETS`、`PLAY_PRESETS`）
+- 編集 UI を含まない PNG を書き出す（`exportToPng`）
+- 色とフォントは CSS 変数（`--playmaker-*`）でホストに合わせる
+
+公開 API の一覧、`PlayData` の形、テーマの変数は、リポジトリの README にある。
+
+## ライセンス
+
+MIT

package/dist/playmaker.css

@@ -0,0 +1,2 @@
+.playmaker-root{--_playmaker-ui-font:var(--playmaker-ui-font,Roboto, system-ui, sans-serif);--_playmaker-ui-surface:var(--playmaker-ui-surface,#fff);--_playmaker-ui-text:var(--playmaker-ui-text,#000000de);--_playmaker-ui-border:var(--playmaker-ui-border,color-mix(in srgb, var(--_playmaker-ui-text) 23%, transparent));--_playmaker-ui-accent:var(--playmaker-ui-accent,#1976d2);--_playmaker-ui-accent-text:var(--playmaker-ui-accent-text,#fff);--_playmaker-ui-shadow:0 2px 1px -1px #0003, 0 1px 1px 0 #00000024, 0 1px 3px 0 #0000001f;--_playmaker-ui-text-dim:color-mix(in srgb, var(--_playmaker-ui-text) 60%, transparent);--_playmaker-ui-text-disabled:color-mix(in srgb, var(--_playmaker-ui-text) 30%, transparent);--_playmaker-ui-divider:color-mix(in srgb, var(--_playmaker-ui-text) 12%, transparent);--_playmaker-ui-accent-faint:color-mix(in srgb, var(--_playmaker-ui-accent) 8%, transparent);--_playmaker-ui-accent-outline:color-mix(in srgb, var(--_playmaker-ui-accent) 50%, transparent);width:100%;height:100%;font-family:var(--_playmaker-ui-font);color:var(--_playmaker-ui-text);font-size:14px;overflow:hidden}.playmaker-stage{grid-area:stage;width:100%;min-width:0;height:100%;min-height:0}.playmaker-root[data-mode=edit]{grid-template:"toolbar toolbar""stage panel"minmax(0,1fr)/minmax(0,1fr) auto;gap:12px;display:grid}.playmaker-canvas{width:100%;height:100%;display:block}.playmaker-root[data-mode=edit] .playmaker-canvas{touch-action:none}.playmaker-toolbar{border:1px solid var(--_playmaker-ui-divider);background:var(--_playmaker-ui-surface);color:var(--_playmaker-ui-text);box-shadow:var(--_playmaker-ui-shadow);border-radius:4px;flex-wrap:wrap;grid-area:toolbar;align-items:center;gap:6px;padding:8px 12px;display:flex}.playmaker-toolbar__button,.playmaker-panel__reset{font:inherit;letter-spacing:.02em;border:1px solid var(--_playmaker-ui-accent-outline);color:var(--_playmaker-ui-accent);cursor:pointer;background:0 0;border-radius:4px;font-weight:500;transition:background-color .15s,border-color .15s}.playmaker-toolbar__button:hover:not([aria-disabled=true]),.playmaker-panel__reset:hover{border-color:var(--_playmaker-ui-accent);background:var(--_playmaker-ui-accent-faint)}.playmaker-toolbar__button{padding:5px 12px}.playmaker-toolbar__button[aria-pressed=true]{background:var(--_playmaker-ui-accent);border-color:var(--_playmaker-ui-accent);color:var(--_playmaker-ui-accent-text)}.playmaker-toolbar__button[aria-disabled=true]{border-color:var(--_playmaker-ui-divider);color:var(--_playmaker-ui-text-disabled);cursor:not-allowed}.playmaker-toolbar__select{font:inherit;border:1px solid var(--_playmaker-ui-border);background:var(--_playmaker-ui-surface);color:var(--_playmaker-ui-text);cursor:pointer;border-radius:4px;padding:5px 8px}.playmaker-toolbar__select:hover{border-color:var(--_playmaker-ui-text)}.playmaker-toolbar__sep{background:var(--_playmaker-ui-divider);align-self:stretch;width:1px;margin:0 4px}.playmaker-panel{box-sizing:border-box;border:1px solid var(--_playmaker-ui-divider);background:var(--_playmaker-ui-surface);width:220px;max-height:100%;color:var(--_playmaker-ui-text);box-shadow:var(--_playmaker-ui-shadow);border-radius:4px;flex-direction:column;grid-area:panel;align-self:start;gap:12px;padding:12px 16px 16px;display:flex;overflow-y:auto}.playmaker-panel__title{margin:0;font-size:1.15em;font-weight:500}.playmaker-panel__hint{color:var(--_playmaker-ui-text-dim);margin:0;font-size:1em;line-height:1.5}.playmaker-panel__row{align-items:center;gap:8px;display:flex}.playmaker-panel__label{display:contents}.playmaker-panel__row-text{white-space:nowrap;color:var(--_playmaker-ui-text-dim);margin-right:auto}.playmaker-panel__row input,.playmaker-panel__row select{font:inherit;border:1px solid var(--_playmaker-ui-border);background:var(--_playmaker-ui-surface);min-width:0;color:var(--_playmaker-ui-text);border-radius:4px;flex:auto;padding:4px 8px}.playmaker-panel__row input:hover,.playmaker-panel__row select:hover{border-color:var(--_playmaker-ui-text)}.playmaker-root :is(button,input,select):focus-visible{outline:2px solid var(--_playmaker-ui-accent);outline-offset:1px}.playmaker-panel__swatches{flex:none;gap:6px;display:flex}.playmaker-panel__swatches--rows{grid-template-columns:repeat(4,auto);display:grid}.playmaker-panel__swatch{border:1px solid var(--_playmaker-ui-divider);cursor:pointer;border-radius:50%;width:22px;height:22px;padding:0}.playmaker-panel__swatch--outline{background:var(--_playmaker-ui-surface);border-width:3px}.playmaker-panel__swatch[aria-pressed=true]{outline:2px solid var(--_playmaker-ui-accent);outline-offset:2px}.playmaker-panel__reset{flex:none;padding:2px 8px;font-size:.93em}
+/*$vite$:1*/

package/dist/playmaker.d.ts

@@ -0,0 +1,319 @@
+/**
+ * 今の PlayData のスキーマの版。スキーマを変えるときは 1 上げ、`PLAY_DATA_MIGRATIONS` に
+ * 1 つ前の版から変換する段を足す。
+ */
+export declare const CURRENT_PLAY_DATA_VERSION: 2;
+
+/** リスナを登録し、購読をやめるための IDisposable を返す。 */
+declare type Event_2<T> = (listener: (e: T) => void) => IDisposable;
+export { Event_2 as Event }
+
+/**
+ * サイドラインの間の幅。規定は 160 フィート（53⅓ ヤード）だが、中央（26.5）が
+ * 0.5 ヤードの格子点に乗るように 53 ヤードへ丸める。本物の寸法との差は 1 フィートで、
+ * 図の見た目には出ない。
+ */
+export declare const FIELD_WIDTH_YARDS = 53;
+
+export declare const FIELD_ZONE_LABELS: {
+    readonly "own-redzone": "自陣RZ";
+    readonly middle: "中央";
+    readonly redzone: "相手RZ";
+};
+
+/**
+ * フィールドのどの範囲を映すか。
+ * - `middle`: センター付近
+ * - `redzone`: 相手のゴール側
+ * - `own-redzone`: 自陣のゴール側
+ */
+export declare const FIELD_ZONE_VALUES: readonly ["own-redzone", "middle", "redzone"];
+
+/**
+ * フィールド上の位置（ヤード）。縦は LOS（`field.losYard`）からの距離で持つので、
+ * ゾーンを切り替えて LOS が動いても、図は形を保ったまま一緒に動く。
+ * - lateralYard: 0 = 左サイドライン … FIELD_WIDTH_YARDS = 右サイドライン
+ * - downfieldYard: 0 = LOS。正が攻撃方向（画面の上）、負がバックフィールド
+ *
+ * どちらも GRID_STEP_YARDS の倍数で、モデルの中に格子の外の位置は無い。
+ */
+export declare interface FieldPosition {
+    readonly lateralYard: number;
+    readonly downfieldYard: number;
+}
+
+export declare interface FieldState {
+    readonly zone: FieldZone;
+    /**
+     * LOS の絶対ヤード。今はゾーンから決まり、読み込んだデータの値は使わない。
+     * 保存するデータから選手の絶対位置を復元できるよう、値としては持たせる。
+     */
+    readonly losYard: number;
+}
+
+export declare type FieldZone = (typeof FIELD_ZONE_VALUES)[number];
+
+/** 読み込むと、players を今の図に足す。プリセットのほかに、利用者が作った隊形も渡せる。 */
+export declare interface Formation {
+    readonly id: string;
+    readonly name: string;
+    /** 読み込んだときの選手の配置には影響しない。 */
+    readonly side: TeamSide;
+    /** 1 人以上。 */
+    readonly players: readonly FormationPlayer[];
+}
+
+export declare const FORMATION_PRESETS: readonly Formation[];
+
+/**
+ * 隊形の 1 人。`id` は持たず、読み込むたびに振る。同じ隊形を 2 回読んでも、
+ * 図にいる選手とも Undo で戻る選手とも id がぶつからない。
+ */
+export declare type FormationPlayer = Omit<Player, "id">;
+
+export declare function getFormationPreset(id: string): Formation | undefined;
+
+export declare function getPlayPreset(id: string): PlayPreset | undefined;
+
+/**
+ * 位置を置ける格子の刻み（ヤード）。横はサイドライン、縦は LOS を原点にする。
+ * 図の中の位置はすべてこの格子点にあるので、要素同士を揃える操作が無くても縦横が揃う。
+ */
+export declare const GRID_STEP_YARDS = 0.5;
+
+export declare interface IDisposable {
+    dispose(): void;
+}
+
+export declare interface ImageExportOptions {
+    /**
+     * PNG の幅（px）。高さはゾーンの窓の縦横比から決める。
+     * 未指定、有限でない値、1 未満は 1600 にし、4096 を超える幅は 4096 に切り詰める。
+     */
+    width?: number | undefined;
+}
+
+/**
+ * 1 本の線。起点は座標ではなく選手の id で持つので、選手を動かすと線の起点も付いてくる。
+ * `color` と `thickness` を省くと、テーマの色と種別ごとの既定の太さで描く。
+ */
+export declare interface Line {
+    readonly id: string;
+    readonly kind: LineKind;
+    /** 起点となる選手の id。実在しない参照は復元時に除外される。 */
+    readonly startPlayerId: string;
+    /** 起点と終点の間の中継点（0 個可）。 */
+    readonly waypoints: readonly FieldPosition[];
+    /** 終点（ヤード空間）。 */
+    readonly end: FieldPosition;
+    readonly interpolation: LineInterpolation;
+    /** CSS の色の文字列。 */
+    readonly color?: string;
+    /** 種別ごとの既定の太さに対する倍率。省くと DEFAULT_LINE_THICKNESS。 */
+    readonly thickness?: number;
+}
+
+/**
+ * 線の補間方法。どの種別の線にも効く。
+ * - `straight`: 制御点を直線で結ぶ
+ * - `bezier`: 制御点をすべて通る滑らかな曲線で結ぶ
+ */
+declare const LINE_INTERPOLATION_VALUES: readonly ["straight", "bezier"];
+
+/**
+ * 線の種別。色ではなく終点の記法と線種で見分ける。
+ * - `route`: レシーバーやランナーの走路。終点に矢印を描く
+ * - `block`: ブロックの割り当て。route と同じ太さで、終点に T 字のバーを描く
+ * - `motion`: スナップ前の選手の移動。破線で、終点に矢印を描く
+ */
+declare const LINE_KIND_VALUES: readonly ["route", "block", "motion"];
+
+export declare type LineInterpolation = (typeof LINE_INTERPOLATION_VALUES)[number];
+
+export declare type LineKind = (typeof LINE_KIND_VALUES)[number];
+
+/**
+ * どの版で保存したデータでも、今の版の PlayData にする。壊れたデータを渡しても投げない。
+ * 返り値は新しいオブジェクトで、入力と参照を共有しない。
+ * 選手、線、waypoint は MAX_PLAYERS、MAX_LINES、MAX_WAYPOINTS_PER_LINE の個数までしか読まない。
+ */
+export declare function migratePlayData(raw: unknown): PlayData;
+
+export declare const PLAY_PRESETS: readonly PlayPreset[];
+
+/** プレーの種類。色は持たず、一覧でどう見せるかは使う側が決める。 */
+export declare type PlayCategory = "run-zone" | "run-gap" | "pass-quick" | "pass-dropback" | "pass-deep" | "pa" | "rpo" | "coverage" | "pressure";
+
+/**
+ * プレー図のデータ。保存したものを `restorePlayData` に渡すと、古い版や版の無いもの、
+ * 新しい版のものも今の版に寄せて読む。
+ */
+export declare interface PlayData {
+    readonly version: typeof CURRENT_PLAY_DATA_VERSION;
+    readonly field: FieldState;
+    /** 後の要素ほど上に重ねて描く。 */
+    readonly players: readonly Player[];
+    /** 後の要素ほど上に重ねて描く。 */
+    readonly lines: readonly Line[];
+}
+
+/**
+ * 型付きで組み立てて読み込む図。LOS の位置は読み込むときにゾーンから決め直すので、
+ * `field.losYard` は省略できる。
+ */
+export declare interface PlayDataInput extends Omit<PlayData, "field"> {
+    readonly field: Omit<FieldState, "losYard"> & {
+        readonly losYard?: number | undefined;
+    };
+}
+
+/**
+ * 1 人の選手。`color` は CSS の色の文字列で、省くとテーマの色で描く。
+ * `fill` を省くと DEFAULT_PLAYER_FILL で描く。
+ */
+export declare interface Player {
+    readonly id: string;
+    readonly position: FieldPosition;
+    readonly shape: PlayerShape;
+    readonly label: string;
+    readonly color?: string;
+    readonly fill?: PlayerFill;
+}
+
+/**
+ * 選手マーカーの塗り。枠線だけ（`outline`）か、色で塗りつぶす（`solid`）か。
+ * 形状とは独立に持ち、攻守や役割の見分けに使う。パネルはこの順にスウォッチを並べる。
+ */
+declare const PLAYER_FILL_VALUES: readonly ["outline", "solid"];
+
+/**
+ * 選手マーカーの形状。種類が多いと図が散らかるので、丸と四角の 2 種だけにする。
+ * どちらも外接円を当たり判定にできるので、hit-test は形状で分けない。
+ */
+declare const PLAYER_SHAPE_VALUES: readonly ["circle", "square"];
+
+export declare type PlayerFill = (typeof PLAYER_FILL_VALUES)[number];
+
+export declare type PlayerShape = (typeof PLAYER_SHAPE_VALUES)[number];
+
+/**
+ * container の中にプレー図を描き、edit モードでは編集 UI も置く。
+ * dispose すると、置いた要素をすべて取り除く。
+ * dispose したあとの変更は例外を投げずに何もせず、開発時だけ console.warn で知らせる。
+ * getPlayData と fieldZone は、dispose した時点の図を返す。
+ */
+export declare class Playmaker implements IDisposable {
+    /**
+     * 編集コマンドと Undo / Redo の確定ごとに 1 回、最新の図の深いコピーを渡す。
+     * `version` は常に現行なので、受け取った値をそのまま永続化できる。
+     * 構築時、`setPlayData` と `restorePlayData` での読み込み、PNG の書き出しでは発火しない
+     * （読み込みは編集ではないため）。
+     * コピーはリスナごとに作るので、受け手が書き換えても、この図とほかのリスナには波及しない。
+     * 返り値を dispose すると購読をやめる。
+     */
+    readonly onDidChange: Event_2<PlayData>;
+    private readonly store;
+    private readonly root;
+    private readonly surface;
+    private readonly session;
+    private currentMode;
+    private panel;
+    private ui;
+    constructor(container: HTMLElement, options?: PlaymakerOptions);
+    get mode(): PlaymakerMode;
+    /**
+     * モードを切り替える。図と Undo の履歴は残し、編集 UI とポインタ、キーの入力だけを付け外しする。
+     * view にすると、ドラッグや作図の途中の操作は取り消し、選択の強調も描かない。
+     */
+    setMode(mode: PlaymakerMode): void;
+    get fieldZone(): FieldZone;
+    /**
+     * LOS をそのゾーンの既定の位置へ移し、選手と線も一緒に動かす。
+     * 編集なので Undo と onDidChange の対象になる。view モードでも呼べる。
+     */
+    setFieldZone(zone: FieldZone): void;
+    /**
+     * 隊形の選手を今の図に追記し、置いたら true を返す。攻守の隊形を順に重ねられる。
+     * 選手の位置は LOS からの相対（`lateralYard` と `downfieldYard`）で書く。
+     * 外から渡した隊形は正規化してから読むので、位置の読めない選手は捨てる。
+     * 置ける選手が 1 人もいないときと、置くと選手が 64 人を超えるときは、1 人も置かずに false を返す。
+     * 編集なので Undo と onDidChange の対象になる。view モードでも呼べる。
+     */
+    loadFormation(formation: Formation): boolean;
+    /**
+     * 型付きで組み立てた図を読み込み、今の図と置き換える。`getPlayData` の戻り値や、
+     * プリセットの `data` もそのまま渡せる。
+     * 型に合っていても、重複した id と件数の上限を超えた分は `restorePlayData` と同じく正規化する。
+     * 読み込みは編集ではないので、Undo の履歴は消え、onDidChange は発火しない。
+     */
+    setPlayData(data: PlayDataInput): void;
+    /**
+     * 永続化しておいた値を、形を確かめずに受け取って読み込み、今の図と置き換える。
+     * 旧版、版の無いもの、未来版、壊れたデータも、例外を投げずに今のスキーマへ寄せ、読めない要素だけを捨てる。
+     * 選手 64 人、線 128 本、線 1 本あたり waypoint 32 個を超える分は、先頭から上限までを残して捨てる。
+     * 読み込みは編集ではないので、Undo の履歴は消え、onDidChange は発火しない。
+     */
+    restorePlayData(raw: unknown): void;
+    /**
+     * 今の図の深いコピー。`version` は常に現行で、そのまま JSON にして永続化できる。
+     * `restorePlayData` か `initialData` に戻すと、同じ図になる。
+     * 編集でも件数の上限は超えられず、上限に達すると選手の追加、フォーメーションの読み込み、作図は何もしない。
+     */
+    getPlayData(): PlayData;
+    /**
+     * 呼んだ時点で確定しているプレー図を PNG 画像（Blob）として書き出す。
+     * 選択の強調、waypoint のハンドル、ドラッグや作図の途中の形、ツールバーとパネルは入らない。
+     * view と edit のどちらのモードでも使える。
+     * 同梱フォントを読み込み終えてから描くので、構築の直後に呼んでもヤードの数字と選手のラベルは同梱フォントになる。
+     * フォントを読み込めなかったときは代わりのフォントで描く。
+     * canvas を確保できないとき、PNG に変換できないとき、dispose したあとは、例外を投げずに reject する。
+     */
+    exportToPng(options?: ImageExportOptions): Promise<Blob>;
+    /**
+     * 図とパネルの色を、テーマの CSS 変数から読み直す。CSS 変数を変えてもブラウザは知らせてこないので、
+     * ホストが祖先の要素で変数を変えたあとに呼ぶ。
+     */
+    refresh(): void;
+    dispose(): void;
+    /** dispose したあとの呼び出しは何もしないので、開発時だけそのことを知らせる。 */
+    private warnIgnoredAfterDispose;
+    private replaceUi;
+    private createUi;
+    private draw;
+    /** view モードでは undefined を返し、格子や選択の強調のような編集中だけの層を描かせない。 */
+    private surfaceOverlay;
+}
+
+export declare type PlaymakerMode = "view" | "edit";
+
+export declare interface PlaymakerOptions {
+    /**
+     * 最初のモード。既定は "edit"。"view" は編集 UI を置かず、ポインタとキーの操作も受けない。
+     * あとから `setMode` で切り替えられる。
+     */
+    mode?: PlaymakerMode | undefined;
+    /** 最初に表示する図。`restorePlayData` と同じく、形を確かめずに受け取って今のスキーマへ寄せる。 */
+    initialData?: unknown;
+    /** 構築時に `onDidChange` へ登録するリスナ。解除するには Playmaker を dispose する。 */
+    onChange?: ((data: PlayData) => void) | undefined;
+}
+
+/** 線まで描き込んだプレー図に、一覧に出すための情報を添えたもの。 */
+export declare interface PlayPreset {
+    readonly id: string;
+    readonly name: string;
+    readonly side: TeamSide;
+    readonly category: PlayCategory;
+    /** パーソネルか隊形の短い注記（例: "11 pers"、"Nickel"）。 */
+    readonly personnel: string;
+    /** コンセプトの 1 行の説明。 */
+    readonly summary: string;
+    /** そのまま setPlayData に渡せる。 */
+    readonly data: PlayData;
+}
+
+declare const TEAM_SIDE_VALUES: readonly ["offense", "defense"];
+
+export declare type TeamSide = (typeof TEAM_SIDE_VALUES)[number];
+
+export { }