@johnmorrisdotca/kazoku-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-11-01
+
+The first release, and its first part: view controls, at `@johnmorrisdotca/kazoku-ui/view-controls`.
+
+- `<kazoku-view-controls>`, a framework-free custom element (`/view-controls/element`, registered by `/view-controls/define`, which leaves a tag already taken alone), and `createViewController`, the same hands without an element.
+- Angle and tilt sliders, Auto-turn with play and pause, Front; zoom out, 2 times, in and Fit; zoom about the pointer and with Ctrl or Command and the wheel; the four-arrow pan pad and the Move or Turn choice for a drag.
+- Touch: one finger turns at 1x and moves the view when zoomed in; two fingers pinch.
+- Choices kept in the address, with keys you can rename (`parseAddress`, `formatAddress`).
+- It never draws: it reports `{ yaw, tilt, zoom, panX, panY, turning, drag }` in a `kazoku-viewchange` event or an `onChange` callback.
+- Labels in English and Japanese; light and dark; 48 px touch targets; a compact bar on a phone; no automatic turn for a reader who prefers reduced motion.
+- No runtime dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morris
+
+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,157 @@
-# Temporary Holding Version
+# Kazoku 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.
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-dark.webp">
+<img alt="The demo: a white card with a blue circle and a black triangle, turned a little and tipped, in a frame with a dotted floor. Under it the view controls: Angle and Tilt sliders, Auto-turn and Front buttons, zoom out, 2 times, zoom in and Fit, four arrows to move the zoomed view, and the Move and Turn choice for a drag." src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-light.webp" width="720">
+</picture>
+
+The family's shared interface parts, as their own versioned package: one part per subpath, so a page loads only what it uses. No runtime dependencies, MIT.
+The first part is the **view controls** for any 3D or zoomable view. They never draw the scene: they tell your page what the reader chose, and your canvas, WebGL,
+SVG or CSS 3D applies it.
+
+[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
+
+```sh
+npm install @johnmorrisdotca/kazoku-ui
+```
+
+Parts (each its own subpath; later ones: picture-tile pickers, theme swatches with light and dark, the English and 日本語 switch, Help, GitHub and npm pills, Save SVG and PNG, the family's backgrounds):
+
+| Subpath | What it is |
+|---|---|
+| `@johnmorrisdotca/kazoku-ui/view-controls` | The controller, the arithmetic, the address and the labels. Imports on a server. |
+| `@johnmorrisdotca/kazoku-ui/view-controls/element` | The `ViewControlsElement` class (needs a browser). |
+| `@johnmorrisdotca/kazoku-ui/view-controls/define` | Registers `<kazoku-view-controls>` (once, and only if the tag is free). |
+
+## View controls
+
+- Angle and tilt sliders, Auto-turn with play and pause, Front.
+- Zoom out, 2 times, zoom in and Fit. Zoom is about the pointer (and Ctrl or Command with the wheel, or a trackpad's pinch).
+- The four-arrow pan pad (shown once zoomed in) and the Move or Turn choice for what a drag does.
+- Touch: one finger turns at 1x and moves the view when zoomed in; two fingers pinch.
+- Keys on the view: arrows turn and tip it, `+` and `-` zoom, `0` or Home is Front and Fit.
+- The choices are kept in the address, with keys you can rename.
+- Labels in English and Japanese; light and dark; 48 px touch targets; a compact bar on a phone; no automatic turn for a reader who prefers reduced motion.
+- **A control never stops or resets the turn.** Zoom, tilt, pan, the Move or Turn choice, Fit and Front all leave Auto-turn running (Front only sets the angle to 0 and the turn goes on from there). A hand on the angle slider, or turning the view by dragging it, holds the turn still while it is down and the turn carries on from where the hand left it. Only the Auto-turn button pauses it.
+
+### In plain HTML
+
+```html
+<div id="scene" tabindex="0" style="height: 320px">...your scene...</div>
+<kazoku-view-controls for="scene" address></kazoku-view-controls>
+
+<script type="module">
+  import "@johnmorrisdotca/kazoku-ui/view-controls/define";
+
+  const scene = document.getElementById("scene");
+  document.querySelector("kazoku-view-controls").addEventListener("kazoku-viewchange", (event) => {
+    const { yaw, tilt, zoom, panX, panY } = event.detail;
+    scene.style.transform = `translate(${panX}px, ${panY}px) scale(${zoom}) rotateX(${tilt}deg) rotateY(${yaw}deg)`;
+  });
+</script>
+```
+
+Put the element on the view or right beside it, so it is on screen with the view. `for` names the element the hands bind to (the pointer, pinch, wheel and keys); give it a `tabindex` if you want the keys on it, and size it to the view, because the pan is held to the room the zoom gives. With `overlay` the bar sits over the bottom of its positioned parent instead.
+
+### In a framework
+
+The element is plain DOM, so any framework uses it with a ref and one listener. React:
+
+```jsx
+import "@johnmorrisdotca/kazoku-ui/view-controls/define";
+import { useEffect, useRef } from "react";
+
+export function Viewer({ draw }) {
+  const view = useRef(null);
+  const controls = useRef(null);
+  useEffect(() => {
+    const bar = controls.current;
+    bar.view = view.current;
+    const on = (event) => draw(event.detail);
+    bar.addEventListener("kazoku-viewchange", on);
+    return () => bar.removeEventListener("kazoku-viewchange", on);
+  }, [draw]);
+  return (
+    <>
+      <div ref={view} tabIndex={0} style={{ height: 320 }} />
+      <kazoku-view-controls ref={controls} lang="en" />
+    </>
+  );
+}
+```
+
+### Without the element
+
+`createViewController` is the same hands and state with no markup of its own, for a page that draws its own buttons. It touches the DOM only in `bind`.
+
+```js
+import { createViewController } from "@johnmorrisdotca/kazoku-ui/view-controls";
+
+const view = createViewController({
+  speed: 30, // degrees a second for Auto-turn
+  onChange(state, { final, reason }) {
+    draw(state); // { yaw, tilt, zoom, panX, panY, turning, drag }
+  },
+});
+const unbind = view.bind(document.getElementById("scene")); // pointer, pinch, wheel, keys
+myPlayButton.onclick = () => view.toggle();
+myZoomIn.onclick = () => view.zoomBy(1.4);
+```
+
+## The event API
+
+`kazoku-viewchange` is dispatched on the element (it bubbles and crosses shadow roots). `event.detail`, and the first argument of `onChange`, is:
+
+| Field | Meaning |
+|---|---|
+| `yaw` | Degrees, -180 up to 180: the turn about the vertical. Dragging right makes it larger. |
+| `tilt` | Degrees, held to plus or minus `tilt-max` (30): the top tips away as it gets larger (dragging up). |
+| `zoom` | 1 to 5 (`zoom-min`, `zoom-max`). |
+| `panX`, `panY` | CSS pixels the zoomed picture is moved from the middle of the view; 0 at 1x. |
+| `turning` | True while Auto-turn is running. |
+| `drag` | `"move"` or `"turn"`: what a plain drag does while zoomed in. |
+| `final` | False for the steps of a drag, a pinch, a slider and the automatic turn; true when something settled. Do the costly drawing on `final`, the cheap transform on every event. |
+| `reason` | What changed it: `init`, `auto`, `drag`, `pinch`, `wheel`, `key`, `slider`, `zoom`, `pan`, `front`, `fit`, `play`, `pause` or `set`. |
+
+An `init` event is sent once, a moment after the element connects, with the starting view (from the attributes and the address). `element.state` is the current view at any time.
+
+### Attributes
+
+| Attribute | |
+|---|---|
+| `for` | The id of the view the hands bind to. Or set `element.view = someElement`. |
+| `lang` | `en` or `ja`. Otherwise the nearest `lang` above it, else English. |
+| `yaw`, `tilt`, `zoom` | The starting view. |
+| `autoplay` | Turn by itself from the start, unless the reader prefers reduced motion. |
+| `speed` | Degrees a second (30). |
+| `flat` | The view cannot turn: no angle, tilt, Auto-turn or Front, and a drag moves it. |
+| `tilt-max`, `zoom-min`, `zoom-max` | The limits (30, 1, 5). |
+| `address` | Keep the choices in the page's address (`?yaw=40&tilt=10&zoom=2&drag=turn`). |
+| `address-keys` | Other keys: `yaw:a,zoom:z`. |
+| `theme` | `light` or `dark`; otherwise the page's colour scheme. |
+| `overlay` | Sit over the bottom of a positioned parent. |
+
+Methods: `play()`, `pause()`, `front()`, `fit()`, `set({ yaw, tilt, zoom, panX, panY, drag })`, and `controller` (the `createViewController` object behind it). `element.words = { front: "Home" }` replaces labels.
+Colours are custom properties: `--kazoku-ink`, `--kazoku-surface`, `--kazoku-line`, `--kazoku-accent`; the parts are `bar`, `field`, `slider` and `button`.
+
+### The address
+
+Only what a reader chose is kept: angle, tilt, zoom and the drag choice. The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?)`.
+
+### Why the tag is only defined when it is free
+
+`customElements.define` throws when a name is taken, and a page can meet that without any fault: two copies of this package (an app and a widget that each bundle one, or two versions), the script loaded twice, or a page that registered the tag to supply its own element. A throw would stop the importing module and the page's script with it. So `define` calls `customElements.get` first and the first definition wins; `defineViewControls(registry?)` returns whether it defined the tag.
+
+## Size
+
+Gzipped, unbundled: the element and its definition about 4.8 KB, the controller 3.5 KB, the maths 1.4 KB, the address 1.2 KB, the labels 0.7 KB and the styles 1.6 KB (`pnpm test:package` prints them). Nothing is loaded from the network.
+
+## Checks
+
+`pnpm check` (lint, types, 25 unit tests of the maths, the address and the controller, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, zoom about the pointer, pan when zoomed, touch, the address, the labels, reduced motion).
+
+## Not yet
+
+Not published to npm yet. The Japanese labels have not yet been read by a native speaker. The demo's scene is a CSS 3D card; the package has no opinion about what draws.
+
+Licence: MIT. No brand, league or sponsor mark is in this package.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** The subpaths of the parts, in the order they were added. */
+export declare const PARTS: readonly ["view-controls"];
+export type Part = (typeof PARTS)[number];

package/dist/index.js

@@ -0,0 +1,3 @@
+// Kazoku UI 家族: the family's shared interface parts, each its own subpath so a page loads only what it uses.
+/** The subpaths of the parts, in the order they were added. */
+export const PARTS = ["view-controls"];

package/dist/view-controls/address.d.ts

@@ -0,0 +1,24 @@
+import { type Limits } from "./math.ts";
+export type DragMode = "move" | "turn";
+export interface AddressKeys {
+    yaw: string;
+    tilt: string;
+    zoom: string;
+    drag: string;
+}
+export declare const DEFAULT_KEYS: AddressKeys;
+export interface AddressChoices {
+    yaw: number;
+    tilt: number;
+    zoom: number;
+    drag: DragMode;
+}
+/** Read the choices out of a query string (`?yaw=40`, with or without the `?`). Anything missing or not a number is left out of the result. */
+export declare function parseAddress(search: string, keys?: AddressKeys, limits?: Limits): Partial<AddressChoices>;
+/**
+ * The query string (with its `?`, or empty) that keeps `choices` and every other parameter of `search`. A choice at its starting value is left out, so
+ * the plain address stays plain. `leaveYaw` keeps the angle out while the view turns by itself (it would change every frame).
+ */
+export declare function formatAddress(search: string, choices: AddressChoices, keys?: AddressKeys, leaveYaw?: boolean): string;
+/** Read `address-keys`: `yaw:a,tilt:b` renames the keys it names and leaves the others. */
+export declare function parseKeys(text: string | null): AddressKeys;

package/dist/view-controls/address.js

@@ -0,0 +1,60 @@
+// The choices kept in the page's address: pure string functions, so a server or a test can use them. Only what a person chose is kept
+// (angle, tilt, zoom, what a drag does); the pan is in pixels of one screen and the turning of a moment, so neither is.
+import { clamp, DEFAULT_LIMITS, wrapYaw } from "./math.js";
+export const DEFAULT_KEYS = { yaw: "yaw", tilt: "tilt", zoom: "zoom", drag: "drag" };
+const rounded = (value, places) => Number(value.toFixed(places));
+/** Read the choices out of a query string (`?yaw=40`, with or without the `?`). Anything missing or not a number is left out of the result. */
+export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMITS) {
+    const params = new URLSearchParams(search);
+    const out = {};
+    const number = (key) => {
+        const text = params.get(key);
+        if (text === null || text.trim() === "")
+            return undefined;
+        const value = Number(text);
+        return Number.isFinite(value) ? value : undefined;
+    };
+    const yaw = number(keys.yaw);
+    const tilt = number(keys.tilt);
+    const zoom = number(keys.zoom);
+    if (yaw !== undefined)
+        out.yaw = rounded(wrapYaw(yaw), 0);
+    if (tilt !== undefined)
+        out.tilt = rounded(clamp(tilt, -limits.tiltMax, limits.tiltMax), 0);
+    if (zoom !== undefined)
+        out.zoom = rounded(clamp(zoom, limits.zoomMin, limits.zoomMax), 2);
+    const drag = params.get(keys.drag);
+    if (drag === "turn" || drag === "move")
+        out.drag = drag;
+    return out;
+}
+/**
+ * The query string (with its `?`, or empty) that keeps `choices` and every other parameter of `search`. A choice at its starting value is left out, so
+ * the plain address stays plain. `leaveYaw` keeps the angle out while the view turns by itself (it would change every frame).
+ */
+export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = false) {
+    const params = new URLSearchParams(search);
+    const set = (key, value) => {
+        if (value === undefined)
+            params.delete(key);
+        else
+            params.set(key, value);
+    };
+    if (!leaveYaw)
+        set(keys.yaw, Math.round(choices.yaw) === 0 ? undefined : String(rounded(wrapYaw(choices.yaw), 0)));
+    set(keys.tilt, Math.round(choices.tilt) === 0 ? undefined : String(rounded(choices.tilt, 0)));
+    set(keys.zoom, Math.abs(choices.zoom - 1) < 0.005 ? undefined : String(rounded(choices.zoom, 2)));
+    set(keys.drag, choices.drag === "turn" ? "turn" : undefined);
+    const text = params.toString();
+    return text === "" ? "" : `?${text}`;
+}
+/** Read `address-keys`: `yaw:a,tilt:b` renames the keys it names and leaves the others. */
+export function parseKeys(text) {
+    const keys = { ...DEFAULT_KEYS };
+    for (const part of (text ?? "").split(",")) {
+        const [name, key] = part.split(":").map((s) => s.trim());
+        if (name !== undefined && key !== undefined && key !== "" && name in keys)
+            keys[name] = key;
+    }
+    return keys;
+}

package/dist/view-controls/controller.d.ts

@@ -0,0 +1,56 @@
+import type { DragMode } from "./address.ts";
+import { type Camera, type Limits, type Point, type Size } from "./math.ts";
+export interface ViewState extends Camera {
+    /** True while the view turns by itself. A control never changes this; only play, pause and a grab of the view's own do not either (see `holdTurn`). */
+    turning: boolean;
+    /** What a plain drag does while zoomed in: move the view, or turn the piece. */
+    drag: DragMode;
+}
+export interface ChangeInfo {
+    /** False for the steps of a drag, a pinch, a slider or the automatic turn; true when something settled (a button, a release, a key, a wheel step). */
+    final: boolean;
+    /** What changed it: "set", "auto", "drag", "pinch", "wheel", "key", "zoom", "pan", "front", "fit", "play", "pause", "tap". */
+    reason: string;
+}
+export interface Clock {
+    request(callback: (now: number) => void): number;
+    cancel(id: number): void;
+}
+export interface ViewControllerOptions {
+    initial?: Partial<ViewState>;
+    /** False for a flat view that cannot turn: a drag then always moves it and the angle and tilt never change. */
+    turnable?: boolean;
+    /** Degrees a second when it turns by itself. */
+    speed?: number;
+    limits?: Partial<Limits>;
+    /** The view's size in CSS pixels, for holding the pan; `bind` gives it from the element when this is left out. */
+    size?: () => Size | undefined;
+    onChange?: (state: ViewState, info: ChangeInfo) => void;
+    /** Animation frames; the browser's requestAnimationFrame by default. A test passes its own. */
+    clock?: Clock;
+}
+export interface ViewController {
+    readonly state: ViewState;
+    turnable: boolean;
+    speed: number;
+    readonly limits: Limits;
+    set(next: Partial<ViewState>, final?: boolean, reason?: string): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Hold the automatic turn still while a hand (a slider being dragged) has the angle; `releaseTurn` lets it carry on from where the hand left it. Counts, so holds nest. */
+    holdTurn(): void;
+    releaseTurn(): void;
+    front(): void;
+    fit(): void;
+    /** Zoom to `next` about the point `at` (client pixels; the view's middle when left out). */
+    zoomAt(next: number, at?: Point, final?: boolean): void;
+    zoomBy(factor: number, at?: Point): void;
+    /** Move the view by whole fractions of its size: `panBy(1, 0)` is a quarter of its width to the right. */
+    panBy(stepsX: number, stepsY: number): void;
+    setDrag(drag: DragMode): void;
+    /** Bind the pointer, pinch, wheel and key hands to `view`. Returns a function that unbinds them. */
+    bind(view: HTMLElement): () => void;
+    destroy(): void;
+}
+export declare function createViewController(options?: ViewControllerOptions): ViewController;