@harmonics/lattice-ui 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 `@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.1
+
+- What 0.5.0 says, built. 0.5.0 shipped this README and CHANGELOG over a `dist` built before
+  them: its scripts have `orient` and nothing else of 0.5.0, and its `react.d.ts` imports a
+  `StrokeEndDetail` its types do not have. `npm publish` now builds and checks the package first.
+
+## 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-Ka2LbDpP.js";
 //#region src/elements/define.ts
 e();
 //#endregion