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

package/dist/preview/index.d.mts

@@ -0,0 +1,60 @@
+import { X as ControlMeasureId } from "../index-D3uCYKe3.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.
+ */
+declare function renderRepresentative(id: ControlMeasureId): 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 `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.
+   */
+  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;
+};
+//#endregion
+export { PreviewShape, ProjectDimensions, projectRenderToShapes, renderRepresentative };

package/dist/preview/index.mjs

@@ -0,0 +1,254 @@
+import { c as DEFINITIONS, t as renderControlMeasure } from "../renderControlMeasure-BblcXXLp.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.
+*/
+function renderRepresentative(id) {
+	try {
+		const { controlPoints, options, textAmplifiers } = representativeSample(id);
+		return renderControlMeasure({
+			id: "preview",
+			kind: id,
+			controlPoints,
+			...options ? { options } : {},
+			...textAmplifiers ? { 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
+	};
+}
+/** 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;
+/** 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.
+*/
+const MAX_TEXT_HEIGHT_RATIO = .25;
+/**
+* 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.
+*/
+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 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 };