@harmonics/lattice-ui 0.1.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 `@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
+  carried piece and which slot it would land in. Near a slot it leans in, nearer the slot catches
+  and holds it, and it stays held until tugged past a release distance (`MAGNET` has the four
+  distances). `snapFrames(from)` is the click into the slot: Web Animations keyframes that pass it
+  once and settle; `stepOnScreen(step)` is a step's move on the screen. Additive: nothing in 0.3.0 changes.
+
+## 0.3.0
+
+- Glue in `@harmonics/lattice-ui/hexes`: `glued` (a piece joined to every piece it shares a side
+  with, each part keeping its tone), `sharedSides` (the sides that would glue), `seamsOf` (where a
+  piece is glued), `apart` (back into its units), `pulledOff` (one part off, the rest as one piece
+  or several); with `turned` and `pivotPoint` (a sixth of a turn about the piece's pivot) and
+  `unitAt` (a new cell or triangle under a point). Additive: nothing in 0.2.0 changes.
+
+## 0.2.0
+
+- `@harmonics/lattice-ui/hexes`: the lattice's geometry, for pages that place their own pieces on
+  the sky. Cells, corners and triangles (`boxOf`, `cornerOf`, `cornersOf`, `hexAt`, `cornerAt`,
+  `trisOf`), pieces (`pieceOf`, `covered`, `outlineOf`, `touching`), moving and snapping (`moved`,
+  `snapDelta`, `stepFor`) and finding room (`fits`, `nearestFit`, `screenArea`). Pure functions, no
+  DOM. Additive: nothing in 0.1.0 changes.
+
 ## 0.1.0
 
 - `<lattice-face>`: the tree's face, by mood or by expression, idling, with a laugh of relief on

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
@@ -155,6 +171,99 @@ them: `lattice-icon::part(done-cell)`, `::part(done-check)`, `::part(shears-blad
 
 TypeScript knows the tags from `HTMLElementTagNameMap` once the package is imported.
 
+## Geometry
+
+`@harmonics/lattice-ui/hexes` is the lattice's own geometry, for a page that places pieces on the
+sky itself (a board, a puzzle, an editor). Pure functions, no DOM, safe in a server render.
+
+```js
+import { pieceOf, moved, snapDelta, fits, nearestFit, screenArea } from "@harmonics/lattice-ui/hexes";
+
+const piece = pieceOf("a", [{ kind: "cell", at: { q: 2, r: 1 }, tone: 1 }]);
+const carried = moved(piece, snapDelta(piece, dx, dy)); // follow a pointer, snapped to whole cells
+const placed = fits(carried, others, screenArea(width, height))
+  ? carried
+  : nearestFit(carried, others, screenArea(width, height));
+```
+
+The sky is pointy-top hexagons 44 on a side: a cell is 76.21 across, rows are 66 apart, and each
+row starts half a cell further right. A cell is `{ q, r }` (axial); its box's top-left is
+`boxOf(hex)`. Split into triangles, the sky is also a grid of corners `{ i, j }` (`cornerOf`), each
+the top-left of two triangles `{ i, j, k }`: `k` 0 points right, 1 left. A piece is
+`{ id, parts, pivot }`; make one with `pieceOf`. A piece with a cell moves a whole cell at a time.
+
+To lay a `<lattice-shape>` exactly on a `<hex-sky>` of the same `scale` (`s`), give the shape the
+piece's parts and place it at `s × (minX − 2, minY − lift − 2)`, the top-left of every corner it
+covers (`covered`, `cornersOf`, `cornerOf`), less the shape's padding and lift.
+
+### Glue
+
+Pieces that share a side (not only a corner) can be glued into one; each part keeps its `tone`, so
+a glued piece still shows its woods, and it moves and turns as one. The functions that split a
+piece take `id`, your own generator of new piece ids.
+
+```js
+import { apart, glued, pulledOff, seamsOf, sharedSides, turned, unitAt } from "@harmonics/lattice-ui/hexes";
+
+const sides = others.flatMap((o) => sharedSides(piece, o)); // where G would glue: draw them lit
+const { piece: one, absorbed } = glued(piece, others); // G: drop the absorbed ids from your list
+const seams = seamsOf(one); // the sides between its parts, to draw as hairlines
+const units = apart(one, newId); // Shift+G: every part a piece of its own
+const [part, ...rest] = pulledOff(one, index, newId); // one part off; the rest stay joined
+const turnedOnce = turned(one, 1); // a sixth clockwise about its pivot (pivotPoint(one) on screen)
+const fresh = unitAt("tri", x, y, tone, newId()); // a new cell or triangle under a point
+```
+
+Sides and seams come as pairs of screen points, in the sky's own pixels. Glued pieces are drawn
+with `<lattice-shape>` like any other: give it the piece's parts.
+
+### Magnet
+
+A carried piece is pulled into the sky's lattice. Near a slot it leans in. Nearer, the slot
+catches it and it is drawn there exactly. It stays held until it is tugged past a release
+distance, which is further out than the catch, so it never flickers at the edge. `MAGNET` holds
+the four distances, as parts of the piece's unit: `reach`, `capture`, `release` and `lean`.
+
+```js
+import { magnetOf, moved, snapFrames, stepOnScreen } from "@harmonics/lattice-ui/hexes";
+
+let held; // the slot it is held in, handed back on every move
+onPointerMove((dx, dy) => {
+  const m = magnetOf(piece, dx, dy, held);
+  held = m.held;
+  draw(piece, m.x, m.y); // where it is drawn, as a move from where it was lifted
+  glow(m.step, m.pull); // the slot it would land in, and how hard it pulls (0 to 1)
+});
+onPointerUp((dx, dy) => {
+  const m = magnetOf(piece, dx, dy, held);
+  const slot = stepOnScreen(m.step); // the slot's move on the screen
+  piece = moved(piece, m.step);
+  // The click: from where it was let go, past the slot once, to rest in it.
+  element.animate(snapFrames({ x: m.x - slot.x, y: m.y - slot.y }), { duration: 260 });
+});
+```
+
+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-DMimFemm.js";
+import { t as e } from "./elements-Czlt91Ar.js";
 //#region src/elements/define.ts
 e();
 //#endregion