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

package/dist/preview/index.d.mts

@@ -0,0 +1,115 @@
+import { X as ControlMeasureId, or as TextAmplifiers } from "../index-C6nqkw1A.mjs";
+import { FeatureCollection, Geometry } from "geojson";
+
+//#region src/preview/index.d.ts
+/**
+ * Renders a measure's representative preview to GeoJSON. Pure — no map engine,
+ * 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, 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 {
+  type: "polyline" | "polygon" | "circle" | "text";
+  /** SVG path data for `polyline`/`polygon`. */
+  d?: string;
+  /** Center for `circle`/`text`. */
+  cx?: number;
+  cy?: number;
+  /** Whether a `polygon` is a doctrinal solid (arrowhead) vs an area outline. */
+  filled?: boolean;
+  /** Glyph text for `text` (e.g. breach's "B"). */
+  text?: string;
+  /** Generator-frame rotation (radians) for `text`. */
+  rotation?: number;
+  /**
+   * Text height in the same SVG units as `d`/`cx`/`cy`, derived from the
+   * 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
+   *  feature's `textAnchor` — `"start"`/`"end"` anchor the text at the point
+   *  instead of centering it. Undefined = centered. */
+  textAnchor?: "start" | "end";
+}
+/** Target viewBox the geometry is fit into. */
+interface ProjectDimensions {
+  width: number;
+  height: number;
+  pad: number;
+}
+/**
+ * Fits a rendered `FeatureCollection` into a `width`×`height` viewBox (inset by
+ * `pad`) and emits styling-free {@link PreviewShape}s. North is up (y is
+ * flipped). Returns `ok: false` for an empty/degenerate render so consumers can
+ * show a geometry-typed fallback glyph.
+ */
+declare function projectRenderToShapes(fc: FeatureCollection<Geometry, unknown>, dims: ProjectDimensions): {
+  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, svgTextTransform, viewBoxString, viewBoxWithLabels };

package/dist/preview/index.mjs

@@ -0,0 +1,365 @@
+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
+* before reaching a generator. Most generators operate in projected meters, so
+* small degree offsets near the origin yield visible geometry. The single place
+* that knows preview points are degree offsets feeding projected-meter
+* generators.
+*/
+const D = .005;
+/**
+* Generic, category-level layout for measures without a `previewSample`
+* override — keyed off `geometry`/`minCoordinates`/`entityType` so a whole
+* class shares one layout rather than each sibling repeating it. Per-measure
+* quirks live on the definition (ADR-0025). Points are unitless.
+*/
+function fallbackControlPoints(m) {
+	const min = m.minCoordinates ?? 2;
+	if (m.geometry === "point" || min <= 1) return [[0, 0]];
+	if (min === 2) return [[-1, 0], [1, 0]];
+	if (m.entityType === "Axis of Advance") return [
+		[-1, -.4],
+		[1, -.4],
+		[1.8, -.4],
+		[0, .6]
+	];
+	if (min === 3) return [
+		[-1, -.4],
+		[1, -.4],
+		[0, .6]
+	];
+	return [
+		[-.3, -.3],
+		[.3, -.3],
+		[-.6, .1],
+		[.6, .1]
+	];
+}
+/**
+* Resolves a measure's representative input: its co-located `previewSample`
+* override if present, otherwise the generic {@link fallbackControlPoints}.
+* Unitless points are scaled by {@link D} to the degree offsets a generator
+* expects.
+*/
+function representativeSample(id) {
+	const definition = DEFINITIONS[id];
+	const sample = definition.previewSample;
+	const controlPoints = (sample ? sample.controlPoints : fallbackControlPoints(definition.metadata)).map(([x, y]) => [x * D, y * D]);
+	const options = sample?.options;
+	const textAmplifiers = sample?.textAmplifiers;
+	return {
+		controlPoints,
+		...options ? { options } : {},
+		...textAmplifiers ? { textAmplifiers } : {}
+	};
+}
+/**
+* Renders a measure's representative preview to GeoJSON. Pure — no map engine,
+* 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, overrides) {
+	try {
+		const { controlPoints, options, textAmplifiers } = representativeSample(id);
+		return renderControlMeasure({
+			id: "preview",
+			kind: id,
+			controlPoints,
+			options: {
+				...options,
+				...overrides?.options
+			},
+			textAmplifiers: {
+				...textAmplifiers,
+				...overrides?.textAmplifiers
+			}
+		});
+	} catch {
+		return {
+			type: "FeatureCollection",
+			features: []
+		};
+	}
+}
+/**
+* Fits a rendered `FeatureCollection` into a `width`×`height` viewBox (inset by
+* `pad`) and emits styling-free {@link PreviewShape}s. North is up (y is
+* flipped). Returns `ok: false` for an empty/degenerate render so consumers can
+* show a geometry-typed fallback glyph.
+*/
+function projectRenderToShapes(fc, dims) {
+	let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+	const walk = (p) => {
+		if (p[0] < minX) minX = p[0];
+		if (p[0] > maxX) maxX = p[0];
+		if (p[1] < minY) minY = p[1];
+		if (p[1] > maxY) maxY = p[1];
+	};
+	for (const f of fc.features) collectCoords(f.geometry, walk);
+	if (!isFinite(minX) || !isFinite(minY)) return {
+		shapes: [],
+		ok: false
+	};
+	const spanX = Math.max(maxX - minX, 1e-9);
+	const spanY = Math.max(maxY - minY, 1e-9);
+	const innerW = dims.width - dims.pad * 2;
+	const innerH = dims.height - dims.pad * 2;
+	const scale = Math.min(innerW / spanX, innerH / spanY);
+	const offsetX = dims.pad + (innerW - spanX * scale) / 2;
+	const offsetY = dims.pad + (innerH - spanY * scale) / 2;
+	const tx = (p) => [offsetX + (p[0] - minX) * scale, offsetY + (maxY - p[1]) * scale];
+	const shapes = [];
+	const bboxArea = spanX * spanY;
+	const textLimits = {
+		scale,
+		maxWidthPx: dims.width * MAX_TEXT_WIDTH_RATIO,
+		maxHeightPx: dims.height * MAX_TEXT_HEIGHT_RATIO
+	};
+	for (const f of fc.features) collectShapes(f.geometry, tx, shapes, bboxArea, textLimits, f.properties);
+	return {
+		shapes,
+		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. 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 = .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 `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 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);
+}
+function ringArea(ring) {
+	let a = 0;
+	for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) a += (ring[j][0] - ring[i][0]) * (ring[j][1] + ring[i][1]);
+	return Math.abs(a / 2);
+}
+function collectCoords(g, push) {
+	switch (g.type) {
+		case "Point":
+			push(g.coordinates);
+			break;
+		case "MultiPoint":
+		case "LineString":
+			g.coordinates.forEach(push);
+			break;
+		case "MultiLineString":
+		case "Polygon":
+			g.coordinates.forEach((ring) => ring.forEach(push));
+			break;
+		case "MultiPolygon":
+			g.coordinates.forEach((poly) => poly.forEach((ring) => ring.forEach(push)));
+			break;
+		case "GeometryCollection":
+			g.geometries.forEach((sub) => collectCoords(sub, push));
+			break;
+	}
+}
+function pathFromRing(ring, tx, close) {
+	if (ring.length === 0) return "";
+	const parts = ring.map((p, i) => {
+		const [x, y] = tx(p);
+		return `${i === 0 ? "M" : "L"}${x.toFixed(2)} ${y.toFixed(2)}`;
+	});
+	if (close) parts.push("Z");
+	return parts.join(" ");
+}
+function collectShapes(g, tx, out, bboxArea, textLimits, props) {
+	const labelProps = props && typeof props === "object" ? props : {};
+	const labelText = typeof labelProps.text === "string" ? labelProps.text : void 0;
+	const labelRotation = typeof labelProps.rotation === "number" ? labelProps.rotation : void 0;
+	const labelAnchor = labelProps.textAnchor === "start" || labelProps.textAnchor === "end" ? labelProps.textAnchor : void 0;
+	const polygonFilled = (ring) => bboxArea > 0 && ringArea(ring) / bboxArea < .25;
+	switch (g.type) {
+		case "Point": {
+			const [x, y] = tx(g.coordinates);
+			if (labelText !== void 0) {
+				const heightPx = resolveTextHeightPx(labelProps, labelText, textLimits);
+				out.push({
+					type: "text",
+					cx: x,
+					cy: y,
+					text: labelText,
+					rotation: labelRotation,
+					heightPx,
+					textAnchor: labelAnchor
+				});
+			} else out.push({
+				type: "circle",
+				cx: x,
+				cy: y
+			});
+			break;
+		}
+		case "MultiPoint":
+			g.coordinates.forEach((p) => {
+				const [x, y] = tx(p);
+				out.push({
+					type: "circle",
+					cx: x,
+					cy: y
+				});
+			});
+			break;
+		case "LineString":
+			out.push({
+				type: "polyline",
+				d: pathFromRing(g.coordinates, tx, false)
+			});
+			break;
+		case "MultiLineString":
+			g.coordinates.forEach((line) => out.push({
+				type: "polyline",
+				d: pathFromRing(line, tx, false)
+			}));
+			break;
+		case "Polygon":
+			g.coordinates.forEach((ring) => out.push({
+				type: "polygon",
+				d: pathFromRing(ring, tx, true),
+				filled: polygonFilled(ring)
+			}));
+			break;
+		case "MultiPolygon":
+			g.coordinates.forEach((poly) => poly.forEach((ring) => out.push({
+				type: "polygon",
+				d: pathFromRing(ring, tx, true),
+				filled: polygonFilled(ring)
+			})));
+			break;
+		case "GeometryCollection":
+			g.geometries.forEach((sub) => collectShapes(sub, tx, out, bboxArea, textLimits, props));
+			break;
+	}
+}
+//#endregion
+export { projectRenderToShapes, renderRepresentative, svgTextTransform, viewBoxString, viewBoxWithLabels };