@harmonics/lattice-ui 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 `@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.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

@@ -155,6 +155,80 @@ 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.
+
 ## 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-BJBhL4LI.js";
 //#region src/elements/define.ts
 e();
 //#endregion