@harmonics/lattice-ui 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 `@harmonics/lattice-ui` follows semantic versioning; while it is `0.x`, a minor version may change
 an element's inputs, events or tokens, and says so here.
 
+## 0.5.0
+
+- `<shears-pad>` always ends a stroke. `strokeend` carries `cancelled`: true when the stroke was cut
+  short (the pointer cancelled or its capture lost, `disabled` set mid-stroke, the pad taken off
+  the page), where before no `strokeend` came at all. `pointercancel` is now `cancelled: true`.
+  `stroke` carries `point`, the newest point.
+- **Types:** `stroke` and `strokeend` are typed on `ShearsPadElement` (`ShearsPadEventMap`, and
+  `StrokeEndDetail`) instead of on every element's `HTMLElementEventMap`. A listener added on a
+  plain `HTMLElement` reference now needs the pad's type, or a cast.
+- `<lattice-face>` idles on animation frames and stops while off screen or in a hidden tab; it
+  follows `prefers-reduced-motion` as it changes, not only as it was when first drawn.
+- An element moved on the page keeps its drawing and state; it lets go only once it stays off.
+- `defineX(name)` registers an element under a tag of your own. A tag another element holds is
+  left to it with a console warning instead of in silence.
+- `<lattice-shape>` warns once when `parts` is a string that is not JSON (the usual cause: React
+  set it before the elements were defined). `parts` read twice is the same array.
+- `@harmonics/lattice-ui/hexes` exports `crossesCell`, `crossesLine` and `crossesRing`.
+- `<hex-sky orient="flat">`: the lattice turned a quarter turn clockwise about its origin, for pages
+  whose pieces have flat-topped cells. `x`, `y` and `scale` mean what they did; the default,
+  `pointy`, draws exactly what 0.4.0 did.
+
 ## 0.4.0
 
 - The magnet in `@harmonics/lattice-ui/hexes`: `magnetOf(piece, dx, dy, held)` says where to draw a

package/README.md

@@ -25,7 +25,15 @@ npm install @harmonics/lattice-ui
 
 `@harmonics/lattice-ui` itself defines nothing when imported: call `defineLatticeElements()` (or
 one element's `defineLatticeFace()`, …) in a browser. Both are safe to import in a server render;
-there they do nothing. Every input is both an attribute and a property.
+there they do nothing. Every input is both an attribute and a property; a property set does not
+change the attribute, so style by class rather than by `[mood=…]`. A value an input does not know
+falls back to its default.
+
+A tag another library already holds is left to it, with a warning. Give the element a tag of your
+own instead: `defineHexSky("my-sky")`, and the same for every `defineX`.
+
+An element moved on the page (a list reordered) keeps what it was doing; one taken off the page
+lets go a moment later.
 
 ## Elements
 
@@ -33,7 +41,8 @@ there they do nothing. Every input is both an attribute and a property.
 
 A pale hexagon plate raised off the page with a face on it, in 1,536 of the lattice's triangles.
 It idles (blinks, bobs), laughs with relief when `pulse` goes up, and sinks the old face as a new
-one comes. Under `prefers-reduced-motion`, or `still`, it holds still and only changes.
+one comes. Under `prefers-reduced-motion` (followed as it changes), or `still`, it holds still and
+only changes. Off screen, or in a hidden tab, it does not idle.
 
 | Input | Type | Default | |
 |---|---|---|---|
@@ -83,6 +92,7 @@ Decorative.
 | Input | Type | Default | |
 |---|---|---|---|
 | `kind` | `sky` `earth` | `sky` | Earth: cells broken into triangles, on the earth's colour |
+| `orient` | `pointy` `flat` | `pointy` | Flat: the lattice turned a quarter turn clockwise about its origin, so its cells have flat tops and bottoms |
 | `scale` | number | `1` | The lattice's size |
 | `x`, `y` | number (pixels) | `0` | Where the lattice's origin sits from the element's top-left, so a sky showing part of a larger one keeps its cells in place |
 
@@ -93,16 +103,20 @@ cuts is yours to decide. Put it over what can be cut and size it as any block.
 
 | Event | `detail` | |
 |---|---|---|
-| `stroke` | `{ points, fresh }` | At every move; `fresh` on a stroke's first point |
-| `strokeend` | `{ points }` | When the pointer lifts |
+| `stroke` | `{ points, point, fresh }` | At every move; `point` is the newest, `fresh` on a stroke's first |
+| `strokeend` | `{ points, cancelled }` | Once per stroke: lifted, or `cancelled` when cut short (the pointer cancelled or lost, `disabled` set, the pad taken off the page) |
 
 Points are in the element's own pixels from its top-left. `disabled` stops it taking strokes. A
 cut by pointer has no keyboard of its own: give the same action a button.
 
 ```js
 pad.addEventListener("stroke", (e) => cutAlong(e.detail.points));
+pad.addEventListener("strokeend", (e) => (e.detail.cancelled ? undo() : commit()));
 ```
 
+`ShearsPadEventMap` types these on the pad's own `addEventListener`. To find what a stroke cut,
+see [Cutting](#cutting).
+
 ### `<lattice-icon>`
 
 `name="shears"` or `name="done"`, in the text's colour, a step square
@@ -145,7 +159,9 @@ them: `lattice-icon::part(done-cell)`, `::part(done-check)`, `::part(shears-blad
 
 - **React 19**: use the tags directly; add `import type {} from "@harmonics/lattice-ui/react"`
   for their props. React 19 sets inputs as properties, so `parts={[…]}` works, and listens with
-  `onstroke` / `onstrokeend`.
+  `onstroke` / `onstrokeend`. Define the elements before React first renders them: until then
+  React cannot see the property and sets `parts` as the attribute `"[object Object]"`, which draws
+  nothing (the shape warns once in the console when that happens).
 - **Solid**: `import type {} from "@harmonics/lattice-ui/solid"`; set objects with `prop:parts`;
   listen with `on:stroke`.
 - **Vue**: tell the compiler the tags are custom elements
@@ -229,6 +245,25 @@ onPointerUp((dx, dy) => {
 
 Under reduced motion, draw the piece in its slot and leave out the animation.
 
+### Cutting
+
+What a `<shears-pad>` stroke went through. A stroke goes through an outline when it goes in at one
+side and out at another; one that only grazes a corner, or stops inside, does not.
+
+```js
+import { crossesCell, crossesLine, crossesRing } from "@harmonics/lattice-ui/hexes";
+
+pad.addEventListener("stroke", (e) => {
+  const stroke = e.detail.points; // in the sky's pixels when the pad covers the sky at scale 1
+  const isCut = (part) => part.kind === "cell" && crossesCell(stroke, part.at);
+  const cut = pieces.filter((p) => p.parts.some(isCut));
+  const severed = crossesLine(stroke, branch); // through a line of points
+  const through = crossesRing(stroke, outline); // through any closed outline
+});
+```
+
+`crossesCell(stroke, hex, lift)` takes the cell as drawn `lift` above its place.
+
 ## Server rendering
 
 Importing either entry on a server does nothing and throws nothing. Render the tags as markup;

package/dist/define.js

@@ -1,4 +1,4 @@
-import { t as e } from "./elements-BJBhL4LI.js";
+import { t as e } from "./elements-Czlt91Ar.js";
 //#region src/elements/define.ts
 e();
 //#endregion

package/dist/{elements-BJBhL4LI.js → elements-Czlt91Ar.js}

@@ -1709,12 +1709,14 @@ var Cn = /*#__PURE__*/ P("<svg class=trail part=trail aria-hidden=true><polyline
 }, Dn = () => kt(wn, En), On = ":host{background:var(--color-tree-sky);display:block;position:relative}:host([kind=earth]){background:var(--color-tree-earth)}.sky{width:100%;height:100%;position:absolute;inset:0;overflow:hidden}.line{fill:none;stroke:var(--color-tree-lattice-sky);stroke-width:var(--tree-rule-width)}:host([kind=earth]) .line{stroke:var(--color-tree-lattice-earth)}", kn = /*#__PURE__*/ P("<svg class=sky part=sky aria-hidden=true><defs><pattern patternUnits=userSpaceOnUse><path class=line></path></pattern></defs><rect width=100% height=100%>"), An = "hex-sky", jn = Ot(On), Mn = 0, Nn = class t extends jt {
 	static observedAttributes = [
 		"kind",
+		"orient",
 		"scale",
 		"x",
 		"y"
 	];
 	inputs = t.observedAttributes;
 	kindSignal = T("sky");
+	orientSignal = T("pointy");
 	scaleSignal = T(1);
 	xSignal = T(0);
 	ySignal = T(0);
@@ -1724,6 +1726,12 @@ var Cn = /*#__PURE__*/ P("<svg class=trail part=trail aria-hidden=true><polyline
 	set kind(e) {
 		this.kindSignal[1](String(e ?? "").toLowerCase() === "earth" ? "earth" : "sky");
 	}
+	get orient() {
+		return this.orientSignal[0]();
+	}
+	set orient(e) {
+		this.orientSignal[1](String(e ?? "").toLowerCase() === "flat" ? "flat" : "pointy");
+	}
 	get scale() {
 		return this.scaleSignal[0]();
 	}
@@ -1754,7 +1762,7 @@ var Cn = /*#__PURE__*/ P("<svg class=trail part=trail aria-hidden=true><polyline
 		return (() => {
 			var r = kn(), a = r.firstChild, o = a.firstChild, s = o.firstChild, c = a.nextSibling;
 			return F(o, "id", t), F(c, "fill", `url(#${t})`), E((t) => {
-				var r = e.width, a = e.height, c = `translate(${n.x} ${n.y}) scale(${n.scale})`, l = i[n.kind];
+				var r = e.width, a = e.height, c = `translate(${n.x} ${n.y})${n.orient === "flat" ? " rotate(90)" : ""} scale(${n.scale})`, l = i[n.kind];
 				return r !== t.e && F(o, "width", t.e = r), a !== t.t && F(o, "height", t.t = a), c !== t.a && F(o, "patternTransform", t.a = c), l !== t.o && F(s, "d", t.o = l), t;
 			}, {
 				e: void 0,

package/dist/index.js

@@ -1 +1 @@
-export { x as FACES, _ as FACE_TAG, n as HexSky, p as ICON_NAMES, m as ICON_TAG, v as LatticeFace, h as LatticeIcon, c as LatticeShape, y as MOODS, d as SHAPE_NAMES, l as SHAPE_TAG, a as SHEARS_TAG, r as SKY_TAG, o as ShearsPadElement, f as TONES, i as defineHexSky, t as defineLatticeElements, b as defineLatticeFace, g as defineLatticeIcon, u as defineLatticeShape, s as defineShearsPad } from "./elements-BJBhL4LI.js";
+export { x as FACES, _ as FACE_TAG, n as HexSky, p as ICON_NAMES, m as ICON_TAG, v as LatticeFace, h as LatticeIcon, c as LatticeShape, y as MOODS, d as SHAPE_NAMES, l as SHAPE_TAG, a as SHEARS_TAG, r as SKY_TAG, o as ShearsPadElement, f as TONES, i as defineHexSky, t as defineLatticeElements, b as defineLatticeFace, g as defineLatticeIcon, u as defineLatticeShape, s as defineShearsPad } from "./elements-Czlt91Ar.js";

package/dist/types/elements/sky.d.ts

@@ -3,11 +3,14 @@ export declare const SKY_TAG = "hex-sky";
 export declare class HexSky extends LatticeElement {
     static readonly observedAttributes: string[];
     private readonly kindSignal;
+    private readonly orientSignal;
     private readonly scaleSignal;
     private readonly xSignal;
     private readonly ySignal;
     get kind(): "sky" | "earth";
     set kind(kind: string);
+    get orient(): "pointy" | "flat";
+    set orient(orient: string);
     get scale(): number;
     set scale(scale: number | string);
     get x(): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harmonics/lattice-ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Harmonics tree's look as Custom Elements: a lattice face, the hexagon sky, raised lattice shapes, a shears cut gesture and two marks. Any page, any framework.",
   "license": "MIT",
   "type": "module",

package/react.d.ts

@@ -11,7 +11,7 @@ import type {
   ShapeName,
   ShearsPadElement,
   StrokeDetail,
-  StrokePoint,
+  StrokeEndDetail,
 } from "./dist/types/elements/index";
 
 type Base<E> = DetailedHTMLProps<HTMLAttributes<E>, E>;
@@ -28,7 +28,13 @@ declare module "react" {
         label?: string;
         decorative?: boolean;
       };
-      "hex-sky": Base<HexSky> & { kind?: "sky" | "earth"; scale?: number; x?: number; y?: number };
+      "hex-sky": Base<HexSky> & {
+        kind?: "sky" | "earth";
+        orient?: "pointy" | "flat";
+        scale?: number;
+        x?: number;
+        y?: number;
+      };
       "lattice-shape": Base<LatticeShape> & {
         shape?: ShapeName;
         parts?: Part[] | string;
@@ -40,7 +46,7 @@ declare module "react" {
       "shears-pad": Base<ShearsPadElement> & {
         disabled?: boolean;
         onstroke?: (event: CustomEvent<StrokeDetail>) => void;
-        onstrokeend?: (event: CustomEvent<{ points: StrokePoint[] }>) => void;
+        onstrokeend?: (event: CustomEvent<StrokeEndDetail>) => void;
       };
       "lattice-icon": Base<LatticeIcon> & { name?: IconName; label?: string };
     }