@harmonics/lattice-ui 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+`@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
+  `pulse`.
+- `<lattice-shape>`: nine ready-made shapes of lattice cells and triangles, or any `parts`, in eight
+  woods.
+- `<hex-sky>`: the sky and the earth lattices, at any scale and origin.
+- `<shears-pad>`: the cut gesture, as `stroke` and `strokeend` events.
+- `<lattice-icon>`: the shears and done marks.
+- Types for React 19 (`/react`) and Solid (`/solid`); `HTMLElementTagNameMap` for every tag.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Blankenship
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# @harmonics/lattice-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Harmonics tree's look as Custom Elements: a face drawn in the lattice's own triangles, the
+hexagon sky, raised shapes of cells and triangles, a shears cut gesture, and two marks. They work
+on any page and in any framework (React, Vue, Svelte, Solid, plain HTML) with no build step. Each
+draws in its own shadow root and carries the tree's colours with it, so it needs nothing else from
+the page. You bring the state; the elements draw it.
+
+```sh
+npm install @harmonics/lattice-ui
+```
+
+## In five minutes
+
+```html
+<script type="module">
+  import "@harmonics/lattice-ui/define"; // registers every element
+</script>
+
+<lattice-face mood="distressed"></lattice-face>
+<lattice-shape shape="flower" tone="4"></lattice-shape>
+<hex-sky style="height: 200px"></hex-sky>
+<button><lattice-icon name="shears"></lattice-icon> Prune</button>
+```
+
+`@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.
+
+## Elements
+
+### `<lattice-face>`
+
+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.
+
+| Input | Type | Default | |
+|---|---|---|---|
+| `mood` | `happy` `content` `asleep` `sad` `distressed` `puzzled` `relieved` (`MOODS`) | `happy` | The tree's moods, each wearing a face |
+| `expression` | a name from `FACES` (`Happy`, `Laughing`, `Sad`, `Surprised`, `Angry`, `Worried`, `Sleepy`, `Wink`, `Smitten`) | | Wins over `mood` |
+| `pulse` | number | `0` | Raise it by one for a laugh of relief |
+| `still` | boolean | `false` | No idle, no laugh, no fade |
+| `size` | number (pixels) | `96` | Its width; the height follows |
+| `label` | string | "A happy face" | What a screen reader says |
+| `decorative` | boolean | `false` | Hidden from screen readers |
+
+```js
+const face = document.querySelector("lattice-face");
+face.pulse += 1;
+```
+
+### `<lattice-shape>`
+
+A shape made of the sky lattice's own cells and triangles, raised off the page, each part in one
+of the tree's woods.
+
+| Input | Type | Default | |
+|---|---|---|---|
+| `shape` | `cell` `pair` `line` `flower` `triangle` `diamond` `trapezoid` `big-triangle` `hexagon` (`SHAPE_NAMES`) | `cell` | |
+| `parts` | `Part[]`, or the same as JSON | | Any shape on the lattice; wins over `shape` |
+| `tone` | 0–7 | `0` | 0–4 the tree's woods, 5 good fruit, 6 bitter, 7 untasted |
+| `lift` | number | `8` | How high it stands, in lattice units |
+| `scale` | number | `1` | 1 is the tree's own size: a cell 76 pixels across |
+| `label` | string | | Without one it is hidden from screen readers |
+
+A part is a cell `{ kind: "cell", at: { q, r } }` on the axial hex grid, or a triangle
+`{ kind: "tri", at: { i, j, k } }` (corner `i, j` of the triangle grid, `k` 0 pointing right, 1
+left), each with an optional `tone`.
+
+```js
+shape.parts = [
+  { kind: "cell", at: { q: 0, r: 0 }, tone: 1 },
+  { kind: "tri", at: { i: 0, j: 3, k: 0 }, tone: 5 },
+];
+```
+
+### `<hex-sky>`
+
+The tree's sky, its hexagon lattice drawn faint over it, filling the element. Size it as any block.
+Decorative.
+
+| Input | Type | Default | |
+|---|---|---|---|
+| `kind` | `sky` `earth` | `sky` | Earth: cells broken into triangles, on the earth's colour |
+| `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 |
+
+### `<shears-pad>`
+
+The cut gesture. A drag across it draws the blade's fading trail and reports the stroke; what it
+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 |
+
+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));
+```
+
+### `<lattice-icon>`
+
+`name="shears"` or `name="done"`, in the text's colour, a step square
+(`--lattice-icon-size` to change it). Hidden from screen readers unless it has a `label`.
+
+## Styling
+
+Every element carries the tree's colour tokens, light and dark (it follows
+`prefers-color-scheme`). Set any of them on the element itself to change it:
+
+```css
+lattice-face, lattice-shape {
+  --color-tree-ink: #222;
+  --color-tree-raised: #fffdf6;
+}
+```
+
+Set them on the elements, not on `body`: an element's own tokens sit nearer than an ancestor's.
+The ones the elements use:
+
+| Token | Used for |
+|---|---|
+| `--color-tree-sky` | the sky, and what woods and plates are mixed with |
+| `--color-tree-earth` | the earth sky |
+| `--color-tree-ink` | the face's features |
+| `--color-tree-raised` | the face's plate, a glint, untasted fruit |
+| `--color-tree-wood-0` … `--color-tree-wood-4` | the five woods; `wood-0` is also the plate's edge |
+| `--color-tree-olive` | fruit |
+| `--color-tree-alert` | blush, the tongue, the blade's trail |
+| `--color-tree-lattice-sky`, `--color-tree-lattice-earth` | the lattice lines |
+| `--tree-rule-width`, `--tree-rule-thick-width` | edges, seams, the blade |
+| `--space-tree-2`, `--space-tree-4` | how far a face sinks; an icon's size |
+
+Each element also exposes its drawing as a part: `::part(face)`, `::part(shape)`, `::part(sky)`,
+`::part(trail)`, `::part(icon)`. A mark's own paths are parts too, for a hover that recolours
+them: `lattice-icon::part(done-cell)`, `::part(done-check)`, `::part(shears-blade)`,
+`::part(shears-handle)`.
+
+## Frameworks
+
+- **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`.
+- **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
+  (`compilerOptions.isCustomElement: (tag) => /^(lattice|hex|shears)-/.test(tag)`); bind objects
+  with `.prop` (`:parts.prop="parts"`); listen with `@stroke`.
+- **Svelte, Angular, plain HTML**: as any custom element.
+
+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;
+they draw when the page defines them in the browser.
+
+## Licence
+
+MIT. The package bundles [Solid](https://www.solidjs.com) (MIT).

package/dist/define.js

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