@spotlab/hand-matrix 0.4.0 → 0.5.0

package/README.md

@@ -5,13 +5,13 @@ and [`@spotlab/range`](../range) — no Tailwind, no bundler-plugin
 requirement.
 
 ```tsx
-import { RangeGrid } from "@spotlab/hand-matrix";
+import { RangeMatrix, rangeToMatrix } 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" />;
+<RangeMatrix {...rangeToMatrix("AKs:0.5,QQ")} />;
 ```
 
 ## Exports
@@ -20,31 +20,33 @@ 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
+- `RangeMatrix` — the read-only grid, for one range or several actions at
+  once, drawn exactly as `RangeMatrixEditor` draws it but without painting.
+  Each cell stacks its actions' weights as colored bands, dead cells
+  (`avail` 0) are hatched, and capped cells (`avail` below 1) show a cap
+  line with the rest hatched. Each cell carries a `data-combo` attribute.
+  Props (`RangeMatrixProps`):
+  - `cells: EditorCell[]` — one per combo, in `@spotlab/range`'s `COMBOS`
+    order (see [Editing](#editing)).
+  - `actions: EditorActionSpec[]` — index-aligned with each cell's
+    `weights`.
+  - `order: number[]` — indices into `actions`, in the order bands stack.
+    An action left out isn't drawn, so its share of a cell stays
+    transparent; include it to give it a color.
+  - `className?: string`.
+- `rangeToMatrix(range, { color?, labels? }): RangeMatrixProps` (without
+  `className`) — `RangeMatrix`'s props for drawing one range:
+  `<RangeMatrix {...rangeToMatrix(range)} />`. Takes a range string (parsed
+  via `@spotlab/range`) or the expanded `HandFrequency[]` form, and fills
+  each cell to its combo's mean weight in `color` (default
+  `var(--spotlab-hm-fill)`), leaving the rest blank. The returned `actions`
+  are `in` and `out`, labeled by `labels.in` (default `"In range"`) and
+  `labels.out` (default `"Out of range"`), for building your own legend.
+  Memoize the result (e.g. `useMemo`) rather than calling it on every
+  render.
+
+`rangeToMatrix`'s parse and combo collapse (`toComboWeights`) are wasm
+calls, so `initRange()` must have resolved before calling it — see
 [`@spotlab/range`](../range)'s own README for why that call is explicit
 rather than automatic.
 
@@ -55,9 +57,8 @@ 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.
+- `RangeMatrixEditor` — the paintable grid: `RangeMatrix`'s cells with
+  brush/eyedropper painting wired on for mouse and touch.
   Props (`RangeMatrixEditorProps`):
   - `cells: EditorCell[]` and `onCellsChange(cells)`.
   - `actions: EditorActionSpec[]` — index-aligned with each cell's
@@ -85,9 +86,9 @@ goes in as props and changes come out through `on*Change` callbacks.
 - `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`.
+  `{ onCellDown(combo), onCellEnter(combo) }`: call `onCellDown` when a
+  pointer goes down on a cell and `onCellEnter` each time it moves onto
+  another one. 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
@@ -115,7 +116,7 @@ goes in as props and changes come out through `on*Change` callbacks.
   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`,
+  `RangeMatrixEditorProps`, `ActionWeightSlidersProps`,
   `WeightInputProps`.
 
 **The editor works at combo level.** A cell is one of the 169 combos (`AKs`,
@@ -133,7 +134,7 @@ 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" />`
+class that sets variables works there too (`<RangeMatrix className="my-theme" … />`
 with `.my-theme { --spotlab-hm-border: … }`), in addition to the
 `.spotlab-hm-root` selector form below.
 
@@ -195,9 +196,10 @@ Available variables: `--spotlab-hm-border`, `--spotlab-hm-border-width`,
 `--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.
+Action colors (each `EditorActionSpec`'s `color`, or `rangeToMatrix`'s
+`color` option) are **not** theme variables — they are data, passed as props.
+`--spotlab-hm-fill` is only the default `rangeToMatrix` uses when `color` is
+omitted.
 
 ## License
 

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

@@ -1,24 +1,17 @@
 import { FC } from 'react';
+import { MatrixDisplayProps } from '../hand-matrix';
 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[];
+export type RangeMatrixEditorProps = MatrixDisplayProps & {
     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.
+ * The paintable 13x13 range grid: `RangeMatrix`'s cells with brush/eyedropper
+ * painting wired onto them. Fully controlled; `useRangePainting` drives the
+ * state changes.
  */
 export declare const RangeMatrixEditor: FC<RangeMatrixEditorProps>;

package/dist/hand-matrix.d.ts

@@ -1,10 +1,7 @@
 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;
-};
+import { EditorCell } from './editor/cells';
+import { EditorActionSpec } from './editor/weights';
+type CellPointerHandler = (combo: string, event: ReactPointerEvent<HTMLDivElement>) => void;
 type GridPointerHandlers = {
     /**
      * A pointer (mouse, pen or touch) went down on `combo`'s cell. The grid
@@ -22,12 +19,29 @@ type GridPointerHandlers = {
      */
     onPointerEnter?: CellPointerHandler;
 };
+/** The cell data both `RangeMatrix` and `RangeMatrixEditor` draw from. */
+export type MatrixDisplayProps = {
+    /** 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. An
+     * action left out isn't drawn, so its share of a cell stays transparent.
+     */
+    order: number[];
+    className?: string;
+};
 /**
- * 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.
+ * The 13x13 grid that `RangeMatrix` and `RangeMatrixEditor` both render, so
+ * the two draw cells identically: each cell stacks its actions' weights as
+ * bands in `order`, with dead and capped cells marked. Each cell carries a
+ * `data-combo` attribute. The editor adds a per-cell cursor and the painting
+ * handlers; passing `onPointerDown` also makes the grid a drag surface
+ * (`dragSurfaceStyle`), so a drag reaches the handlers instead of scrolling
+ * the page or selecting text. Internal: not exported from the package root.
  */
-export declare const HandMatrix: FC<{
-    className?: string;
-} & ComboStyleProp & GridPointerHandlers>;
+export declare const HandMatrix: FC<MatrixDisplayProps & GridPointerHandlers & {
+    cursorOf?: (cell: EditorCell) => CSSProperties["cursor"];
+}>;
 export {};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { HandMatrix, cellFillGradient, CELL_FILL_DIRECTION, type CellPointerHandler, } from './hand-matrix';
-export { RangeGrid } from './range-grid';
+export { RangeMatrix, type RangeMatrixProps } from './range-matrix';
+export { rangeToMatrix } from './range-to-matrix';
 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';

package/dist/index.js

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

package/dist/range-matrix.d.ts

@@ -0,0 +1,10 @@
+import { FC } from 'react';
+import { MatrixDisplayProps } from './hand-matrix';
+export type RangeMatrixProps = MatrixDisplayProps;
+/**
+ * A read-only 13x13 grid of several actions at once: each cell stacks its
+ * actions' weights as colored bands in `order`, hatches dead cells (`avail`
+ * 0), and marks capped cells (`avail` below 1) with a cap line and hatched
+ * remainder. Draws exactly what `RangeMatrixEditor` does, without painting.
+ */
+export declare const RangeMatrix: FC<RangeMatrixProps>;

package/dist/range-to-matrix.d.ts

@@ -0,0 +1,19 @@
+import { HandFrequency } from '@spotlab/range';
+import { RangeMatrixProps } from './range-matrix';
+/**
+ * `RangeMatrix`'s props for drawing one range: every cell is fully available
+ * and filled to its combo's mean weight in `color` (default
+ * `var(--spotlab-hm-fill)`), with the rest left blank. The two actions are
+ * `in` and `out`, labeled `labels.in` (default "In range") and `labels.out`
+ * (default "Out of range") for a legend of your own. Takes a range string or
+ * its expanded hand-keyed form; a string is parsed via `@spotlab/range`, so
+ * `initRange()` must have resolved. Parsing and collapsing are wasm calls, so
+ * memoize the result rather than calling this on every render.
+ */
+export declare function rangeToMatrix(range: HandFrequency[] | string, { color, labels, }?: {
+    color?: string;
+    labels?: {
+        in?: string;
+        out?: string;
+    };
+}): Omit<RangeMatrixProps, "className">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spotlab/hand-matrix",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/dist/range-grid.d.ts

@@ -1,13 +0,0 @@
-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;
-}>;