@harmonics/lattice-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# 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.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,165 @@
-# 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.
+
+## 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-DMimFemm.js";
+//#region src/elements/define.ts
+e();
+//#endregion