@orbat-mapper/control-measures 0.2.0-alpha.10 → 0.2.0-alpha.11

package/dist/preview/index.d.mts

@@ -1,4 +1,4 @@
-import { X as ControlMeasureId } from "../index-D3uCYKe3.mjs";
+import { X as ControlMeasureId, or as TextAmplifiers } from "../index-C6nqkw1A.mjs";
 import { FeatureCollection, Geometry } from "geojson";
 
 //#region src/preview/index.d.ts
@@ -7,8 +7,16 @@ import { FeatureCollection, Geometry } from "geojson";
  * so it runs identically at build time (docs catalog, README generator) and in
  * the browser (preview app). Returns an empty collection if the generator
  * throws, so a single broken measure never breaks a whole gallery.
+ *
+ * `overrides.textAmplifiers` and `overrides.options` are each merged over the
+ * sample's own amplifiers/options (override wins per key, sample-only keys
+ * survive) — used by the params panel's placement preview to substitute
+ * placeholder values (`<T>`, `<N>`, …) for whatever the sample carries.
  */
-declare function renderRepresentative(id: ControlMeasureId): FeatureCollection<Geometry, unknown>;
+declare function renderRepresentative(id: ControlMeasureId, overrides?: {
+  textAmplifiers?: TextAmplifiers;
+  options?: Record<string, unknown>;
+}): FeatureCollection<Geometry, unknown>;
 /** A styling-free preview primitive. Consumers supply stroke, radius, font,
  *  and colors when they draw it. */
 interface PreviewShape {
@@ -26,13 +34,14 @@ interface PreviewShape {
   rotation?: number;
   /**
    * Text height in the same SVG units as `d`/`cx`/`cy`, derived from the
-   * source label's ground-anchored `textSizePixels`/`textSizeResolution`
-   * (ADR-0027) scaled through the fit into the viewBox, then clamped so a
-   * long string can't exceed ~40% of the viewBox width. Present only when the
-   * label carried real sizing; a fixed glyph with no sizing (e.g. breach's
-   * "B", or Boundary's echelon-only sample) leaves this `undefined` — a
-   * consumer should fall back to its own fixed font size, matching behavior
-   * from before this field existed.
+   * source label's ground-anchored `textSizeMeters` (ADR-0028) scaled through
+   * the fit into the viewBox, then clamped so a long string can't exceed ~40%
+   * of the viewBox width. Present only when the label carried real
+   * ground-anchored sizing; a fixed glyph with no sizing (e.g. breach's "B",
+   * or Boundary's echelon-only sample) or a screen-anchored label (bare
+   * `textSizePixels`, unresolvable to a ground size without a live map
+   * resolution) leaves this `undefined` — a consumer should fall back to its
+   * own fixed font size, matching behavior from before this field existed.
    */
   heightPx?: number;
   /** Horizontal alignment relative to (`cx`, `cy`), mirroring the label
@@ -56,5 +65,51 @@ declare function projectRenderToShapes(fc: FeatureCollection<Geometry, unknown>,
   shapes: PreviewShape[];
   ok: boolean;
 };
+/**
+ * Grows a viewBox to include every `text` shape's estimated on-screen box —
+ * {@link projectRenderToShapes} fits geometry coordinates only, so an
+ * anchor-aware label (e.g. a phase line's end-anchored "PL ECHO") can extend
+ * well past the plain `0 0 width height` viewBox. Consumers should build
+ * their SVG `viewBox` from this instead.
+ *
+ * For each text shape (skipping shapes without `cx`/`cy`), estimates a box
+ * from its glyph count (`CHAR_WIDTH_RATIO` × `fontSize`) and `fontSize`
+ * itself, placed per `textAnchor` horizontally and centered on `cy`
+ * vertically (SVG text uses `dominant-baseline="central"`), rotates its
+ * corners around `(cx, cy)` by the same angle the SVG transform applies
+ * (`renderedAngle = PI - rotation`, negated for SVG's y-down axis — see
+ * {@link svgTextTransform}; labels commonly carry `rotation = PI`,
+ * which renders flat, so an undefined rotation must not be treated as
+ * rotated), and unions the result with the base `[0, 0, width, height]` box.
+ *
+ * `fontSize` is supplied by the caller since each gallery picks its own
+ * fallback/cap for `heightPx`.
+ */
+declare function viewBoxWithLabels(shapes: PreviewShape[], dims: {
+  width: number;
+  height: number;
+}, fontSize: (s: PreviewShape) => number): {
+  minX: number;
+  minY: number;
+  width: number;
+  height: number;
+};
+/**
+ * The SVG `viewBox` string for a preview, grown to include every label's
+ * on-screen box (see {@link viewBoxWithLabels}). The convenience every Vue
+ * consumer wants — they only ever format the box into this exact string.
+ */
+declare function viewBoxString(shapes: PreviewShape[], dims: {
+  width: number;
+  height: number;
+}, fontSize: (s: PreviewShape) => number): string;
+/**
+ * The SVG `transform` attribute that rotates a `text` shape into place, or
+ * `undefined` for an unrotated/incomplete shape. Text rotations use the same
+ * generator convention as the map adapters (`renderedAngle = PI - rotation`);
+ * SVG's y-axis points down, so the angle is negated. Shared by every SVG
+ * preview consumer (sidebar gallery, docs catalog, README generator).
+ */
+declare function svgTextTransform(s: PreviewShape): string | undefined;
 //#endregion
-export { PreviewShape, ProjectDimensions, projectRenderToShapes, renderRepresentative };
+export { PreviewShape, ProjectDimensions, projectRenderToShapes, renderRepresentative, svgTextTransform, viewBoxString, viewBoxWithLabels };

package/dist/preview/index.mjs

@@ -1,4 +1,4 @@
-import { c as DEFINITIONS, t as renderControlMeasure } from "../renderControlMeasure-BblcXXLp.mjs";
+import { c as DEFINITIONS, t as renderControlMeasure } from "../renderControlMeasure-NKEYq3Fg.mjs";
 //#region src/preview/index.ts
 /**
 * Unitless `previewSample` points (~`[-1, 1]`) are scaled by this degree offset
@@ -59,16 +59,27 @@ function representativeSample(id) {
 * so it runs identically at build time (docs catalog, README generator) and in
 * the browser (preview app). Returns an empty collection if the generator
 * throws, so a single broken measure never breaks a whole gallery.
+*
+* `overrides.textAmplifiers` and `overrides.options` are each merged over the
+* sample's own amplifiers/options (override wins per key, sample-only keys
+* survive) — used by the params panel's placement preview to substitute
+* placeholder values (`<T>`, `<N>`, …) for whatever the sample carries.
 */
-function renderRepresentative(id) {
+function renderRepresentative(id, overrides) {
 	try {
 		const { controlPoints, options, textAmplifiers } = representativeSample(id);
 		return renderControlMeasure({
 			id: "preview",
 			kind: id,
 			controlPoints,
-			...options ? { options } : {},
-			...textAmplifiers ? { textAmplifiers } : {}
+			options: {
+				...options,
+				...overrides?.options
+			},
+			textAmplifiers: {
+				...textAmplifiers,
+				...overrides?.textAmplifiers
+			}
 		});
 	} catch {
 		return {
@@ -117,33 +128,133 @@ function projectRenderToShapes(fc, dims) {
 		ok: shapes.length > 0
 	};
 }
+/**
+* Meters per degree of latitude, converting a label's ground-meter height
+* (`textSizeMeters`, ADR-0028) into the lon/lat degree frame the render was
+* fit in. Preview samples sit near the origin (see `D`), where this holds for
+* both axes. Without it the raw height overshoots by ~5 orders of magnitude,
+* pinning every label to the width/height caps — larger than its geometric
+* footprint, swallowing the clearance the generator baked in between line and
+* label.
+*/
+const METERS_PER_DEGREE = 111320;
 /** Rough average glyph width, as a ratio of height, for a bold sans-serif
 *  label — used only to estimate whether a string will overflow the viewBox,
 *  not to lay out real text. */
 const CHAR_WIDTH_RATIO = .62;
+/**
+* Glyph-width ratio for {@link viewBoxWithLabels}' extent boxes. Deliberately
+* wider than {@link CHAR_WIDTH_RATIO}: the average slightly undershoots bold
+* uppercase strings ("PL ECHO"), and an extent estimate that undershoots crops
+* the label edge while one that overshoots only costs a little slack.
+*/
+const EXTENT_CHAR_WIDTH_RATIO = .75;
 /** A text shape may not claim more than this fraction of the viewBox width;
 *  longer strings shrink their `heightPx` to fit. */
 const MAX_TEXT_WIDTH_RATIO = .4;
 /**
 * A text shape may not claim more than this fraction of the viewBox height —
 * guards short strings (e.g. "LL", "BHL") whose ground-anchored size would
-* otherwise fit the width cap easily but still tower over the sample line.
-* Close to the fixed font sizes consumers used before `heightPx` existed.
+* otherwise fit the width cap easily but still tower over the sample line. The
+* preview samples sit near the origin (see `D`), so the fit `scale` is large
+* and a real-sized label's `raw` height overshoots this cap almost every time;
+* the cap, not the ground size, is what sets the on-screen height. Kept well
+* below the fixed glyph fallback so labels read as annotations on the line
+* rather than dominating a 96×48 thumbnail.
 */
-const MAX_TEXT_HEIGHT_RATIO = .25;
+const MAX_TEXT_HEIGHT_RATIO = .16;
+/**
+* Grows a viewBox to include every `text` shape's estimated on-screen box —
+* {@link projectRenderToShapes} fits geometry coordinates only, so an
+* anchor-aware label (e.g. a phase line's end-anchored "PL ECHO") can extend
+* well past the plain `0 0 width height` viewBox. Consumers should build
+* their SVG `viewBox` from this instead.
+*
+* For each text shape (skipping shapes without `cx`/`cy`), estimates a box
+* from its glyph count (`CHAR_WIDTH_RATIO` × `fontSize`) and `fontSize`
+* itself, placed per `textAnchor` horizontally and centered on `cy`
+* vertically (SVG text uses `dominant-baseline="central"`), rotates its
+* corners around `(cx, cy)` by the same angle the SVG transform applies
+* (`renderedAngle = PI - rotation`, negated for SVG's y-down axis — see
+* {@link svgTextTransform}; labels commonly carry `rotation = PI`,
+* which renders flat, so an undefined rotation must not be treated as
+* rotated), and unions the result with the base `[0, 0, width, height]` box.
+*
+* `fontSize` is supplied by the caller since each gallery picks its own
+* fallback/cap for `heightPx`.
+*/
+function viewBoxWithLabels(shapes, dims, fontSize) {
+	let minX = 0;
+	let minY = 0;
+	let maxX = dims.width;
+	let maxY = dims.height;
+	for (const s of shapes) {
+		if (s.type !== "text" || s.cx === void 0 || s.cy === void 0) continue;
+		const font = fontSize(s);
+		const w = (s.text?.length ?? 0) * EXTENT_CHAR_WIDTH_RATIO * font;
+		const h = font;
+		const left = s.textAnchor === "start" ? s.cx : s.textAnchor === "end" ? s.cx - w : s.cx - w / 2;
+		const right = left + w;
+		const top = s.cy - h / 2;
+		const bottom = s.cy + h / 2;
+		const theta = s.rotation === void 0 ? 0 : -(Math.PI - s.rotation);
+		const cos = Math.cos(theta);
+		const sin = Math.sin(theta);
+		for (const [x, y] of [
+			[left, top],
+			[right, top],
+			[right, bottom],
+			[left, bottom]
+		]) {
+			const rx = s.cx + (x - s.cx) * cos - (y - s.cy) * sin;
+			const ry = s.cy + (x - s.cx) * sin + (y - s.cy) * cos;
+			if (rx < minX) minX = rx;
+			if (rx > maxX) maxX = rx;
+			if (ry < minY) minY = ry;
+			if (ry > maxY) maxY = ry;
+		}
+	}
+	return {
+		minX,
+		minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
+}
+/**
+* The SVG `viewBox` string for a preview, grown to include every label's
+* on-screen box (see {@link viewBoxWithLabels}). The convenience every Vue
+* consumer wants — they only ever format the box into this exact string.
+*/
+function viewBoxString(shapes, dims, fontSize) {
+	const box = viewBoxWithLabels(shapes, dims, fontSize);
+	return `${box.minX} ${box.minY} ${box.width} ${box.height}`;
+}
+/**
+* The SVG `transform` attribute that rotates a `text` shape into place, or
+* `undefined` for an unrotated/incomplete shape. Text rotations use the same
+* generator convention as the map adapters (`renderedAngle = PI - rotation`);
+* SVG's y-axis points down, so the angle is negated. Shared by every SVG
+* preview consumer (sidebar gallery, docs catalog, README generator).
+*/
+function svgTextTransform(s) {
+	if (s.rotation === void 0 || s.cx === void 0 || s.cy === void 0) return void 0;
+	return `rotate(${(-((Math.PI - s.rotation) * 180) / Math.PI).toFixed(3)} ${s.cx.toFixed(3)} ${s.cy.toFixed(3)})`;
+}
 /**
-* Resolves a label's SVG-unit text height from its `textSizePixels`/
-* `textSizeResolution` properties (ground meters = pixels × resolution),
-* scaled by the same `scale` the geometry was fit with, then clamped by both
-* the height cap and the width the string would occupy at that height (so a
-* long string can't overflow `maxWidthPx`). Returns `undefined` when the label
-* carries no real sizing — the caller leaves `heightPx` unset.
+* Resolves a label's SVG-unit text height from its `textSizeMeters` property
+* (ADR-0028's ground anchor), scaled by the same `scale` the geometry was fit
+* with, then clamped by both the height cap and the width the string would
+* occupy at that height (so a long string can't overflow `maxWidthPx`).
+* Returns `undefined` when the label carries no ground-anchored sizing — a
+* screen-anchored label (bare `textSizePixels`, meaningless without a live map
+* resolution to convert it) or one with no size at all — and the caller
+* leaves `heightPx` unset.
 */
 function resolveTextHeightPx(labelProps, text, limits) {
-	const sizePixels = labelProps.textSizePixels;
-	const sizeResolution = labelProps.textSizeResolution;
-	if (typeof sizePixels !== "number" || typeof sizeResolution !== "number") return void 0;
-	const raw = sizePixels * sizeResolution * limits.scale;
+	const sizeMeters = labelProps.textSizeMeters;
+	if (typeof sizeMeters !== "number") return void 0;
+	const raw = sizeMeters * limits.scale / METERS_PER_DEGREE;
 	const widthLimit = text.length > 0 ? limits.maxWidthPx / (text.length * CHAR_WIDTH_RATIO) : Infinity;
 	return Math.min(raw, limits.maxHeightPx, widthLimit);
 }
@@ -251,4 +362,4 @@ function collectShapes(g, tx, out, bboxArea, textLimits, props) {
 	}
 }
 //#endregion
-export { projectRenderToShapes, renderRepresentative };
+export { projectRenderToShapes, renderRepresentative, svgTextTransform, viewBoxString, viewBoxWithLabels };