@ntmats/hc-ui 0.9.0 → 0.11.0

package/README.md

@@ -95,4 +95,4 @@ Fixed colors that stay the same in both themes are HeroClix tokens: `color-dial-
 
 `PhysicalCardView` is the printed card in HCUnits' format (375×525 px, absolute positions), scaled to its container's width: front and back side by side while each keeps about 86% of its size, otherwise one under the other, never above 1.2×. With `fitHeight` the front also fits the visible height of the scrolling area found by `fitHeightWithin`. Everything comes resolved: the backgrounds (`images.front`, `images.back`, `images.legacy`, `layout.rarityImage`, `layout.dialImage`: addresses the app serves; HCUI's are in its `public/card/` and do not ship here), the title (its type shrinks from 28px to fit), header lines, team abilities (buttons that open a tip, with the shield the caller passes in `teamAbilityIcon`), the collection number and set symbol, the token (`portrait` drawn by the caller with the class the card gives, `terrain` art or an `object` ring in its color), the bystander's token replica, keyphrases, the rules (already translated, with an optional `icon`; tapping a paragraph calls `onCopy(copyText)`), improved abilities, the printed dial as a node (`dial.node`, usually `CombatDialView` with `presentation="printed"`), the terrain dial, points (buttons that call `onSelectPoint`, an object's line or nothing) and the black back bar. Rules that do not fit the front move to the backs, two columns each, one block at a time (`nextPhysicalCardDistribution`); the split starts over when `contentKey` changes. Under a mouse the card tilts up to 3° toward the pointer, with parallax and a shine (nearly still over the dial); on a phone only the focus view moves, by the motion sensor (`requestPhysicalCardMotionAccess` asks iOS on the first touch). Holding the card with a finger for 450 ms calls `onRequestFocus`; the caller opens `PhysicalCardFocusView` (a modal `<dialog>` over a dimmed, blurred backdrop; Esc and a tap outside, once the opening finger is lifted, call `onClose`) with a second card with `focus`, which shows one side at a time and draws `focusActions({ nextSide, backs, flip })` under it (the library's `Button` `outline` there gets the surface fill). Tips are controlled as in the dial: hover with a mouse opens a passive tip described by the control, a press or Enter opens it as a dialog, leaving closes the passive one; the caller keeps `tip` and draws it in `tipSlot`. Paper, ink, shine and grain follow the theme (`color-card-*`, `filter-card-background`, `blend-card-*`, `opacity-card-grain*`); the printed black and white, the team-up band and the terrain dial are fixed (`color-card-print-*`, `color-card-team-up`, `color-card-terrain-panel*`). Letters are upright (`--hc-rond: 0` on the card, which its printed dial reads too). Motion only with a fine pointer or in the phone's focus view, and none under `prefers-reduced-motion`.
 
-`MapBoardView` draws a map already fetched (`map`: the hcmaps JSON, `HCMapJson`) with the hcmaps engine (`HCMap`) in a canvas named by `canvasLabel`, square-cornered and white in both themes (`color-map-board`), and shades the inspected square or draws the inspected edge (`selection`, from `inspectMap`; `color-map-selection*`). `onInspect(x, y, clientX, clientY)` gets the pointer in squares: mouse and pen while passing over, touch on press; `onLeave` when the mouse leaves. Other attributes (role, `tabIndex`, `onKeyDown`, `aria-*`) go to the container, so the caller adds the keyboard (HCUI: arrows move one square, Esc closes). `MapBoardPlaceholder` is the empty grid while it loads, a busy status whose `label` is visually hidden by the library. `MapTooltipView` is fixed next to `anchor` without leaving the screen (portal it out of a clipping container): the title, a wall's color, and for each square (one, or two on an edge) its coordinate, terrain and elevation swatches with the caller's names, the environment (a node, e.g. `MapEnvironmentView`, or `environmentNote`) and notes. `MapSwatch` is the board's square in a legend; `MapLegendView` lists them (the 3D model's legend) with children after; `MapEnvironmentView` shows indoor/outdoor with the caller's icons (black line icons, turned light in the dark theme by `filter-map-environment-icon`) and names. `renderMapThumbnail(json, height)` returns a PNG data URL. The engines are plain functions with no DOM beyond a canvas context: `inspectMap` (square, edge or wall at a point, in squares), `mapSquare`, `mapMaxLevel`, `mapElevationLevel`, `mapSquareCoordinate`; `buildMapScene` (the 3D model's heights, walls, ramps and ziplines), the orthographic camera (`makeMapProjection`, `pickMapScene`, `zoomMapCamera`, `clampMapPan`) and `drawMapScene` (Canvas 2D). The 3D model's component, its gestures and its icons stay in the app.
+`MapBoardView` draws a map already fetched (`map`: the hcmaps JSON, `HCMapJson`) with the hcmaps engine (`HCMap`) in a canvas named by `canvasLabel`, square-cornered and white in both themes (`color-map-board`), and shades the inspected square or draws the inspected edge (`selection`, from `inspectMap`; `color-map-selection*`). `onInspect(x, y, clientX, clientY)` gets the pointer in squares: mouse and pen while passing over, touch on press; `onLeave` when the mouse leaves. Other attributes (role, `tabIndex`, `onKeyDown`, `aria-*`) go to the container, so the caller adds the keyboard (HCUI: arrows move one square, Esc closes). `MapBoardPlaceholder` is the empty grid while it loads, a busy status whose `label` is visually hidden by the library. `MapTooltipView` is fixed next to `anchor` without leaving the screen (portal it out of a clipping container): the title, a wall's color, and for each square (one, or two on an edge) its coordinate, terrain and elevation swatches with the caller's names, the environment (a node, e.g. `MapEnvironmentView`, or `environmentNote`) and notes. `MapSwatch` is the board's square in a legend; `MapLegendView` lists them (the 3D model's legend) with children after; `MapEnvironmentView` shows indoor/outdoor with the caller's icons (black line icons, turned light in the dark theme by `filter-map-environment-icon`) and names. `renderMapThumbnail(json, height)` returns a PNG data URL. The engines are plain functions with no DOM beyond a canvas context: `inspectMap` (square, edge or wall at a point, in squares), `mapSquare`, `mapMaxLevel`, `mapElevationLevel`, `mapSquareCoordinate`; `buildMapScene` (the 3D model's heights, walls, ramps and ziplines), the camera (`makeMapProjection`, `pickMapScene`, `zoomMapCamera`, `clampMapPan`) and `drawMapScene` (Canvas 2D). The camera is parallel by default; `makeMapProjection(scene, camera, viewport, { perspective: MAP_PERSPECTIVE_DISTANCE })` adds a light perspective (near squares larger, far ones smaller) in the same screen box, with `ground` still exact and `factor(x, y, z)` telling how much a point grew, e.g. to size a figure drawn over the model. `MapBoardView` draws again when the browser gives its canvas back blank (`contextrestored`). `drawMapScene(..., { decorate })` lets the app paint a side over its default face (`side(ctx, face)`, with the face's screen `quad`) and draw what stands on a square right after it in the painter's order (`cell(ctx, cell)`), or draw a ramp its own way (`ramp(ctx, ramp)` returning `true`), e.g. facades, props and stairs, without changing terrain or picking. The 3D model's component, its gestures and its icons stay in the app.

package/dist/index.d.ts

@@ -1512,8 +1512,24 @@ export interface MapProjection {
     depth(x: number, y: number): number;
     /** From the screen to the map, on a plane at height `z`. */
     ground(px: number, py: number, z: number): [number, number];
+    /**
+     * How much a point at (x, y, z) is enlarged on screen compared with the parallel
+     * projection: above 1 near the camera, below 1 far from it. Always 1 without
+     * `perspective`. Optional so hand-made projections still type-check.
+     */
+    factor?(x: number, y: number, z: number): number;
+}
+export interface MapProjectionOptions {
+    /**
+     * A light perspective, as the camera's distance in half-diagonals of the scene
+     * (`MAP_PERSPECTIVE_DISTANCE` = 4; larger is gentler). Off by default: a parallel
+     * projection, where near and far squares are the same size.
+     */
+    perspective?: number;
 }
-export declare function makeMapProjection(scene: MapScene, camera: MapCamera, viewport: MapViewport): MapProjection;
+/** The camera distance the Arena's table uses for `perspective`. */
+export declare const MAP_PERSPECTIVE_DISTANCE = 4;
+export declare function makeMapProjection(scene: MapScene, camera: MapCamera, viewport: MapViewport, { perspective }?: MapProjectionOptions): MapProjection;
 /** The map's center may go as far as any of its corners reaches the middle of the screen. */
 export declare function clampMapPan(scene: MapScene, camera: MapCamera, viewport: MapViewport): MapCamera;
 /** Zooms keeping the point at `anchor` (measured from the screen's center) still. */
@@ -1575,6 +1591,31 @@ export declare function mapFootprintOutline({ x, y, width, height, cells }: {
     edges: [Point, Point][];
     corners: Point[];
 };
+/** A square's visible side, as `drawMapScene` draws it: from the neighbor's top (`low`) to the square's. */
+export interface MapSceneFace {
+    cell: MapSceneCell;
+    /** The side's outward direction (one of `MAP_CELL_SIDES`). */
+    dx: number;
+    dy: number;
+    low: number;
+    top: number;
+    /** Screen corners: low at the side's start, low at its end, top at its end, top at its start. */
+    quad: [[number, number], [number, number], [number, number], [number, number]];
+    /** How lit the side is, 0..1 (the default face is shaded by it). */
+    light: number;
+}
+/**
+ * What the app adds to the 3D model, in the painter's order of `drawMapScene`: a side
+ * drawn over the default face (a facade, a wall's stones), and whatever stands on a
+ * square, drawn right after that square (a car, a tree, a pillar), so nearer squares
+ * and walls still cover it. Terrain, heights and picking do not change.
+ */
+export interface MapSceneDecoration {
+    side?(ctx: CanvasRenderingContext2D, face: MapSceneFace): void;
+    cell?(ctx: CanvasRenderingContext2D, cell: MapSceneCell): void;
+    /** Draws a ramp (e.g. as stairs) in place of the default wedge; return `true` when it did. */
+    ramp?(ctx: CanvasRenderingContext2D, ramp: MapSceneRamp): boolean;
+}
 export interface MapSceneFootprint {
     x: number;
     y: number;
@@ -1599,8 +1640,9 @@ export interface MapSceneHighlight {
     /** The target of a piece being moved: floor and volume, cut to the board. */
     footprint?: MapSceneFootprint;
 }
-export declare function drawMapScene(ctx: CanvasRenderingContext2D, scene: MapScene, view: MapProjection, texture: HTMLCanvasElement, highlight?: MapSceneHighlight | null, { tufts }?: {
+export declare function drawMapScene(ctx: CanvasRenderingContext2D, scene: MapScene, view: MapProjection, texture: HTMLCanvasElement, highlight?: MapSceneHighlight | null, { tufts, decorate }?: {
     tufts?: boolean;
+    decorate?: MapSceneDecoration;
 }): void;
 /** The thumbnail's default height, in pixels. */
 export declare const MAP_THUMBNAIL_HEIGHT = 192;

package/dist/index.js

@@ -2758,7 +2758,8 @@ var MAP_DEFAULT_CAMERA = { azimuth: -32, tilt: 52, zoom: 1, panX: 0, panY: 0 };
 var MAP_TILT_RANGE = [6, 90];
 var MAP_ZOOM_RANGE = [1, 6];
 var clampMapValue = (value, min, max) => Math.min(max, Math.max(min, value));
-function makeMapProjection(scene, camera, viewport) {
+var MAP_PERSPECTIVE_DISTANCE = 4;
+function makeMapProjection(scene, camera, viewport, { perspective } = {}) {
   const rad = camera.azimuth * Math.PI / 180, tilt = camera.tilt * Math.PI / 180;
   const sin = Math.sin(rad), cos = Math.cos(rad), sinT = Math.sin(tilt), cosT = Math.cos(tilt);
   const cx2 = scene.width / 2, cy = scene.height / 2, midZ = (scene.maxTop + MAP_SCENE_BASE_Z) / 2;
@@ -2767,7 +2768,7 @@ function makeMapProjection(scene, camera, viewport) {
   const fit = Math.min(viewport.width / (halfWidth * 2.06), viewport.height / (halfHeight * 2.06));
   const scale = fit * camera.zoom;
   const ox = viewport.width / 2 + camera.panX, oy = viewport.height / 2 + camera.panY;
-  return {
+  const parallel = {
     scale,
     sin,
     cos,
@@ -2781,6 +2782,44 @@ function makeMapProjection(scene, camera, viewport) {
     ground(px, py, z) {
       const rx = (px - ox) / scale, ry = ((py - oy) / scale + (z - midZ) * cosT) / sinT;
       return [cx2 + rx * cos + ry * sin, cy - rx * sin + ry * cos];
+    },
+    factor: () => 1
+  };
+  if (!perspective || !(perspective > 0)) return parallel;
+  const [sx, sy] = parallel.point(cx2, cy, midZ);
+  const D = perspective * Math.max(1, halfWidth, (scene.maxTop - MAP_SCENE_BASE_Z) / 2);
+  const toward = (x, y, z) => parallel.depth(x, y) * cosT + (z - midZ) * sinT;
+  const raw = (x, y, z) => D / Math.max(D * 0.05, D - toward(x, y, z));
+  const corners = [[0, 0], [scene.width, 0], [scene.width, scene.height], [0, scene.height]];
+  const extremes = corners.flatMap(([x, y]) => [[x, y, scene.maxTop], [x, y, MAP_SCENE_BASE_Z]]);
+  const box = (points) => {
+    const xs = points.map((p) => p[0]), ys = points.map((p) => p[1]);
+    return [Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys)];
+  };
+  const [flatW, flatH] = box(extremes.map(([x, y, z]) => parallel.point(x, y, z)));
+  const [deepW, deepH] = box(extremes.map(([x, y, z]) => {
+    const [px, py] = parallel.point(x, y, z), f = raw(x, y, z);
+    return [sx + (px - sx) * f, sy + (py - sy) * f];
+  }));
+  const norm = Math.max(flatW > 1e-9 ? deepW / flatW : 0, flatH > 1e-9 ? deepH / flatH : 0) || 1;
+  const factor = (x, y, z) => raw(x, y, z) / norm;
+  return {
+    scale,
+    sin,
+    cos,
+    factor,
+    depth: parallel.depth,
+    point(x, y, z) {
+      const [px, py] = parallel.point(x, y, z), f = factor(x, y, z);
+      return [sx + (px - sx) * f, sy + (py - sy) * f];
+    },
+    ground(px, py, z) {
+      const zc = z - midZ;
+      const v = (py - sy) / scale * norm;
+      const denom = D * sinT + v * cosT;
+      const along = Math.abs(denom) < 1e-9 ? 0 : (v * D - v * zc * sinT + zc * cosT * D) / denom;
+      const f = D / Math.max(D * 0.05, D - along * cosT - zc * sinT) / norm;
+      return parallel.ground(sx + (px - sx) / f, sy + (py - sy) / f, z);
     }
   };
 }
@@ -2834,11 +2873,9 @@ function pickMapScene(scene, view, px, py) {
         const p00 = view.point(cell.x, cell.y, cell.top), p10 = view.point(cell.x + 1, cell.y, cell.top);
         const p11 = view.point(cell.x + 1, cell.y + 1, cell.top), p01 = view.point(cell.x, cell.y + 1, cell.top);
         if (inside(px, py, [p00, p10, p11, p01])) {
-          const ax = p10[0] - p00[0], ay = p10[1] - p00[1], bx = p01[0] - p00[0], by = p01[1] - p00[1];
-          const det = ax * by - ay * bx;
-          if (!det) return { x: cell.x + 0.5, y: cell.y + 0.5 };
-          const u = ((px - p00[0]) * by - (py - p00[1]) * bx) / det, v = ((py - p00[1]) * ax - (px - p00[0]) * ay) / det;
-          return { x: cell.x + clampMapValue(u, 0, 1), y: cell.y + clampMapValue(v, 0, 1) };
+          const [gx, gy] = view.ground(px, py, cell.top);
+          if (!Number.isFinite(gx) || !Number.isFinite(gy)) return { x: cell.x + 0.5, y: cell.y + 0.5 };
+          return { x: clampMapValue(gx, cell.x, cell.x + 1), y: clampMapValue(gy, cell.y, cell.y + 1) };
         }
         for (const side of MAP_CELL_SIDES) {
           if (side.dx * view.sin + side.dy * view.cos <= 0) continue;
@@ -2925,7 +2962,7 @@ function sideColor(cell) {
   if (cell.terrain === "window") return MAP_TERRAIN_EDGE_COLORS.window;
   return SIDE_COLORS[cell.environment] ?? SIDE_COLORS.unknown;
 }
-function drawCellSides(ctx, scene, view, cell) {
+function drawCellSides(ctx, scene, view, cell, decorate) {
   const { point } = view;
   for (const side of MAP_CELL_SIDES) {
     if (side.dx * view.sin + side.dy * view.cos <= 0) continue;
@@ -2934,7 +2971,13 @@ function drawCellSides(ctx, scene, view, cell) {
     if (low >= cell.top) continue;
     const ax = cell.x + side.ax, ay = cell.y + side.ay, bx = cell.x + side.bx, by = cell.y + side.by;
     const light = faceLight(view, side.dx, side.dy);
-    face(ctx, [point(ax, ay, low), point(bx, by, low), point(bx, by, cell.top), point(ax, ay, cell.top)], shade(sideColor(cell), light));
+    const quad = [point(ax, ay, low), point(bx, by, low), point(bx, by, cell.top), point(ax, ay, cell.top)];
+    face(ctx, quad, shade(sideColor(cell), light));
+    if (decorate?.side) {
+      ctx.save();
+      decorate.side(ctx, { cell, dx: side.dx, dy: side.dy, low, top: cell.top, quad, light });
+      ctx.restore();
+    }
     ctx.strokeStyle = "rgba(0,0,0,.26)";
     ctx.lineWidth = 1;
     for (let z = 0; z < cell.top - 0.01; z += MAP_SCENE_LEVEL_HEIGHT) {
@@ -3116,7 +3159,7 @@ function drawHighlight(ctx, scene, view, highlight) {
   ctx.lineWidth = 2;
   ctx.stroke();
 }
-function drawMapScene(ctx, scene, view, texture, highlight, { tufts = true } = {}) {
+function drawMapScene(ctx, scene, view, texture, highlight, { tufts = true, decorate } = {}) {
   const pad = 0.35;
   polygon(ctx, [view.point(-pad, -pad, MAP_SCENE_BASE_Z - 0.16), view.point(scene.width + pad, -pad, MAP_SCENE_BASE_Z - 0.16), view.point(scene.width + pad, scene.height + pad, MAP_SCENE_BASE_Z - 0.16), view.point(-pad, scene.height + pad, MAP_SCENE_BASE_Z - 0.16)]);
   ctx.fillStyle = "rgba(0,0,0,.14)";
@@ -3139,11 +3182,24 @@ function drawMapScene(ctx, scene, view, texture, highlight, { tufts = true } = {
     items.push({
       depth: view.depth(cell.x + 0.5, cell.y + 0.5),
       draw() {
-        drawCellSides(ctx, scene, view, cell);
+        drawCellSides(ctx, scene, view, cell, decorate);
         drawCellTop(ctx, scene, view, cell, texture, shadows);
         if (mixed && cell.environment === "indoor") drawIndoorCurb(ctx, scene, view, cell);
-        for (const ramp of rampsByCell.get(cell.y * scene.width + cell.x) ?? []) drawRamp(ctx, view, ramp);
+        for (const ramp of rampsByCell.get(cell.y * scene.width + cell.x) ?? []) {
+          let drawn = false;
+          if (decorate?.ramp) {
+            ctx.save();
+            drawn = decorate.ramp(ctx, ramp);
+            ctx.restore();
+          }
+          if (!drawn) drawRamp(ctx, view, ramp);
+        }
         if (tufts && cell.terrain === "hindering") drawHindering(ctx, view, cell);
+        if (decorate?.cell) {
+          ctx.save();
+          decorate.cell(ctx, cell);
+          ctx.restore();
+        }
       }
     });
   }
@@ -3189,14 +3245,19 @@ var MapBoardView = forwardRef(function MapBoardView2({ map, canvasLabel, selecti
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
-    const ctx = canvas.getContext("2d");
-    if (!ctx) return;
-    try {
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
-      new HCMap(map).draw(ctx, { grid });
-    } catch {
-      failed.current?.();
-    }
+    const draw = () => {
+      const ctx = canvas.getContext("2d");
+      if (!ctx) return;
+      try {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        new HCMap(map).draw(ctx, { grid });
+      } catch {
+        failed.current?.();
+      }
+    };
+    draw();
+    canvas.addEventListener("contextrestored", draw);
+    return () => canvas.removeEventListener("contextrestored", draw);
   }, [map, grid]);
   function pointer(event) {
     const bounds = event.currentTarget.getBoundingClientRect();
@@ -3307,6 +3368,7 @@ export {
   MAP_GRID_SOFT_COLOR,
   MAP_GRID_TERRAIN_SHADE,
   MAP_INDOOR_EDGE_COLOR,
+  MAP_PERSPECTIVE_DISTANCE,
   MAP_SCENE_BASE_Z,
   MAP_SCENE_LEVEL_HEIGHT,
   MAP_TERRAIN_EDGE_COLORS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ntmats/hc-ui",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Shared HCUI/Arena React presentation primitives.",
   "license": "UNLICENSED",