@glissade/scene 0.34.0 → 0.35.0-pre.0

package/dist/describe.js

@@ -22,7 +22,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.34.0";
+const RAW_VERSION = "0.35.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) {
@@ -76,6 +76,7 @@ const CONSTRUCTION_PROP_META = {
 		fontWeight: { type: "number" },
 		fontStyle: { type: "'normal'|'italic'" },
 		align: { type: "'left'|'center'|'right'" },
+		box: { type: "{ valign: 'center'|'top'|'bottom', h? }" },
 		lineHeight: { type: "number" },
 		letterSpacing: { type: "number" },
 		fontVariationSettings: { type: "string" }
@@ -397,6 +398,18 @@ const HELPERS = [
 		import: "@glissade/scene/type",
 		usage: "splitText(text: Text | TextProps, opts?: { by?: 'word'|'line'|'grapheme', id?: string, measurer?: TextMeasurer }): { node: Group, children: Text[], parts: SplitPart[], targets(prop): string[] }"
 	},
+	{
+		name: "fitText",
+		summary: "Shrink-to-fit: set a Text's fontSize to the largest that wraps within maxW to <= maxLines / <= maxH (a build-time binary search over the measurer, like Grid/splitText). Fails loud if it can't fit even at minPx (or pass onOverflow:'clamp'). Pass { measurer } for exact fit. Tree-shaken off the base scene index.",
+		import: "@glissade/scene/type",
+		usage: "fitText(text: Text, opts: { maxW: number, maxH?, maxLines?, minPx?, onOverflow?: 'throw'|'clamp', measurer? }): Text"
+	},
+	{
+		name: "fitTextGroup",
+		summary: "Fit several Texts to ONE shared fontSize (the largest at which every one fits its box) so a row/list of labels renders uniformly — kills the ragged 'same list, three sizes' bug. Returns the shared size. On the @glissade/scene/type subpath.",
+		import: "@glissade/scene/type",
+		usage: "fitTextGroup(texts: Text[], opts: { maxW: number, minPx?, measurer? }): number"
+	},
 	{
 		name: "Grid",
 		summary: "Build-time CSS-grid-style track resolver: position plain children into a column grid (fr/px tracks + gaps), returning a Group. Pure fan-out (no Yoga, no new target) — the goldens hold by construction. Tree-shaken off the base scene index.",

package/dist/nodes.d.ts

@@ -745,6 +745,19 @@ interface TextProps extends NodeProps {
   fontAxes?: PropInit<FontAxes>;
   /** Horizontal alignment about the node position; default 'left'. */
   align?: 'left' | 'center' | 'right';
+  /**
+   * VERTICAL anchoring in a box (0.35). Text is baseline-anchored by default;
+   * `box: { valign: 'center' }` instead centers the text's real INK (ascent +
+   * descent from the measurer, single- AND multi-line) on the node position —
+   * killing the `fontSize * 0.35` fudge every boxed-text component hand-rolls.
+   * `'top'`/`'bottom'` frame the ink at the top/bottom of an `h`-tall box
+   * centered on the position (pass `h`). OMITTED ⇒ baseline (byte-identical
+   * default). Construction-only; needs the scene measurer (like wrapping).
+   */
+  box?: {
+    valign: 'center' | 'top' | 'bottom';
+    h?: number;
+  };
   /** Wrap width in px; unset = no wrapping (explicit \n still breaks). */
   width?: PropInit<number>;
   /** Line height as a multiple of fontSize; default 1.25. */
@@ -793,6 +806,11 @@ declare class Text extends Node {
    *  When non-empty, overrides {@link fontVariationSettings} in the FontSpec. */
   readonly fontAxes: BindableSignal<FontAxes>;
   readonly align: 'left' | 'center' | 'right';
+  /** vertical box anchoring (0.35); undefined = baseline-anchored (default). */
+  readonly box?: {
+    valign: 'center' | 'top' | 'bottom';
+    h?: number;
+  };
   readonly width: BindableSignal<number>;
   readonly lineHeight: number;
   /** Static letter-spacing (tracking) in px; undefined = none. */
@@ -831,6 +849,14 @@ declare class Text extends Node {
     x: number;
     y: number;
   };
+  /**
+   * 0.35 box-valign: the y offset added to the fillText line grid so the text's
+   * real INK (ascent+descent, single- OR multi-line) anchors vertically per
+   * `box.valign` — the ink-metric answer to the `fontSize * 0.35` fudge. 0 when
+   * no `box` is set, so the default draw is byte-identical. Shared by draw() and
+   * lineBoxes() so highlights/reveals follow the shifted text.
+   */
+  private valignOffset;
   /**
    * The wrapped box {w, h}, measured with the scene's active measurer — the
    * same numbers Layout flows with, public so bindings never hand-calculate

package/dist/nodes.js

@@ -480,7 +480,8 @@ const NODE_CONSTRUCTION_PROP_NAMES = {
 		"align",
 		"lineHeight",
 		"fontVariationSettings",
-		"letterSpacing"
+		"letterSpacing",
+		"box"
 	],
 	Image: ["assetId"],
 	Video: [
@@ -1904,6 +1905,8 @@ var Text = class Text extends Node {
 	*  When non-empty, overrides {@link fontVariationSettings} in the FontSpec. */
 	fontAxes;
 	align;
+	/** vertical box anchoring (0.35); undefined = baseline-anchored (default). */
+	box;
 	width;
 	lineHeight;
 	/** Static letter-spacing (tracking) in px; undefined = none. */
@@ -1926,6 +1929,7 @@ var Text = class Text extends Node {
 		this.fontVariationSettings = props.fontVariationSettings;
 		this.fontAxes = initProp(signal({}), props.fontAxes);
 		this.align = props.align ?? "left";
+		if (props.box !== void 0) this.box = props.box;
 		this.width = initProp(signal(0), props.width);
 		this.lineHeight = props.lineHeight ?? 1.25;
 		this.letterSpacing = props.letterSpacing;
@@ -2001,6 +2005,33 @@ var Text = class Text extends Node {
 		};
 	}
 	/**
+	* 0.35 box-valign: the y offset added to the fillText line grid so the text's
+	* real INK (ascent+descent, single- OR multi-line) anchors vertically per
+	* `box.valign` — the ink-metric answer to the `fontSize * 0.35` fudge. 0 when
+	* no `box` is set, so the default draw is byte-identical. Shared by draw() and
+	* lineBoxes() so highlights/reveals follow the shifted text.
+	*/
+	valignOffset(m) {
+		if (this.box === void 0) return 0;
+		const font = this.fontSpec();
+		const lines = breakLines(this.text(), font, this.width() > 0 ? this.width() : void 0, m);
+		const step = quantize(font.size * this.lineHeight);
+		let inkTop = Infinity;
+		let inkBottom = -Infinity;
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			if (!line) continue;
+			const met = m.measureText(line, font);
+			inkTop = Math.min(inkTop, i * step - met.ascent);
+			inkBottom = Math.max(inkBottom, i * step + met.descent);
+		}
+		if (!Number.isFinite(inkTop)) return 0;
+		const h = this.box.h ?? inkBottom - inkTop;
+		if (this.box.valign === "center") return -(inkTop + inkBottom) / 2;
+		if (this.box.valign === "top") return -h / 2 - inkTop;
+		return h / 2 - inkBottom;
+	}
+	/**
 	* The wrapped box {w, h}, measured with the scene's active measurer — the
 	* same numbers Layout flows with, public so bindings never hand-calculate
 	* text dimensions (e.g. underline width = () => title.measuredSize().w).
@@ -2024,6 +2055,7 @@ var Text = class Text extends Node {
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, m);
 		const step = quantize(font.size * this.lineHeight);
+		const vy = this.valignOffset(m);
 		const boxes = [];
 		for (let i = 0; i < lines.length; i++) {
 			const line = lines[i];
@@ -2034,7 +2066,7 @@ var Text = class Text extends Node {
 			boxes.push({
 				text: line,
 				x,
-				y: i * step - met.ascent,
+				y: i * step - met.ascent + vy,
 				w,
 				h: met.ascent + met.descent
 			});
@@ -2214,6 +2246,7 @@ var Text = class Text extends Node {
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, ctx.measurer);
 		const step = quantize(font.size * this.lineHeight);
+		const vy = this.valignOffset(ctx.measurer);
 		const revealRaw = this.effectiveReveal(ctx.measurer);
 		const masked = Number.isFinite(revealRaw);
 		let remaining = masked ? Math.max(0, Math.floor(revealRaw)) : 0;
@@ -2230,7 +2263,7 @@ var Text = class Text extends Node {
 						color: this.fill()
 					},
 					x: 0,
-					y: i * step,
+					y: i * step + vy,
 					...this.align !== "left" ? { align: this.align } : {}
 				});
 				continue;
@@ -2248,7 +2281,7 @@ var Text = class Text extends Node {
 					color: this.fill()
 				},
 				x: 0,
-				y: i * step,
+				y: i * step + vy,
 				...this.align !== "left" ? { align: this.align } : {}
 			});
 			else {
@@ -2263,7 +2296,7 @@ var Text = class Text extends Node {
 						color: this.fill()
 					},
 					x: lineX,
-					y: i * step
+					y: i * step + vy
 				});
 			}
 		}

package/dist/type.d.ts

@@ -73,5 +73,41 @@ declare class SplitTextError extends Error {
  * part geometry — see the dev-warning footgun below.
  */
 declare function splitText(source: Text | TextProps, opts?: SplitTextOpts): SplitTextResult;
+interface FitTextOpts {
+  /** wrap/measure width (px). Required — text wraps to this and never exceeds it. */
+  maxW: number;
+  /** cap the wrapped height (px). Optional — combine with maxLines. */
+  maxH?: number;
+  /** cap the number of wrapped lines. Optional. */
+  maxLines?: number;
+  /** never shrink below this (px). Default 6. Below it, fitText throws (fail loud). */
+  minPx?: number;
+  /** if the text can't fit even at minPx: 'throw' (default) or 'clamp' to minPx. */
+  onOverflow?: 'throw' | 'clamp';
+  /** measurer for exact fit — pass one (or call setTextMeasurer first), else the
+   *  estimating fallback is used with a one-time dev warning (the splitText footgun). */
+  measurer?: TextMeasurer;
+}
+/**
+ * The largest integer-px fontSize ≤ the text's current size at which it fits the
+ * box — via a binary search over `measureWrappedText` (pure, no runtime state).
+ * The build-time answer to "shrink this to fit its container" the hand-rolled
+ * shrink loops re-implemented per component.
+ */
+declare function fitTextSize(text: Text, opts: FitTextOpts): number;
+/**
+ * Shrink `text` to fit its box: sets its `fontSize` to `fitTextSize(...)` and
+ * returns it (a plain `signal.set`, so a later explicit bind still wins — the
+ * Grid()/splitText() mutate-and-return convention). Also sets `width` to maxW so
+ * the node wraps to the same box it was fitted against.
+ */
+declare function fitText(text: Text, opts: FitTextOpts): Text;
+/**
+ * Fit several texts to ONE shared size — the largest px at which EVERY text fits
+ * its box — so a row/list of labels renders uniformly (kills the "same list, three
+ * different sizes" ragged-headers bug). Each text may carry its own maxW; a single
+ * `maxW` applies to all. Returns the shared size.
+ */
+declare function fitTextGroup(texts: readonly Text[], opts: FitTextOpts): number;
 //#endregion
-export { type GraphemeBox, type LineBox, SplitBy, SplitPart, SplitTextError, SplitTextOpts, SplitTextResult, type WordBox, splitText };
+export { FitTextOpts, type GraphemeBox, type LineBox, SplitBy, SplitPart, SplitTextError, SplitTextOpts, SplitTextResult, type WordBox, fitText, fitTextGroup, fitTextSize, splitText };

package/dist/type.js

@@ -1,4 +1,4 @@
-import { L as quantize, P as fallbackMeasurer, V as warnIfEstimating, r as Group, s as Text } from "./nodes.js";
+import { I as measureWrappedText, L as quantize, P as fallbackMeasurer, V as warnIfEstimating, r as Group, s as Text } from "./nodes.js";
 //#region src/type.ts
 /**
 * `@glissade/scene/type` — `splitText()`: build-time split-text sub-targets
@@ -131,5 +131,82 @@ function splitText(source, opts = {}) {
 		targets
 	};
 }
+/** Build a measurement FontSpec for `text` at a candidate size (public fields only). */
+function fontAt(text, size) {
+	return {
+		family: text.fontFamily,
+		size,
+		weight: text.fontWeight,
+		...text.fontStyle === "italic" ? { style: "italic" } : {},
+		...text.letterSpacing !== void 0 ? { letterSpacing: text.letterSpacing } : {}
+	};
+}
+/** True if `text` wraps within maxW to ≤ maxLines and ≤ maxH at this fontSize. */
+function fits(text, size, opts, m) {
+	const font = fontAt(text, size);
+	const met = measureWrappedText(text.text(), font, opts.maxW, text.lineHeight, m);
+	if (opts.maxLines !== void 0 && met.lines.length > opts.maxLines) return false;
+	if (opts.maxH !== void 0 && met.height > opts.maxH) return false;
+	for (const line of met.lines) if (m.measureText(line, font).width > opts.maxW + .5) return false;
+	return true;
+}
+/**
+* The largest integer-px fontSize ≤ the text's current size at which it fits the
+* box — via a binary search over `measureWrappedText` (pure, no runtime state).
+* The build-time answer to "shrink this to fit its container" the hand-rolled
+* shrink loops re-implemented per component.
+*/
+function fitTextSize(text, opts) {
+	const m = opts.measurer ?? text.measurerSource?.() ?? fallbackMeasurer();
+	warnIfEstimating(m, "fitText");
+	const minPx = opts.minPx ?? 6;
+	const hi = Math.max(minPx, Math.floor(text.fontSize()));
+	if (fits(text, hi, opts, m)) return hi;
+	if (!fits(text, minPx, opts, m)) {
+		if (opts.onOverflow === "clamp") return minPx;
+		throw new Error(`fitText: '${text.text().slice(0, 40)}${text.text().length > 40 ? "…" : ""}' does not fit ${opts.maxW}px${opts.maxLines !== void 0 ? ` in ${opts.maxLines} line(s)` : ""} even at minPx=${minPx} — raise maxW/maxLines/maxH, lower minPx, or pass { onOverflow: 'clamp' }`);
+	}
+	let lo = minPx;
+	let best = minPx;
+	let hiN = hi;
+	while (lo <= hiN) {
+		const mid = lo + hiN >> 1;
+		if (fits(text, mid, opts, m)) {
+			best = mid;
+			lo = mid + 1;
+		} else hiN = mid - 1;
+	}
+	return best;
+}
+/**
+* Shrink `text` to fit its box: sets its `fontSize` to `fitTextSize(...)` and
+* returns it (a plain `signal.set`, so a later explicit bind still wins — the
+* Grid()/splitText() mutate-and-return convention). Also sets `width` to maxW so
+* the node wraps to the same box it was fitted against.
+*/
+function fitText(text, opts) {
+	const size = fitTextSize(text, opts);
+	text.fontSize.set(size);
+	text.width.set(opts.maxW);
+	return text;
+}
+/**
+* Fit several texts to ONE shared size — the largest px at which EVERY text fits
+* its box — so a row/list of labels renders uniformly (kills the "same list, three
+* different sizes" ragged-headers bug). Each text may carry its own maxW; a single
+* `maxW` applies to all. Returns the shared size.
+*/
+function fitTextGroup(texts, opts) {
+	if (texts.length === 0) throw new Error("fitTextGroup needs at least one text");
+	const shared = Math.min(...texts.map((t) => fitTextSize(t, {
+		...opts,
+		onOverflow: "clamp"
+	})));
+	for (const t of texts) {
+		t.fontSize.set(shared);
+		t.width.set(opts.maxW);
+	}
+	return shared;
+}
 //#endregion
-export { SplitTextError, splitText };
+export { SplitTextError, fitText, fitTextGroup, fitTextSize, splitText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.34.0",
+  "version": "0.35.0-pre.0",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -69,7 +69,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.34.0"
+    "@glissade/core": "0.35.0-pre.0"
   },
   "repository": {
     "type": "git",