@spotlab/hand-matrix 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James DiGioia
+
+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,194 @@
-# Temporary Holding Version
+# @spotlab/hand-matrix
 
-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.
+A 13x13 poker hand-matrix React component. Peer-deps `react`, `react-dom`,
+and [`@spotlab/range`](../range) — no Tailwind, no bundler-plugin
+requirement.
+
+```tsx
+import { RangeGrid } from "@spotlab/hand-matrix";
+import "@spotlab/hand-matrix/style.css";
+import { initRange } from "@spotlab/range";
+
+await initRange(); // once, at startup
+
+<RangeGrid range="AKs:0.5,QQ" />;
+```
+
+## Exports
+
+Everything below is exported from the package root.
+
+### Display
+
+- `HandMatrix` — the bare 13x13 grid primitive. Takes no range data; styling
+  is entirely the caller's job via `comboStyle`, keyed by combo string (e.g.
+  `"AKs"`). Each cell carries a `data-combo` attribute. Props:
+  - `comboStyle?: (combo) => CSSProperties` — per-cell style.
+  - `onPointerDown?`, `onPointerEnter?: CellPointerHandler` — the
+    `(combo, event)` handlers to use for dragging across cells, with a mouse
+    or a finger. `onPointerDown` releases the implicit pointer capture a
+    touch takes on its first cell. `onPointerEnter` fires once each time the
+    pointer moves onto a new cell, found by hit-testing each `pointermove`
+    (`elementFromPoint`), so it also fires during a touch drag, where
+    enter events never reach the other cells. Passing `onPointerDown` sets
+    `touch-action: none` and `user-select: none` on the grid, so a drag
+    neither scrolls the page nor selects the combo text it crosses.
+  - `className?: string` — merged onto the `.spotlab-hm-root` wrapper.
+- `RangeGrid` — a read-only display component. Accepts the expanded
+  `HandFrequency[]` form or a range string directly (parsed via
+  `@spotlab/range`), and fills each cell to its combo's mean weight. Props:
+  `range: HandFrequency[] | string`, `fill?: string` (a CSS color, defaulting
+  to `var(--spotlab-hm-fill)`), `className?: string`.
+- `cellFillGradient(stops: string[]): string` / `CELL_FILL_DIRECTION` — the
+  canonical left-to-right gradient helper used to render a cell's fill.
+  Returns `"transparent"` for no stops.
+
+`RangeGrid`'s combo collapse (`toComboWeights`) is a wasm call, so
+`initRange()` must have resolved before rendering it — see
+[`@spotlab/range`](../range)'s own README for why that call is explicit
+rather than automatic.
+
+### Editing
+
+The editor splits a parent range across a set of actions (e.g. fold, call,
+raise). Its state is an array of 169 `EditorCell`s, one per combo in
+`@spotlab/range`'s `COMBOS` order. Every component is fully controlled: state
+goes in as props and changes come out through `on*Change` callbacks.
+
+- `RangeMatrixEditor` — the paintable grid. Draws each cell's action bands,
+  hatches dead cells (`avail` 0), marks capped cells (`avail` below 1), and
+  wires brush/eyedropper painting onto `HandMatrix` for mouse and touch.
+  Props (`RangeMatrixEditorProps`):
+  - `cells: EditorCell[]` and `onCellsChange(cells)`.
+  - `actions: EditorActionSpec[]` — index-aligned with each cell's
+    `weights`.
+  - `order: number[]` — indices into `actions`, in the order bands stack.
+  - `brush: number[]` and `onBrushChange(brush)` — the weights a paint
+    stroke applies, index-aligned with `actions`.
+  - `tool: PaintTool` and `onToolChange(tool)` — `"brush"` paints on press
+    and drag; `"eyedropper"` loads a cell's weights onto the brush and
+    switches back to `"brush"`.
+  - `className?: string`.
+- `ActionWeightSliders` — one slider and numeric input per action for
+  editing a brush (or any weight row). Moving one action rebalances the
+  others so the row keeps summing to 100. Props (`ActionWeightSlidersProps`):
+  - `actions`, `order`, `weights: number[]` and `onWeightsChange(weights)`.
+  - `passive: number` — the index of the remainder action, which absorbs
+    whatever the others leave.
+  - `renderActionLabel?(action, index, isPassive)` — replaces a row's
+    default label.
+  - `renderActionExtra?(action, index)` — content after the label (e.g. a
+    remove button).
+  - `components?: { WeightInput?: ComponentType<WeightInputProps> }` — swap
+    the default `<input type="number">`.
+  - `className?: string`.
+- `useRangePainting(opts)` — the brush/eyedropper state machine behind
+  `RangeMatrixEditor`, for building your own grid. `opts` takes the editor's
+  `cells`, `brush`, `tool` and their three `on*Change` callbacks. Returns
+  `{ onCellDown(combo), onCellEnter(combo) }`; wire them to `HandMatrix`'s
+  `onPointerDown`/`onPointerEnter`. A stroke ends on any window `pointerup`
+  or `pointercancel`.
+- `seedCells(avail, actionWeights, passive): EditorCell[]` — build the
+  initial grid from a parent range's per-combo availability (`null` for
+  unconstrained) and each action's absolute per-combo weights (the
+  `Map<string, number>` that `toComboWeights` from `@spotlab/range`
+  produces).
+- `cellsToComboWeights(cells, actionIndex): Map<string, number>` — collapse
+  one action back to absolute per-combo weights, ready to save as a range.
+- `comboWeightsToCells(cells, actionWeights, passive): EditorCell[]` — the
+  inverse: re-derive the cells' conditional weights from absolute
+  per-action ranges, keeping each cell's `avail`.
+- `rebalance(weights, index, value, passive): number[]` — set one action's
+  weight and rescale the rest so the row sums to 100. This is what
+  `ActionWeightSliders` uses.
+- Types: `EditorCell` (`{ avail: number; weights: number[] }`, where `avail`
+  is the combo's cap in the parent range and `weights` are each action's
+  share of it, summing to 100), `EditorActionSpec`
+  (`{ id: string; label: string; color: string }`), `PaintTool`,
+  `CellPointerHandler`, `RangeMatrixEditorProps`, `ActionWeightSlidersProps`,
+  `WeightInputProps`.
+
+**The editor works at combo level.** A cell is one of the 169 combos (`AKs`,
+`AKo`, `QQ`), so suit-specific hands such as `AsKd` don't survive a round
+trip: `seedCells` takes combo weights, and `cellsToComboWeights` returns
+them. To keep suit-specific hands, set them aside before editing and add them
+back to the result yourself.
+
+## Theming
+
+The package ships `hand-matrix.css` (`@spotlab/hand-matrix/style.css`),
+scoped entirely under a `.spotlab-hm-root` wrapper that every top-level
+component renders for itself, merged with any `className` passed in. Every
+custom property has a default declared on `.spotlab-hm-root`, so the
+component renders correctly with zero theming.
+
+Because the `className` you pass to a component lands on that same root, a
+class that sets variables works there too (`<RangeGrid className="my-theme" />`
+with `.my-theme { --spotlab-hm-border: … }`), in addition to the
+`.spotlab-hm-root` selector form below.
+
+**To override a variable, target `.spotlab-hm-root` itself** — not `:root`
+and not any other ancestor. Because the package's own default is declared
+directly on `.spotlab-hm-root`, a value set only on an ancestor loses to it
+regardless of specificity (an element's own declared value always beats an
+inherited one). This is the single most likely integration mistake:
+
+```css
+/* This does NOT win: */
+:root {
+  --spotlab-hm-fill: #f59e0b;
+}
+
+/* This does: */
+.spotlab-hm-root {
+  --spotlab-hm-fill: #f59e0b;
+}
+```
+
+**The package's defaults live in a named CSS cascade layer** (`@layer
+spotlab-hand-matrix`), not unlayered — this is what makes the above override
+reliable. Per the CSS cascade, unlayered styles always beat every `@layer`
+regardless of specificity or source order, so if the package's defaults were
+unlayered, a plain override would only win when it happened to load _after_
+the package's stylesheet; load it first, or wrap it in your own `@layer`,
+and the override would silently lose instead. Putting the defaults in a
+named layer makes any unlayered override — the common case for a plain CSS
+file or style tag, which is exactly what most consumers write — win
+automatically, regardless of import order.
+
+The one case this doesn't cover for free: if **your own styles are also
+inside a named layer** (for example, a Tailwind v4 app that wraps its design
+tokens in `@layer base`), layer priority is decided by each layer name's
+_first appearance_ in the stylesheet, not by where the override rule itself
+sits. A layer named for the first time later in the cascade outranks one
+named earlier, so you must import `@spotlab/hand-matrix/style.css` **before**
+whatever first establishes your own layer order (e.g. before `@import
+"tailwindcss"`, which emits `@layer theme, base, components, utilities;` as
+its first statement) — otherwise `spotlab-hand-matrix` gets appended last and
+outranks your override instead:
+
+```css
+/* Correct: registers `spotlab-hand-matrix` before Tailwind's layers, so
+   `@layer base` (where your override lives) outranks it. */
+@import "@spotlab/hand-matrix/style.css";
+@import "tailwindcss";
+```
+
+If you don't use cascade layers yourself (e.g. a plain CSS file, or an
+Obsidian plugin with no bundler-level layer system), none of this applies —
+your override is unlayered and wins unconditionally, in any import order.
+
+Available variables: `--spotlab-hm-border`, `--spotlab-hm-border-width`,
+`--spotlab-hm-cell-bg`, `--spotlab-hm-cell-fg`, `--spotlab-hm-fill`,
+`--spotlab-hm-font-family`, `--spotlab-hm-font-size`,
+`--spotlab-hm-font-weight`, `--spotlab-hm-radius`, `--spotlab-hm-surface-bg`,
+`--spotlab-hm-muted-bg`, `--spotlab-hm-muted-fg`, `--spotlab-hm-track-bg`,
+`--spotlab-hm-row-passive-bg`, `--spotlab-hm-dead-hatch`.
+
+Action/fill colors (`RangeGrid`'s `fill` prop) are **not** theme variables —
+they are data, passed as props. `--spotlab-hm-fill` is only the default used
+when `fill` is omitted.
+
+## License
+
+MIT — see `LICENSE`.

package/dist/editor/action-sliders.d.ts

@@ -0,0 +1,35 @@
+import { ChangeEvent, ComponentType, FC, ReactNode } from 'react';
+import { EditorActionSpec } from './weights';
+export type WeightInputProps = {
+    value: number;
+    "aria-label": string;
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+};
+export type ActionWeightSlidersProps = {
+    actions: EditorActionSpec[];
+    /** Indices into `actions`/`weights`, in the order rows should render. */
+    order: number[];
+    /** Index-aligned with `actions`. */
+    weights: number[];
+    passive: number;
+    onWeightsChange: (weights: number[]) => void;
+    /**
+     * Leading content for a row's header, replacing the default label — the
+     * slot for a control that takes the label's own position (e.g. a
+     * raise-size input) rather than trailing it. Defaults to the action's
+     * label (plus a "· remainder" suffix on the passive row).
+     */
+    renderActionLabel?: (action: EditorActionSpec, index: number, isPassive: boolean) => ReactNode;
+    /** Extra content rendered after an action's label — the slot for consumer-specific controls (a remove button). */
+    renderActionExtra?: (action: EditorActionSpec, index: number) => ReactNode;
+    components?: {
+        WeightInput?: ComponentType<WeightInputProps>;
+    };
+    className?: string;
+};
+/**
+ * One pointer-driven weight slider per action, each paired with a numeric
+ * input for keyboard entry. Adjusting one action rebalances the others
+ * proportionally so the row's weights keep summing to 100.
+ */
+export declare const ActionWeightSliders: FC<ActionWeightSlidersProps>;

package/dist/editor/cells.d.ts

@@ -0,0 +1,26 @@
+export declare const COMBO_INDEX: Map<string, number>;
+/**
+ * One matrix cell's painted state: `avail` is the combo's cap (its weight in the
+ * parent range the editor is splitting), `weights` are each action's conditional
+ * share of that cap, summing to 100 across the node's actions.
+ */
+export type EditorCell = {
+    avail: number;
+    weights: number[];
+};
+/**
+ * Seed the 169-cell grid from a parent range's per-combo availability and each
+ * action's own per-combo range, both expressed as absolute weights (a share of
+ * the whole deck, as `toComboWeights` from `@spotlab/range` produces). `avail`
+ * of `null` means the combo is unconstrained (available at 1). `passive` must be
+ * a valid index into `actionWeights` naming the remainder action.
+ */
+export declare function seedCells(avail: Map<string, number> | null, actionWeights: (Map<string, number> | null)[], passive: number): EditorCell[];
+/** Collapse one action's conditional weights back to absolute per-combo weights. */
+export declare function cellsToComboWeights(cells: EditorCell[], actionIndex: number): Map<string, number>;
+/**
+ * Re-derive conditional cell weights from absolute per-action ranges — the
+ * inverse of `cellsToComboWeights`. `passive` must be a valid index into
+ * `actionWeights` naming the remainder action.
+ */
+export declare function comboWeightsToCells(cells: EditorCell[], actionWeights: (Map<string, number> | null)[], passive: number): EditorCell[];

package/dist/editor/matrix-editor.d.ts

@@ -0,0 +1,24 @@
+import { FC } from 'react';
+import { PaintTool } from './use-range-painting';
+import { EditorCell } from './cells';
+import { EditorActionSpec } from './weights';
+export type RangeMatrixEditorProps = {
+    /** The 169-cell grid, in `@spotlab/range`'s `COMBOS` order. */
+    cells: EditorCell[];
+    /** Index-aligned with each cell's `weights` array. */
+    actions: EditorActionSpec[];
+    /** Indices into `actions`/`weights`, in the order bands should stack — a display concern the consumer owns (e.g. biggest raise first). */
+    order: number[];
+    brush: number[];
+    tool: PaintTool;
+    onCellsChange: (cells: EditorCell[]) => void;
+    onBrushChange: (brush: number[]) => void;
+    onToolChange: (tool: PaintTool) => void;
+    className?: string;
+};
+/**
+ * The paintable 13x13 range grid: per-cell action bands, the dead-cell hatch,
+ * the capped-cell cap marker, and the brush/eyedropper painting wired onto
+ * `HandMatrix`. Fully controlled; `useRangePainting` drives the state changes.
+ */
+export declare const RangeMatrixEditor: FC<RangeMatrixEditorProps>;

package/dist/editor/use-range-painting.d.ts

@@ -0,0 +1,23 @@
+import { EditorCell } from './cells';
+export type PaintTool = "brush" | "eyedropper";
+/**
+ * The brush/eyedropper state machine behind `RangeMatrixEditor`: drag-painting
+ * and eyedropping a cell's weights back onto the brush. Fully controlled — all
+ * state changes go out through the `on*Change` callbacks.
+ *
+ * Wire `onCellDown` to a cell's pointer-down and `onCellEnter` to the pointer
+ * moving onto a cell (`HandMatrix`'s `onPointerDown`/`onPointerEnter` do both,
+ * for mouse and touch alike). A stroke ends on any window `pointerup` or
+ * `pointercancel`.
+ */
+export declare function useRangePainting(opts: {
+    cells: EditorCell[];
+    brush: number[];
+    tool: PaintTool;
+    onCellsChange: (cells: EditorCell[]) => void;
+    onBrushChange: (brush: number[]) => void;
+    onToolChange: (tool: PaintTool) => void;
+}): {
+    onCellDown: (combo: string) => void;
+    onCellEnter: (combo: string) => void;
+};

package/dist/editor/weights.d.ts

@@ -0,0 +1,13 @@
+export declare const fixRound: (weights: number[], keep: number) => number[];
+/**
+ * `passive` names the remainder action — the one whose weight absorbs whatever
+ * the others leave behind. It must be a valid index into `weights`; the caller
+ * decides which action that is and guarantees one exists.
+ */
+export declare const rebalance: (weights: number[], index: number, value: number, passive: number) => number[];
+export declare const sumActive: (weights: number[], passive: number) => number;
+export type EditorActionSpec = {
+    id: string;
+    label: string;
+    color: string;
+};

package/dist/hand-matrix.css

@@ -0,0 +1,147 @@
+/*
+ * Defaults live in a named layer, not unlayered: unlayered CSS always beats
+ * every `@layer`, even one a consumer wrote specifically to override these
+ * variables. A named layer lets a consumer's plain (unlayered) override CSS
+ * win regardless of import order, and lets a consumer who uses cascade
+ * layers themselves (e.g. Tailwind) place their own override layer after
+ * this one. See the "Theming" section of README.md for how to register this
+ * layer's priority relative to a bundler-level layer system.
+ */
+@layer spotlab-hand-matrix {
+  .spotlab-hm-root {
+    --spotlab-hm-border: #d4d4d8;
+    --spotlab-hm-border-width: 1px;
+    --spotlab-hm-cell-bg: transparent;
+    --spotlab-hm-cell-fg: #18181b;
+    --spotlab-hm-muted-bg: #f4f4f5;
+    --spotlab-hm-muted-fg: #71717a;
+    --spotlab-hm-fill: #10b981;
+    --spotlab-hm-font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    --spotlab-hm-font-size: 0.75rem;
+    --spotlab-hm-font-weight: 600;
+    --spotlab-hm-dead-hatch: repeating-linear-gradient(
+      45deg,
+      rgba(15, 23, 42, 0.22) 0 3px,
+      rgba(255, 255, 255, 0.18) 3px 6px
+    );
+    --spotlab-hm-radius: 0.5rem;
+    --spotlab-hm-surface-bg: #ffffff;
+    --spotlab-hm-track-bg: #e4e4e7;
+    --spotlab-hm-row-passive-bg: rgba(244, 244, 245, 0.4);
+  }
+}
+
+.spotlab-hm-row {
+  display: flex;
+  flex-flow: row nowrap;
+}
+
+.spotlab-hm-cell {
+  aspect-ratio: 1 / 1;
+  width: calc(100% / 13);
+  overflow: hidden;
+  background-color: var(--spotlab-hm-cell-bg);
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+  font-family: var(--spotlab-hm-font-family);
+  font-size: var(--spotlab-hm-font-size);
+  font-weight: var(--spotlab-hm-font-weight);
+  color: var(--spotlab-hm-cell-fg);
+}
+
+.spotlab-hm-cell-inner {
+  display: flex;
+  height: 100%;
+  width: 100%;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+
+.spotlab-hm-sliders {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.spotlab-hm-slider-row {
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--spotlab-hm-radius);
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+  padding: 10px 12px;
+  background: var(--spotlab-hm-surface-bg);
+}
+
+.spotlab-hm-slider-row[data-passive="true"] {
+  background: var(--spotlab-hm-row-passive-bg);
+}
+
+.spotlab-hm-slider-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.spotlab-hm-slider-swatch {
+  flex: none;
+  height: 14px;
+  width: 14px;
+  border-radius: 3px;
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+}
+
+.spotlab-hm-slider-label {
+  flex: 1;
+  font-size: 13px;
+  font-weight: 600;
+  font-family: var(--spotlab-hm-font-family);
+  color: var(--spotlab-hm-cell-fg);
+}
+
+.spotlab-hm-slider-remainder {
+  font-size: 12px;
+  font-weight: 400;
+  color: var(--spotlab-hm-muted-fg);
+}
+
+.spotlab-hm-slider-track-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.spotlab-hm-slider-track {
+  position: relative;
+  flex: 1;
+  height: 8px;
+  cursor: pointer;
+  border-radius: 5px;
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+  touch-action: none;
+}
+
+.spotlab-hm-slider-thumb {
+  position: absolute;
+  top: 50%;
+  height: 16px;
+  width: 16px;
+  transform: translate(-50%, -50%);
+  border-radius: 50%;
+  background: var(--spotlab-hm-surface-bg);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
+}
+
+.spotlab-hm-weight-input {
+  height: 32px;
+  width: 58px;
+  flex: none;
+  padding: 0 6px;
+  text-align: center;
+  font-size: 13px;
+  font-family: var(--spotlab-hm-font-family);
+  color: var(--spotlab-hm-cell-fg);
+  background: transparent;
+  border-radius: calc(var(--spotlab-hm-radius) * 0.5);
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+}

package/dist/hand-matrix.d.ts

@@ -0,0 +1,33 @@
+import { CSSProperties, FC, PointerEvent as ReactPointerEvent } from 'react';
+export declare const CELL_FILL_DIRECTION = "to right";
+export declare const cellFillGradient: (stops: string[]) => string;
+export type CellPointerHandler = (combo: string, event: ReactPointerEvent<HTMLDivElement>) => void;
+type ComboStyleProp = {
+    comboStyle?: (combo: string) => CSSProperties;
+};
+type GridPointerHandlers = {
+    /**
+     * A pointer (mouse, pen or touch) went down on `combo`'s cell. The grid
+     * first releases the implicit pointer capture a touch takes on the element
+     * it starts on, so later moves can resolve to other cells. Passing this
+     * also makes the grid root a drag surface (see `dragSurfaceStyle`).
+     */
+    onPointerDown?: CellPointerHandler;
+    /**
+     * The pointer moved onto `combo`'s cell. Resolved by hit-testing each
+     * `pointermove` (`elementFromPoint`) rather than by enter events, so it
+     * fires across a touch drag, where `mouseenter`/`pointerenter` never reach
+     * the other cells, as well as for a mouse. Fires once per change of cell,
+     * whether or not a button is pressed.
+     */
+    onPointerEnter?: CellPointerHandler;
+};
+/**
+ * The bare 13x13 grid. Each cell carries a `data-combo` attribute. Passing
+ * `onPointerDown` marks the grid as a drag surface (`dragSurfaceStyle`): a
+ * drag reaches the handlers instead of scrolling the page or selecting text.
+ */
+export declare const HandMatrix: FC<{
+    className?: string;
+} & ComboStyleProp & GridPointerHandlers>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { HandMatrix, cellFillGradient, CELL_FILL_DIRECTION, type CellPointerHandler, } from './hand-matrix';
+export { RangeGrid } from './range-grid';
+export { RangeMatrixEditor, type RangeMatrixEditorProps, } from './editor/matrix-editor';
+export { ActionWeightSliders, type ActionWeightSlidersProps, type WeightInputProps, } from './editor/action-sliders';
+export { useRangePainting, type PaintTool } from './editor/use-range-painting';
+export { seedCells, cellsToComboWeights, comboWeightsToCells, type EditorCell, } from './editor/cells';
+export { rebalance, type EditorActionSpec } from './editor/weights';

package/dist/index.js

@@ -0,0 +1,334 @@
+import { useCallback as g, useEffect as y, useLayoutEffect as I, useMemo as x, useRef as v } from "react";
+import { COMBOS as b, parseRange as S, toComboWeights as A } from "@spotlab/range";
+import { jsx as h, jsxs as w } from "react/jsx-runtime";
+var P = (t, e) => Array.from({ length: Math.ceil(t.length / e) }, (n, r) => t.slice(r * e, r * e + e)), D = "to right", N = (t) => t.length === 0 ? "transparent" : `linear-gradient(${D}, ${t.join(", ")})`, W = (t) => {
+  const e = t.target;
+  e.hasPointerCapture(t.pointerId) && e.releasePointerCapture(t.pointerId);
+}, M = (t, e, n) => {
+  const r = t.ownerDocument.elementFromPoint(e, n)?.closest("[data-combo]");
+  return !r || !t.contains(r) ? null : r.getAttribute("data-combo");
+}, T = ({ combo: t, onPointerDown: e, comboStyle: n }) => /* @__PURE__ */ h("div", {
+  className: "spotlab-hm-cell",
+  "data-combo": t,
+  style: n?.(t),
+  onPointerDown: e && ((r) => {
+    W(r), e(t, r);
+  }),
+  children: /* @__PURE__ */ h("div", {
+    className: "spotlab-hm-cell-inner",
+    children: /* @__PURE__ */ h("div", {
+      "data-combo": t,
+      children: t
+    })
+  })
+}), B = ({ row: t, ...e }) => /* @__PURE__ */ h("div", {
+  className: "spotlab-hm-row",
+  children: t.map((n, r) => /* @__PURE__ */ h(T, {
+    combo: n,
+    ...e
+  }, r))
+}), F = {
+  touchAction: "none",
+  userSelect: "none",
+  WebkitUserSelect: "none",
+  WebkitTouchCallout: "none"
+}, R = ({ className: t, onPointerDown: e, onPointerEnter: n, ...r }) => {
+  const a = v(null), o = (i) => {
+    const l = M(i.currentTarget, i.clientX, i.clientY);
+    l !== a.current && (a.current = l, l && n?.(l, i));
+  };
+  return /* @__PURE__ */ h("div", {
+    className: ["spotlab-hm-root", t].filter(Boolean).join(" "),
+    style: e ? F : void 0,
+    onPointerDown: n && ((i) => {
+      a.current = M(i.currentTarget, i.clientX, i.clientY);
+    }),
+    onPointerMove: n && o,
+    onPointerLeave: n && (() => a.current = null),
+    children: P(b, 13).map((i, l) => /* @__PURE__ */ h(B, {
+      row: i,
+      onPointerDown: e,
+      ...r
+    }, l))
+  });
+}, O = (t, e) => ({ background: N([`${t} 0 ${e * 100}%`, `transparent ${e * 100}% 100%`]) }), V = ({ range: t, fill: e = "var(--spotlab-hm-fill)", className: n }) => {
+  const r = x(() => {
+    const a = typeof t == "string" ? S(t) : t;
+    return A(a);
+  }, [t]);
+  return /* @__PURE__ */ h(R, {
+    className: n,
+    comboStyle: (a) => {
+      const o = r.get(a);
+      return o ? O(e, o) : {};
+    }
+  });
+}, X = (t) => Math.max(0, Math.min(100, Math.round(t))), j = (t, e) => {
+  const n = t.map(Math.round);
+  let r = 100 - n.reduce((a, o) => a + o, 0);
+  if (r !== 0) {
+    for (let a = 0; a < n.length; a++) if (a !== e && n[a] + r >= 0) {
+      n[a] += r, r = 0;
+      break;
+    }
+    if (r !== 0) {
+      for (let a = 0; a < n.length; a++) if (a !== e && n[a] > 0) {
+        const o = Math.min(n[a], -r);
+        if (n[a] -= o, r += o, r === 0) break;
+      }
+      n[e] = Math.max(0, n[e] + r);
+    }
+  }
+  return n;
+}, _ = (t, e, n, r) => {
+  const a = X(n), o = t.slice();
+  o[e] = a;
+  const i = 100 - a, l = [];
+  for (let s = 0; s < t.length; s++) s !== e && l.push(s);
+  const u = l.reduce((s, p) => s + t[p], 0);
+  if (u <= 0) {
+    l.forEach((p) => o[p] = 0);
+    const s = e === r ? l[0] : r;
+    s != null && (o[s] = i);
+  } else l.forEach((s) => o[s] = Math.round(t[s] / u * i));
+  return j(o, e);
+}, $ = (t, e) => t.reduce((n, r, a) => a === e ? n : n + r, 0), k = new Map(b.map((t, e) => [t, e])), L = (t, e) => {
+  const n = t.slice();
+  let r = $(n, e);
+  if (r > 100) {
+    const a = 100 / r;
+    for (let o = 0; o < n.length; o++) o !== e && (n[o] = Math.round(n[o] * a));
+    r = $(n, e);
+  }
+  return n[e] = Math.max(0, 100 - r), n;
+};
+function Z(t, e, n) {
+  return b.map((r) => {
+    const a = t ? t.get(r) ?? 0 : 1, o = e.map(() => 0);
+    return a <= 0 ? (o[n] = 100, {
+      avail: 0,
+      weights: o
+    }) : (e.forEach((i, l) => {
+      const u = i?.get(r) ?? 0;
+      o[l] = Math.round(u / a * 100);
+    }), {
+      avail: a,
+      weights: L(o, n)
+    });
+  });
+}
+var q = 8;
+function z(t, e) {
+  const n = /* @__PURE__ */ new Map();
+  return t.forEach((r, a) => {
+    if (r.avail <= 0) return;
+    const o = r.weights.reduce((l, u) => l + u, 0);
+    if (!o) return;
+    const i = Number((r.weights[e] / o * r.avail).toFixed(q));
+    i && n.set(b[a], i);
+  }), n;
+}
+function tt(t, e, n) {
+  return t.map((r, a) => {
+    const o = e.map(() => 0);
+    if (r.avail <= 0)
+      return o[n] = 100, {
+        avail: r.avail,
+        weights: o
+      };
+    const i = b[a];
+    return e.forEach((l, u) => {
+      const s = l?.get(i) ?? 0;
+      o[u] = Math.round(s / r.avail * 100);
+    }), {
+      avail: r.avail,
+      weights: L(o, n)
+    };
+  });
+}
+function G(t) {
+  const { cells: e, brush: n, tool: r, onCellsChange: a, onBrushChange: o, onToolChange: i } = t, l = v(null), u = g(() => {
+    l.current?.abort(), l.current = null;
+  }, []);
+  y(() => u, [u]);
+  const s = v(e);
+  I(() => {
+    s.current = e;
+  }, [e]);
+  const p = g((c) => {
+    const d = s.current, f = k.get(c);
+    if (d[f].avail <= 0) return;
+    const C = d.slice();
+    C[f] = {
+      avail: d[f].avail,
+      weights: [...n]
+    }, s.current = C, a(C);
+  }, [n, a]), m = g((c) => {
+    const d = k.get(c);
+    e[d].avail <= 0 || (o([...e[d].weights]), i("brush"));
+  }, [
+    e,
+    o,
+    i
+  ]);
+  return {
+    onCellDown: g((c) => {
+      if (r === "eyedropper") {
+        m(c);
+        return;
+      }
+      u();
+      const d = new AbortController();
+      l.current = d, window.addEventListener("pointerup", u, { signal: d.signal }), window.addEventListener("pointercancel", u, { signal: d.signal }), p(c);
+    }, [
+      r,
+      m,
+      p,
+      u
+    ]),
+    onCellEnter: g((c) => {
+      l.current && r === "brush" && p(c);
+    }, [r, p])
+  };
+}
+var E = (t, e, n) => {
+  const r = [];
+  let a = 0;
+  return n.forEach((o) => {
+    const i = (t.weights[o] || 0) / 100;
+    if (i <= 0) return;
+    const l = e[o].color;
+    r.push(`${l} ${a * 100}%`), r.push(`${l} ${(a + i) * 100}%`), a += i;
+  }), r.length > 0 && a < 1 - 1e-9 && r.push(`transparent ${a * 100}% 100%`), N(r);
+}, et = ({ cells: t, actions: e, order: n, brush: r, tool: a, onCellsChange: o, onBrushChange: i, onToolChange: l, className: u }) => {
+  const { onCellDown: s, onCellEnter: p } = G({
+    cells: t,
+    brush: r,
+    tool: a,
+    onCellsChange: o,
+    onBrushChange: i,
+    onToolChange: l
+  });
+  return /* @__PURE__ */ h(R, {
+    className: u,
+    comboStyle: (m) => {
+      const c = t[k.get(m)];
+      if (c.avail <= 0) return {
+        background: "var(--spotlab-hm-dead-hatch)",
+        backgroundColor: "var(--spotlab-hm-muted-bg)",
+        cursor: "not-allowed",
+        color: "var(--spotlab-hm-muted-fg)"
+      };
+      const d = a === "eyedropper" ? "copy" : "pointer";
+      if (c.avail < 1) {
+        const f = `${c.avail * 100}%`;
+        return {
+          background: `repeating-linear-gradient(180deg, var(--spotlab-hm-muted-fg) 0 4px, transparent 4px 8px), var(--spotlab-hm-dead-hatch), ${E(c, e, n)}`,
+          backgroundSize: `1px 100%, ${(1 - c.avail) * 100}% 100%, ${c.avail * 100}% 100%`,
+          backgroundPosition: `${f} center, right center, left center`,
+          backgroundRepeat: "no-repeat, no-repeat, no-repeat",
+          cursor: d
+        };
+      }
+      return {
+        background: E(c, e, n),
+        cursor: d
+      };
+    },
+    onPointerDown: s,
+    onPointerEnter: p
+  });
+}, U = (t) => /* @__PURE__ */ h("input", {
+  type: "number",
+  className: "spotlab-hm-weight-input",
+  ...t
+}), Y = ({ value: t, color: e, passive: n, onChange: r }) => {
+  const a = v(null), o = v(!1), i = g((l) => {
+    const u = a.current;
+    if (!u) return;
+    const s = u.getBoundingClientRect();
+    r((l - s.left) / s.width * 100);
+  }, [r]);
+  return y(() => {
+    const l = (s) => {
+      o.current && i(s.clientX);
+    }, u = () => o.current = !1;
+    return window.addEventListener("pointermove", l), window.addEventListener("pointerup", u), () => {
+      window.removeEventListener("pointermove", l), window.removeEventListener("pointerup", u);
+    };
+  }, [i]), /* @__PURE__ */ h("div", {
+    ref: a,
+    role: "slider",
+    "aria-valuenow": t,
+    "aria-valuemin": 0,
+    "aria-valuemax": 100,
+    className: "spotlab-hm-slider-track",
+    style: { background: `linear-gradient(to right, ${e} 0 ${t}%, var(--spotlab-hm-track-bg) ${t}% 100%)` },
+    onPointerDown: (l) => {
+      o.current = !0, i(l.clientX);
+    },
+    children: /* @__PURE__ */ h("div", {
+      className: "spotlab-hm-slider-thumb",
+      style: {
+        left: `${t}%`,
+        border: `2px solid ${n ? "var(--spotlab-hm-muted-fg)" : e}`
+      }
+    })
+  });
+}, H = (t, e) => /* @__PURE__ */ w("span", {
+  className: "spotlab-hm-slider-label",
+  children: [t.label, e && /* @__PURE__ */ h("span", {
+    className: "spotlab-hm-slider-remainder",
+    children: " · remainder"
+  })]
+}), rt = ({ actions: t, order: e, weights: n, passive: r, onWeightsChange: a, renderActionLabel: o, renderActionExtra: i, components: l, className: u }) => {
+  const s = l?.WeightInput ?? U, p = (m, c) => {
+    a(_(n, m, c, r));
+  };
+  return /* @__PURE__ */ h("div", {
+    className: ["spotlab-hm-root spotlab-hm-sliders", u].filter(Boolean).join(" "),
+    children: e.map((m) => {
+      const c = t[m], d = m === r;
+      return /* @__PURE__ */ w("div", {
+        className: "spotlab-hm-slider-row",
+        "data-passive": d,
+        children: [/* @__PURE__ */ w("div", {
+          className: "spotlab-hm-slider-header",
+          children: [
+            /* @__PURE__ */ h("span", {
+              className: "spotlab-hm-slider-swatch",
+              style: { background: c.color }
+            }),
+            o?.(c, m, d) ?? H(c, d),
+            i?.(c, m)
+          ]
+        }), /* @__PURE__ */ w("div", {
+          className: "spotlab-hm-slider-track-row",
+          children: [/* @__PURE__ */ h(Y, {
+            value: n[m],
+            color: c.color,
+            passive: d,
+            onChange: (f) => p(m, f)
+          }), /* @__PURE__ */ h(s, {
+            value: n[m],
+            "aria-label": `${c.label} weight`,
+            onChange: (f) => p(m, parseInt(f.target.value || "0", 10))
+          })]
+        })]
+      }, c.id);
+    })
+  });
+};
+export {
+  rt as ActionWeightSliders,
+  D as CELL_FILL_DIRECTION,
+  R as HandMatrix,
+  V as RangeGrid,
+  et as RangeMatrixEditor,
+  N as cellFillGradient,
+  z as cellsToComboWeights,
+  tt as comboWeightsToCells,
+  _ as rebalance,
+  Z as seedCells,
+  G as useRangePainting
+};

package/dist/range-grid.d.ts

@@ -0,0 +1,13 @@
+import { FC } from 'react';
+import { HandFrequency } from '@spotlab/range';
+/**
+ * A read-only 13x13 range grid: each cell fills to its combo's mean weight.
+ * Accepts the expanded hand-keyed form or a range string directly — a range
+ * string is parsed via `@spotlab/range`, so the caller never needs to touch
+ * the parser itself to render one.
+ */
+export declare const RangeGrid: FC<{
+    range: HandFrequency[] | string;
+    fill?: string;
+    className?: string;
+}>;

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@spotlab/hand-matrix",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A 13x13 poker hand-matrix React component: the read-only grid primitive and a range-string-aware display component, themed through CSS custom properties.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mAAdhaTTah/spotlab",
+    "directory": "packages/hand-matrix"
+  },
+  "homepage": "https://github.com/mAAdhaTTah/spotlab/tree/main/packages/hand-matrix#readme",
+  "bugs": {
+    "url": "https://github.com/mAAdhaTTah/spotlab/issues"
+  },
+  "author": "James DiGioia",
+  "keywords": [
+    "poker",
+    "range",
+    "hand-matrix",
+    "react",
+    "component",
+    "texas-holdem"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./dist/hand-matrix.css"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@spotlab/range": "^0.2.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@spotlab/range": "0.2.0",
+    "@storybook/addon-vitest": "^10.5.5",
+    "@storybook/react-vite": "^10.5.5",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "4.1.11",
+    "playwright": "^1.49.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "storybook": "^10.5.5",
+    "typescript": "^6.0.0",
+    "vite": "^8.3.1",
+    "vite-plugin-dts": "^5.1.2",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build:vite": "vite build",
+    "build:css": "node scripts/copy-css.mjs",
+    "build": "pnpm typecheck && pnpm build:vite && pnpm build:css",
+    "test": "vitest run --project unit",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build",
+    "test-storybook": "NODE_ENV=production vitest run --project storybook"
+  }
 }