@harmonics/lattice-ui 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 `@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.6.0
+
+- `<lattice-board>`, in `@harmonics/lattice-ui/board`: a surface of lattice pieces a person drags,
+  steps, turns, glues, breaks apart, pulls parts off and throws away, with an optional tray of new
+  cells and triangles. The tree's Build mode, as an element: the same pull into a slot, click,
+  refusal and glue glow. A cancelable `change` after each thing done; `catch` when a slot catches.
+  Its own entry: pages that do not use it load none of it. Additive: nothing in 0.5.1 changes.
+
+## 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

package/README.md

@@ -1,7 +1,7 @@
 # @harmonics/lattice-ui
 
 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
+hexagon sky, raised shapes of cells and triangles, a shears cut gesture, two marks, and a board of pieces to build on. 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.
@@ -122,6 +122,52 @@ see [Cutting](#cutting).
 `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`.
 
+## Board
+
+`<lattice-board>` is a surface of the lattice's pieces a person builds with, the way the Harmonics
+tree's Build mode does. It is an entry of its own, so a page without one loads none of it.
+
+```js
+import { defineLatticeBoard } from "@harmonics/lattice-ui/board";
+defineLatticeBoard();
+
+const board = document.querySelector("lattice-board");
+board.pieces = [
+  { id: "a", parts: [{ kind: "cell", at: { q: 1, r: 1 }, tone: 0 }, { kind: "cell", at: { q: 2, r: 1 }, tone: 0 }] },
+  { id: "b", parts: [{ kind: "tri", at: { i: -6, j: 16, k: 0 }, tone: 5 }] }, // a triangle of cell (7, 1)
+];
+board.addEventListener("change", (e) => save(e.detail.pieces));
+```
+
+```html
+<lattice-board tray style="height: 400px"></lattice-board>
+```
+
+Drag a piece and the lattice pulls it in: near a slot it leans in and the slot lights, nearer it is
+caught and held, and let go it clicks into the slot, or goes to the nearest place it fits. A piece
+with the focus (Tab) steps with the arrows; R and Shift+R (or a double-click) turn it a sixth;
+G glues it to every piece it shares a side with (the sides glow first); Shift+G breaks it into its
+units; Alt-drag pulls one part off; Delete throws it away. Under reduced motion a carried piece
+follows the pointer exactly and nothing animates.
+
+| Input | Type | Default | |
+|---|---|---|---|
+| `pieces` | `{ id?, parts }[]`, or the same as JSON | | What the board starts from; read back, its own pieces now (each `{ id, parts, pivot }`). Set it again to replace them |
+| `fixed` | `{ id?, parts }[]` (property) | | Drawn flat and in the way, never handled, glued to or handed back |
+| `tray` | boolean | `false` | Two cells at the bottom left: drag out a new cell or triangle (or Enter on one), drop a piece there to throw it away |
+| `scale` | number | `1` | 1 is the tree's own size: a cell 76 pixels across |
+| `label` | string | "A board of lattice pieces" | What a screen reader calls it |
+
+| Event | `detail` | |
+|---|---|---|
+| `change` | `{ pieces, action, id }` | After each thing done: `action` is `move`, `turn`, `glue`, `break`, `pull`, `add` or `remove`; `id` the piece acted on (`""` when a resize moved pieces back onto the board). Cancelable: `preventDefault()` undoes it |
+| `catch` | `{ id }` | A slot caught the carried piece: a page's own sound goes here |
+
+The board fills the element; size it as any block. Its lattice starts at its top-left, so a
+`<hex-sky>` of the same size and `scale` under it shows the slots. `LatticeBoardEventMap` types the
+events on the board's own `addEventListener`. Pieces are the `Piece`s of
+[Geometry](#geometry): a page can lay them out with those functions before handing them over.
+
 ## Styling
 
 Every element carries the tree's colour tokens, light and dark (it follows
@@ -157,7 +203,8 @@ them: `lattice-icon::part(done-cell)`, `::part(done-check)`, `::part(shears-blad
 
 ## Frameworks
 
-- **React 19**: use the tags directly; add `import type {} from "@harmonics/lattice-ui/react"`
+- **React 19**: use the tags directly (define the board before it renders, as the others);
+  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`. 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