@glissade/scene 0.37.0-pre.1 → 0.38.0-pre.0

package/dist/describe.js

@@ -23,7 +23,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.37.0-pre.1";
+const RAW_VERSION = "0.38.0-pre.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /** Arity of a value type's numeric repr: vec2/vec2-arc → 2, number → 1; others (color/paint/path/string/boolean) carry no scalar arity. */
 function arityOf(type) {
@@ -435,6 +435,18 @@ const HELPERS = [
 		import: "@glissade/scene/component",
 		usage: "defineComponent({ name, props: { <p>: { type, required? } }, build(props, childId): Group }): (props & { id }) => { node: Group, id, childId(sub?), targets(child, prop) }"
 	},
+	{
+		name: "Gauge",
+		summary: "Build-time radial gauge (data-viz, like Chart): a spec → N categorical stroked-arc zones + boundary ticks + a needle + separate labels, returning a Group. Angle deg: 0=up, +=clockwise. Needle takes AUTHORED keys (tl on targets(\"needle\",\"rotation\")) OR value→angle (Meter mode). Zones/ticks/needle/labels are each addressable sub-ids (zone-{i}, tick-{i}, needle, label-{i}, glow); labels draw z-above zones so a zone dim never crushes a label. Tree-shaken off the base scene index.",
+		import: "@glissade/scene/gauge",
+		usage: "Gauge({ id, radius, zones: { extent: [start,end], color, label?, labelStyle?: { family?, size?, fill?, weight? } }[], thickness?, gap?, needle?, needleAngle?, value?, domain?, sweep?, ticks?, apexEmphasis?: boolean | number, glow?, position? }): { node: Group, id, childId(sub?), targets(sub, prop): string[] }"
+	},
+	{
+		name: "Meter",
+		summary: "The Gauge value preset: a value (or () => value signal) mapped through domain across the sweep → the needle angle. Same result shape + sub-ids as Gauge. A function value binds live (the needle follows the signal). On the @glissade/scene/gauge subpath.",
+		import: "@glissade/scene/gauge",
+		usage: "Meter({ id, radius, zones, value: number | (() => number), domain?, sweep?, … }): { node: Group, id, childId, targets }"
+	},
 	{
 		name: "linearScale",
 		summary: "A serializable linear scale (value axis): maps a numeric domain onto a pixel/unit range. Pair with Chart({ yScale }). On the @glissade/scene/chart subpath.",

package/dist/gauge.d.ts

@@ -0,0 +1,104 @@
+import { a as Group } from "./nodes.js";
+
+//#region src/gauge.d.ts
+
+declare class GaugeError extends Error {
+  constructor(message: string);
+}
+/** One categorical zone: an angular `extent` (degrees), a color, an optional label. */
+interface GaugeZone {
+  /** `[start, end]` in degrees (0 = up, + = clockwise). start < end. */
+  readonly extent: readonly [number, number];
+  /** the zone arc's stroke color. */
+  readonly color: string;
+  /** optional label drawn at the zone's mid-angle (its own addressable node). */
+  readonly label?: string;
+  /**
+   * per-label style override (family / size / fill / weight) — layered OVER the
+   * computed default (uniform size/fill + the apex size-up). Lets a consumer keep
+   * a per-episode text override AND restyle any single `label-{i}`.
+   */
+  readonly labelStyle?: {
+    readonly family?: string;
+    readonly size?: number;
+    readonly fill?: string;
+    readonly weight?: number;
+  };
+}
+interface GaugeSpec {
+  /** stable id — every child is namespaced under it. */
+  id: string;
+  /** arc radius (px), measured to the centerline of the zone band. */
+  radius: number;
+  /** the categorical zones, in angular order. At least one. */
+  zones: readonly GaugeZone[];
+  /** zone-arc stroke width (px). Default `radius * 0.14`. */
+  thickness?: number;
+  /** degrees trimmed off EACH side of every zone boundary (a visual gap). Default 0. */
+  gap?: number;
+  /** draw a needle (default true). Object form overrides its geometry. */
+  needle?: boolean | {
+    length?: number;
+    width?: number;
+    color?: string;
+  };
+  /** authored initial needle angle (deg, 0 = up). Ignored when `value` is set. */
+  needleAngle?: number;
+  /**
+   * Meter mode: a value (or `() => value` signal) mapped through `domain` across
+   * the gauge's total sweep → the needle angle. A function binds live (the needle
+   * follows the signal); a number sets the initial angle. Omit for authored mode.
+   */
+  value?: number | (() => number);
+  /** value domain for Meter mode (default `[0, 1]`). */
+  domain?: readonly [number, number];
+  /** total angular sweep `[start, end]` the value maps across. Default = zone union. */
+  sweep?: readonly [number, number];
+  /** draw boundary ticks at each distinct zone edge (default true). */
+  ticks?: boolean;
+  /** label font size (px). Default `radius * 0.13`. The mid zone's label is a size up. */
+  labelSize?: number;
+  /** label color. Default `#eaf1ff`. */
+  labelFill?: string;
+  /** label font family. Default `sans-serif`. */
+  fontFamily?: string;
+  /**
+   * emphasize the apex zone's label (the one straddling straight-up): `true`
+   * (default) = ×1.18 size + bold; `false` = no size-up (portrait-safe — the
+   * narrower stage can't afford the bump); a number = a custom size scale + bold.
+   * Gauge is a build-time factory and can't see the stage aspect, so gate this on
+   * your own `isPortrait(size)`.
+   */
+  apexEmphasis?: boolean | number;
+  /** add a center glow Circle (`glow` sub-id, opacity 0 — author animates it). */
+  glow?: boolean | {
+    color?: string;
+    radius?: number;
+  };
+  /** where to place the gauge center in the parent (default the parent origin). */
+  position?: readonly [number, number];
+}
+interface GaugeResult {
+  /** the built subtree (a Group whose id === the gauge id). */
+  readonly node: Group;
+  readonly id: string;
+  /** namespace a child id: `childId('needle')` → `'<id>/needle'`; no arg → the root id. */
+  childId(sub?: string): string;
+  /** ready-to-bind track targets: `targets('needle','rotation')` → `['<id>/needle/rotation']`. */
+  targets(sub: string, prop: string): string[];
+}
+/**
+ * Build a radial arc gauge. Returns the subtree + the child-id/target helpers.
+ * Pure: runs once at construction, emits ordinary nodes, nothing at play time.
+ */
+declare function Gauge(spec: GaugeSpec): GaugeResult;
+/**
+ * `Meter()` — the Gauge value preset: a single value (or signal) mapped through a
+ * domain to the needle across a colored track. Convenience over
+ * `Gauge({ value, domain, zones })`; the same result shape + sub-ids.
+ */
+declare function Meter(spec: Omit<GaugeSpec, 'value'> & {
+  value: number | (() => number);
+}): GaugeResult;
+//#endregion
+export { Gauge, GaugeError, GaugeResult, GaugeSpec, GaugeZone, Meter };

package/dist/gauge.js

@@ -0,0 +1,171 @@
+import { a as Path, o as Rect, r as Group, s as Text, t as Circle } from "./nodes.js";
+//#region src/gauge.ts
+var GaugeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "GaugeError";
+	}
+};
+const DEG = Math.PI / 180;
+/** Linear remap of `v` from `domain` onto `range` (the value→angle map, Meter mode). */
+function mapLinear(v, domain, range) {
+	const [d0, d1] = domain;
+	const [r0, r1] = range;
+	return d1 === d0 ? r0 : r0 + (v - d0) / (d1 - d0) * (r1 - r0);
+}
+/** A point on the gauge circle at angle `g` (deg, 0 = up, + = clockwise). */
+function pointAt(radius, g) {
+	const r = g * DEG;
+	return [radius * Math.sin(r), -radius * Math.cos(r)];
+}
+/** An open polyline contour tracing the arc `a→b` at `radius`, sampled ≤ `step` deg. */
+function arcContour(radius, a, b, step = 2) {
+	const n = Math.max(1, Math.ceil(Math.abs(b - a) / step));
+	const v = [];
+	for (let k = 0; k <= n; k++) v.push(pointAt(radius, a + (b - a) * k / n));
+	const zero = v.map(() => [0, 0]);
+	return [{
+		closed: false,
+		v,
+		in: zero,
+		out: zero
+	}];
+}
+/** A closed triangle pointing up (−y), tip at `(0,-len)`, base width `w`. */
+function needleContour(len, w) {
+	const v = [
+		[0, -len],
+		[-w / 2, 0],
+		[w / 2, 0]
+	];
+	const zero = v.map(() => [0, 0]);
+	return [{
+		closed: true,
+		v,
+		in: zero,
+		out: zero
+	}];
+}
+/**
+* Build a radial arc gauge. Returns the subtree + the child-id/target helpers.
+* Pure: runs once at construction, emits ordinary nodes, nothing at play time.
+*/
+function Gauge(spec) {
+	const { id } = spec;
+	if (!id) throw new GaugeError("Gauge needs a stable id (every child is namespaced under it)");
+	if (!(spec.radius > 0)) throw new GaugeError(`Gauge '${id}': radius must be > 0 (got ${spec.radius})`);
+	if (!spec.zones || spec.zones.length === 0) throw new GaugeError(`Gauge '${id}': needs at least one zone`);
+	const radius = spec.radius;
+	const thickness = spec.thickness ?? radius * .14;
+	const gap = spec.gap ?? 0;
+	const cid = (sub) => sub === void 0 || sub === "" ? id : `${id}/${sub}`;
+	let lo = Infinity;
+	let hi = -Infinity;
+	spec.zones.forEach((z, i) => {
+		const [a, b] = z.extent;
+		if (!(a < b)) throw new GaugeError(`Gauge '${id}': zone ${i} extent must be [start < end] (got [${a}, ${b}])`);
+		lo = Math.min(lo, a);
+		hi = Math.max(hi, b);
+	});
+	const children = [];
+	if (spec.glow) {
+		const g = typeof spec.glow === "object" ? spec.glow : {};
+		children.push(new Circle({
+			id: cid("glow"),
+			radius: g.radius ?? radius * .5,
+			fill: g.color ?? "#ffffff",
+			opacity: 0
+		}));
+	}
+	spec.zones.forEach((z, i) => {
+		const [a, b] = z.extent;
+		children.push(new Path({
+			id: cid(`zone-${i}`),
+			data: arcContour(radius, a + gap / 2, b - gap / 2),
+			stroke: z.color,
+			strokeWidth: thickness
+		}));
+	});
+	if (spec.ticks !== false) {
+		const edges = /* @__PURE__ */ new Set();
+		spec.zones.forEach((z) => {
+			edges.add(z.extent[0]);
+			edges.add(z.extent[1]);
+		});
+		let t = 0;
+		for (const g of [...edges].sort((x, y) => x - y)) {
+			const [x, y] = pointAt(radius, g);
+			children.push(new Rect({
+				id: cid(`tick-${t++}`),
+				anchor: "center",
+				position: [x, y],
+				width: Math.max(1, thickness * .12),
+				height: thickness * 1.4,
+				rotation: g,
+				fill: "#ffffff"
+			}));
+		}
+	}
+	if (spec.needle !== false) {
+		const n = typeof spec.needle === "object" ? spec.needle : {};
+		const len = n.length ?? radius * .92;
+		const w = n.width ?? Math.max(4, radius * .05);
+		let rotation;
+		if (spec.value !== void 0) {
+			const sweep = spec.sweep ?? [lo, hi];
+			const domain = spec.domain ?? [0, 1];
+			rotation = typeof spec.value === "function" ? (() => mapLinear(spec.value(), domain, sweep)) : mapLinear(spec.value, domain, sweep);
+		} else rotation = spec.needleAngle ?? 0;
+		children.push(new Path({
+			id: cid("needle"),
+			data: needleContour(len, w),
+			fill: n.color ?? "#eaf1ff",
+			rotation
+		}));
+	}
+	const labelSize = spec.labelSize ?? radius * .13;
+	const labelFill = spec.labelFill ?? "#eaf1ff";
+	const fontFamily = spec.fontFamily ?? "sans-serif";
+	const apex = spec.apexEmphasis ?? true;
+	const apexScale = apex === false ? 1 : apex === true ? 1.18 : apex;
+	const apexWeight = apex === false ? 400 : 700;
+	spec.zones.forEach((z, i) => {
+		if (z.label === void 0) return;
+		const mid = (z.extent[0] + z.extent[1]) / 2;
+		const [x, y] = pointAt(radius + thickness / 2 + labelSize * .9, mid);
+		const isApex = z.extent[0] < 0 && z.extent[1] > 0;
+		const st = z.labelStyle ?? {};
+		children.push(new Text({
+			id: cid(`label-${i}`),
+			text: z.label,
+			position: [x, y],
+			anchor: "center",
+			align: "center",
+			fill: st.fill ?? labelFill,
+			fontFamily: st.family ?? fontFamily,
+			fontSize: st.size ?? (isApex ? labelSize * apexScale : labelSize),
+			fontWeight: st.weight ?? (isApex ? apexWeight : 400),
+			box: { valign: "center" }
+		}));
+	});
+	return {
+		node: new Group({
+			id,
+			children,
+			...spec.position ? { position: [spec.position[0], spec.position[1]] } : {}
+		}),
+		id,
+		childId: cid,
+		targets: (sub, prop) => [`${cid(sub)}/${prop}`]
+	};
+}
+/**
+* `Meter()` — the Gauge value preset: a single value (or signal) mapped through a
+* domain to the needle across a colored track. Convenience over
+* `Gauge({ value, domain, zones })`; the same result shape + sub-ids.
+*/
+function Meter(spec) {
+	return Gauge(spec);
+}
+//#endregion
+export { Gauge, GaugeError, Meter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.37.0-pre.1",
+  "version": "0.38.0-pre.0",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -31,6 +31,10 @@
       "types": "./dist/chart.d.ts",
       "default": "./dist/chart.js"
     },
+    "./gauge": {
+      "types": "./dist/gauge.d.ts",
+      "default": "./dist/gauge.js"
+    },
     "./component": {
       "types": "./dist/component.d.ts",
       "default": "./dist/component.js"
@@ -73,7 +77,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.37.0-pre.1"
+    "@glissade/core": "0.38.0-pre.0"
   },
   "repository": {
     "type": "git",