@ntmats/hc-ui 0.10.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 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`). 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

@@ -1591,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;
@@ -1615,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

@@ -2962,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;
@@ -2971,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) {
@@ -3153,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)";
@@ -3176,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();
+        }
       }
     });
   }

package/package.json

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