@harmonics/lattice-ui 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 `@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.7.0
+
+- `<lattice-shape pressable>`: a button shaped like itself, in the tab order, named by its
+  `label`; a click on its faces, Enter or Space fires `press`. `pressed` makes it a toggle the page
+  sets; `disabled` stops it. It lifts under the pointer and sinks while pressed, and its focus ring
+  runs round its outline. Without `pressable`, a shape is what it was.
+- `<lattice-icon>` draws five more marks: `note`, and the board's actions `turn`, `glue`, `apart`
+  and `bin`. Each path is a part, named in the README.
+- Additive: nothing in 0.6.0 changes.
+
+## 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

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.
@@ -71,7 +71,10 @@ of the tree's woods.
 | `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 |
+| `label` | string | | Without one it is hidden from screen readers; when pressable, its name |
+| `pressable` | boolean | `false` | A button shaped like itself (below) |
+| `pressed` | boolean | unset | Makes a pressable shape a toggle (`aria-pressed`); the page sets it |
+| `disabled` | boolean | `false` | A pressable shape that cannot be pressed, out of the tab order |
 
 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
@@ -84,6 +87,22 @@ shape.parts = [
 ];
 ```
 
+With `pressable` it is a button shaped like itself, for a palette of woods, a picker of shapes or
+a button that is a shape. It is in the tab order with `role="button"` and its `label` as its name
+(one without a label warns in the console). A click on its faces, Enter, or Space (on release)
+fires `press`, `{ shape, parts }`. Only its faces take the pointer: a press in the gap round a
+hexagon's corner goes to whatever is under it. It stands a little higher under the pointer and
+sinks to half its lift while pressed, or while `pressed`; the keyboard's ring runs round its own
+outline, and a `pressed` one keeps a quiet ring, so a palette shows which is picked by more than
+its depth. The shape never presses itself: keep one `pressed` in a palette from `press`.
+
+```js
+for (const swatch of swatches)
+  swatch.addEventListener("press", () => {
+    for (const s of swatches) s.pressed = s === swatch;
+  });
+```
+
 ### `<hex-sky>`
 
 The tree's sky, its hexagon lattice drawn faint over it, filling the element. Size it as any block.
@@ -119,8 +138,68 @@ see [Cutting](#cutting).
 
 ### `<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`.
+One of the tree's marks (`ICON_NAMES`), in the text's colour, a step square
+(`--lattice-icon-size` to change it). Hidden from screen readers unless it has a `label`. Every
+mark is drawn from the lattice's pieces: hexagons, triangles and diamonds, every line upright or
+at 30°.
+
+| `name` | | Parts |
+|---|---|---|
+| `shears` (default) | two hexagon handles, two diamond blades crossing | `shears-handle`, `shears-blade` |
+| `done` | a check in a hexagon | `done-cell`, `done-check` |
+| `note` | a hexagon with two lines of writing | `note-cell`, `note-line` |
+| `turn` | a hexagon open at one side, a triangle pointing on round (R) | `turn-path`, `turn-arrow` |
+| `glue` | two cells sharing a heavy side (G) | `glue-cell`, `glue-seam` |
+| `apart` | two cells with a gap (Shift+G) | `apart-cell` |
+| `bin` | a cup under a diamond lid (Delete) | `bin-can`, `bin-rib`, `bin-lid` |
+
+The last four are `<lattice-board>`'s keyboard actions, for a page that gives each a button.
+
+## 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
 
@@ -151,13 +230,14 @@ The ones the elements use:
 | `--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)`.
+`::part(trail)`, `::part(icon)`, `::part(board)`, and a shape's focus ring `::part(ring)`. A
+mark's own paths are parts too (see `<lattice-icon>`), for a hover that recolours them:
+`lattice-icon::part(done-cell)`.
 
 ## 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