@twinfinity/printing 6.1.0-beta → 6.1.2-ci.30738-beta

package/src/layout/types.ts

@@ -1,4 +1,4 @@
-import type { SectionPath, SectionLabel } from '@twinfinity/geometry';
+import type { ClassBehaviorRule, SectionPath, SectionLabel } from '@twinfinity/geometry';
 
 export type PagePresetKey = 'a1' | 'a3' | 'a4';
 export type PageOrientation = 'portrait' | 'landscape';
@@ -23,22 +23,51 @@ export interface StyleMap {
     [styleName: string]: TextStyle;
 }
 
-export interface AssetSpec {
+export interface ResourceSpec {
     id: string;
     src?: string;
     content?: string;
 }
 
+/**
+ * Property-value filter narrowing a set of items *within* a class — the `where`
+ * of an include filter, a fill rule or a legend query. Templates use it to pick
+ * out "the IfcSpaces that are apartments" rather than all IfcSpaces.
+ *
+ * Each key is a short property path resolved against the item's property sets
+ * (e.g. `"BIP.spacetype"`; see `resolveProperty`). Each value is either a scalar,
+ * matched for equality, or an array, matched as any-of. Multiple keys are ANDed.
+ *
+ * String comparison on both sides is lowercased and trimmed, so `"Apartment"`,
+ * `"apartment"` and `" APARTMENT "` are the same condition. Numbers and booleans
+ * compare strictly — a property holding the string `"3"` does not match `3`.
+ *
+ * A key whose path resolves to nothing simply fails to match; it is not an error,
+ * so a typo'd path silently selects zero items rather than reporting itself.
+ */
 export type WhereCondition = Record<string, string | number | boolean | Array<string | number>>;
 
+/**
+ * A whole-value variable binding, e.g. `"{{vars.cutHeight}}"`. On numeric
+ * fields that accept it, substitution preserves the variable's type (a
+ * number variable produces a number, not a string) — this is how template
+ * variables drive section placement.
+ */
+export type VariableBinding = `{{vars.${string}}}`;
+
 export interface ClipConfig {
     class?: string | string[];
     where: WhereCondition;
-    expandByM?: number;
+    expandBy?: number;
     clipLabels?: boolean;
-    stroke?: string;
-    strokeWidthMm?: number;
-    strokeOpacity?: number;
+    /** Outline colour (same vocabulary as viewport lineStyles). */
+    color?: string;
+    /** Outline width in mm. */
+    widthMm?: number;
+    /** Outline opacity (0..1). */
+    opacity?: number;
+    /** SVG stroke-dasharray for the clip outline (e.g. '4 2'). */
+    dash?: string;
     fill?: string;
     fillOpacity?: number;
 }
@@ -65,7 +94,7 @@ export interface FillRule {
     /** Fill opacity (0–1). Default: 0.35. */
     fillOpacity?: number;
     /** When true, only apply fill to items whose centroid is spatially inside the clip polygon.
-     *  Useful when expandByM reveals adjacent spaces that shouldn't be filled.
+     *  Useful when expandBy reveals adjacent spaces that shouldn't be filled.
      *  @default false */
     matchClipFilter?: boolean;
 }
@@ -75,9 +104,14 @@ export interface HighlightConfig {
     where: WhereCondition;
     /** Only highlight items that also appear in the referenced viewport (i.e., intersect both planes). */
     intersectsViewport?: string;
-    stroke?: string;
-    strokeWidthMm?: number;
-    strokeOpacity?: number;
+    /** Outline colour (same vocabulary as viewport lineStyles). */
+    color?: string;
+    /** Outline width in mm. */
+    widthMm?: number;
+    /** Outline opacity (0..1). */
+    opacity?: number;
+    /** SVG stroke-dasharray for highlighted outlines (e.g. '4 2'). */
+    dash?: string;
     fill?: string;
     fillOpacity?: number;
 }
@@ -118,24 +152,39 @@ export interface ViewportLineStyle {
 /**
  * Per-category line styles for a viewport.
  *
- * Resolution order: category-specific → `default` → built-in defaults.
+ * Resolution order: category-specific → `defaultVisibleLines`/`defaultHiddenLines`
+ * (by the category's visibility group) → built-in category defaults → `default`
+ * → built-in defaults.
+ *
+ * Visibility groups: `defaultVisibleLines` covers cutLines, visibleLines,
+ * silhouettesVisible, featureEdges and outlineVisible; `defaultHiddenLines`
+ * covers hiddenLines, silhouettesHidden and outlineHidden. `stairArrows` is an
+ * annotation and belongs to neither group.
  *
  * Example:
  * ```json
  * {
- *   "default":     { "widthMm": 0.01, "color": "#1f2937" },
- *   "cutLines":    { "widthMm": 0.02, "color": "#000000" },
- *   "hiddenLines": { "widthMm": 0.005, "color": "#9ca3af", "dash": "4 2" }
+ *   "default":             { "widthMm": 0.01, "color": "#1f2937" },
+ *   "defaultVisibleLines": { "widthMm": 0.1,  "color": "#000000" },
+ *   "defaultHiddenLines":  { "widthMm": 0.05, "color": "#9ca3af", "dash": "4 2" },
+ *   "cutLines":            { "widthMm": 0.2 }
  * }
  * ```
  */
 export interface ViewportLineStyles {
     /** Fallback style for any category not explicitly listed. */
     default?: ViewportLineStyle;
+    /** Group default for all visible-class categories (cutLines, visibleLines, silhouettesVisible, featureEdges, outlineVisible). */
+    defaultVisibleLines?: ViewportLineStyle;
+    /** Group default for all hidden-class categories (hiddenLines, silhouettesHidden, outlineHidden). */
+    defaultHiddenLines?: ViewportLineStyle;
     cutLines?: ViewportLineStyle;
     visibleLines?: ViewportLineStyle;
     hiddenLines?: ViewportLineStyle;
-    silhouettes?: ViewportLineStyle;
+    /** Visible silhouette / apparent-contour traces. */
+    silhouettesVisible?: ViewportLineStyle;
+    /** Occluded silhouette traces — inherits the hiddenLines group style (dashed). */
+    silhouettesHidden?: ViewportLineStyle;
     featureEdges?: ViewportLineStyle;
     stairArrows?: ViewportLineStyle;
     outlineVisible?: ViewportLineStyle;
@@ -147,7 +196,8 @@ export interface ViewportLineStyles {
  *
  * Can be:
  * - String or string array: class names only
- * - Object with class + where: property-based filtering
+ * - Object with class + where: property-based filtering, optionally carrying the
+ *   per-class drawing-generation flags of {@link ClassBehaviorRule} (occludes/classify)
  * - Preset reference: { preset: "presetName" }
  *
  * Examples:
@@ -160,14 +210,18 @@ export interface ViewportLineStyles {
 export type IncludeClassesFilter =
     | string
     | string[]
-    | { class?: string | string[]; where?: WhereCondition }
+    | (Partial<ClassBehaviorRule> & { where?: WhereCondition })
     | { preset: string };
 
 /**
  * Resolved include filter (after preset expansion).
- * Either a simple class name or a class+where filter.
+ * Either a simple class name or a class+where filter carrying the per-class
+ * drawing-generation flags of {@link ClassBehaviorRule}: `occludes: false` — the
+ * class's geometry hides nothing; `classify: false` — its lines skip hidden-line
+ * testing and draw as-is. Both default true; the flags a template carries and the
+ * flags SlabSection evaluates are the same declaration.
  */
-export type ResolvedIncludeFilter = string | { class?: string | string[]; where: WhereCondition };
+export type ResolvedIncludeFilter = string | (Partial<ClassBehaviorRule> & { where?: WhereCondition });
 
 export interface ViewportElement extends BaseElement {
     kind: 'viewport';
@@ -183,31 +237,29 @@ export interface ViewportElement extends BaseElement {
     rotationDeg?: number;
     includeClasses?: IncludeClassesFilter | IncludeClassesFilter[];
     /**
-     * Per-category line styles. When set, overrides `lineWidthMm`/`lineColor`.
-     * Use `lineStyles.default` for a single style across all categories,
-     * or specify individual categories (cutLines, hiddenLines, etc.).
+     * Per-category line styles. Use `lineStyles.default` for a single style
+     * across all categories, or specify individual categories
+     * (cutLines, hiddenLines, etc.).
      */
     lineStyles?: ViewportLineStyles;
-    /** Simple shorthand: default line width for all categories. Overridden by `lineStyles`. */
-    lineWidthMm?: number;
-    /** Simple shorthand: default line color for all categories. Overridden by `lineStyles`. */
-    lineColor?: string;
     /**
      * Fill rules controlling which products get filled polygons.
      * When absent, no fills are rendered (default: no fill).
      */
     fills?: FillRule[];
-    northArrow?: { assetId: string; sizeMm?: number; offsetXMm?: number; offsetYMm?: number; rotationDeg?: number };
-    border?: { stroke?: string; strokeWidthMm?: number; dashed?: boolean };
+    northArrow?: { resourceId: string; sizeMm?: number; offsetXMm?: number; offsetYMm?: number; rotationDeg?: number };
+    border?: { stroke?: string; strokeWidthMm?: number; dash?: string };
     clip?: ClipConfig;
     highlight?: HighlightConfig;
 
     // Section configuration (overrides app defaults if specified)
     /**
-     * Override cutting plane height for horizontal plans (Y coordinate).
-     * If omitted, uses app default. Shorthand for planeNormal=[0,1,0], planePosition=cutHeight.
+     * Override cutting plane height for horizontal plans (Y coordinate,
+     * metres). Shorthand for planeNormal=[0,1,0], planePosition=cutHeight.
+     * May be a variable binding ("{{vars.cutHeight}}" with a number
+     * variable) so end users control the cut through the variables UI.
      */
-    cutHeight?: number;
+    cutHeight?: number | VariableBinding;
     /**
      * Override depth above/below cutting plane. If omitted, uses app default.
      * Only applicable for SLAB mode (PLANE mode doesn't use depth).
@@ -224,21 +276,39 @@ export interface ViewportElement extends BaseElement {
      */
     planeNormal?: [number, number, number];
     /**
-     * Distance from origin along the (normalized) plane normal.
+     * Distance from origin along the (normalized) plane normal (metres).
      * Used with planeNormal to define the cutting plane.
      * The plane passes through the point: normalize(planeNormal) * planePosition.
+     * May be a variable binding like cutHeight.
      */
-    planePosition?: number;
+    planePosition?: number | VariableBinding;
     /**
-     * Section computation mode: 'slab' or 'plane'.
-     * - 'slab': Optimized for horizontal floor plans. Uses depth above/below to include geometry.
-     * - 'plane': Arbitrary plane cuts (vertical sections, diagonal sections). Computes exact intersection.
-     *
-     * If omitted, mode is auto-detected from plane orientation:
-     * - Horizontal planes (planeNormal ≈ Y-axis) → 'slab'
-     * - Vertical or diagonal planes → 'plane'
+     * Stair-arrow geometry options for plan viewports (marker shapes and run
+     * sizing). These shape the GENERATED arrow geometry — stroke/color/width
+     * and hiding stay with `lineStyles.stairArrows`. Ignored in PLANE mode
+     * (elevations generate no stair arrows).
      */
-    mode?: 'slab' | 'plane';
+    stairArrows?: ViewportStairArrowOptions;
+}
+
+/**
+ * Template surface for `SlabSectionStairArrowOptions` (product-geometry) —
+ * kept as its own type so the template schema and the geometry package can
+ * evolve independently; renderTemplateSheet forwards field-by-field.
+ */
+export interface ViewportStairArrowOptions {
+    /** Marker at the run's bottom end (drawing-convention circle). Default 'filled'. */
+    startMarker?: 'filled' | 'open' | 'none';
+    /** Arrowhead at the run's top end. Default 'filled' (solid triangle). */
+    arrowhead?: 'filled' | 'outline' | 'open';
+    /** Fraction of the flight length the arrow occupies. */
+    lengthScale?: number;
+    /** Minimum arrow length in metres. */
+    minLength?: number;
+    /** Maximum arrow length in metres. */
+    maxLength?: number;
+    /** How far the walking line extends onto an un-anchored landing (metres). */
+    landingExtension?: number;
 }
 
 export interface TextElement extends BaseElement {
@@ -247,7 +317,6 @@ export interface TextElement extends BaseElement {
     yMm: number;
     textStyle?: string;
     text: string;
-    maxWidthMm?: number;
     align?: 'left' | 'center' | 'right';
 }
 
@@ -257,7 +326,7 @@ export interface ImageElement extends BaseElement {
     yMm: number;
     widthMm: number;
     heightMm: number;
-    assetId: string;
+    resourceId: string;
     fit?: 'contain' | 'cover' | 'stretch';
 }
 
@@ -269,7 +338,8 @@ export interface LineElement extends BaseElement {
     y2Mm: number;
     stroke?: string;
     strokeWidthMm?: number;
-    dashed?: boolean;
+    /** SVG stroke-dasharray in mm, e.g. "4 2". */
+    dash?: string;
 }
 
 export interface RectElement extends BaseElement {
@@ -281,7 +351,8 @@ export interface RectElement extends BaseElement {
     stroke?: string;
     strokeWidthMm?: number;
     fill?: string;
-    dashed?: boolean;
+    /** SVG stroke-dasharray in mm, e.g. "4 2". */
+    dash?: string;
 }
 
 export interface CircleElement extends BaseElement {
@@ -292,7 +363,8 @@ export interface CircleElement extends BaseElement {
     stroke?: string;
     strokeWidthMm?: number;
     fill?: string;
-    dashed?: boolean;
+    /** SVG stroke-dasharray in mm, e.g. "4 2". */
+    dash?: string;
 }
 
 export interface PointMm {
@@ -305,7 +377,8 @@ export interface PolylineElement extends BaseElement {
     points: PointMm[];
     stroke: string;
     strokeWidthMm: number;
-    dashed?: boolean;
+    /** SVG stroke-dasharray in mm, e.g. "4 2". */
+    dash?: string;
 }
 
 export interface PolygonElement extends BaseElement {
@@ -314,7 +387,8 @@ export interface PolygonElement extends BaseElement {
     stroke?: string;
     strokeWidthMm?: number;
     fill?: string;
-    dashed?: boolean;
+    /** SVG stroke-dasharray in mm, e.g. "4 2". */
+    dash?: string;
 }
 
 export interface ScaleBarElement extends BaseElement {
@@ -350,7 +424,6 @@ export interface LabelsElement extends BaseElement {
     text: string;
     textStyle?: string;
     align?: 'left' | 'center' | 'right';
-    maxWidthMm?: number;
     /** When true, only show labels for items whose position is spatially inside the clip polygon.
      *  @default false */
     matchClipFilter?: boolean;
@@ -358,6 +431,12 @@ export interface LabelsElement extends BaseElement {
 
 export type LegendAnchor = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
 
+/** Table line style — same stroke vocabulary as shape elements. */
+export interface LegendLineStyle {
+    stroke?: string;
+    strokeWidthMm?: number;
+}
+
 export interface LegendColumn {
     id: string;
     label: string;
@@ -388,12 +467,12 @@ export interface LegendElement extends BaseElement {
     showColorColumn?: boolean;
     colorColumnWidthMm?: number;
     cellPaddingMm?: number;
-    borderStrokeWidthMm?: number;
-    borderStrokeColor?: string;
-    gridStrokeWidthMm?: number;
-    gridStrokeColor?: string;
-    headerStrokeWidthMm?: number;
-    headerStrokeColor?: string;
+    /** Outer table border — same vocabulary as the viewport border. */
+    border?: LegendLineStyle;
+    /** Inner grid lines between rows/columns. */
+    grid?: LegendLineStyle;
+    /** Header separator (and summary separator) line. */
+    header?: LegendLineStyle;
     columns: LegendColumn[];
     /**
      * Summary row configuration.
@@ -621,14 +700,14 @@ export interface LayoutTemplate {
 
     page: PageSpec;
     styles?: StyleMap;
-    assets?: AssetSpec[];
+    resources?: ResourceSpec[];
     elements: LayoutElement[];
     presets?: {
         includeClasses?: Record<string, string[]>;
         scales?: Record<string, { preferredScales?: number[] }>;
     };
-    /** Allow fetching remote assets (images, fonts). Default: false. */
-    allowRemoteAssets?: boolean;
+    /** Allow fetching remote resources (images, fonts). Default: false. */
+    allowRemoteResources?: boolean;
 }
 
 export interface ModelMetadataEntry {
@@ -703,9 +782,15 @@ export type ViewportItemsMap = Record<string, { items: NormalizedProductItem[] }
 export type LayoutDataViewports = { viewports: ViewportItemsMap } & Record<string, any>;
 
 export interface ValidationOptions {
-    allowRemoteAssets?: boolean;
+    allowRemoteResources?: boolean;
     allowDataUrls?: boolean;
     maxViewports?: number;
+    /**
+     * Treat an `image.resourceId` that names no declared resource as an error. Off by default:
+     * `renderLayout` throws on validation errors, so switching this on mid-render turns one missing
+     * logo into no print at all. Authoring tools want it on; rendering paths do not.
+     */
+    strictResourceRefs?: boolean;
 }
 
 export interface ValidationIssue {
@@ -750,7 +835,7 @@ export interface RenderDrawingInput {
      */
     models?: ModelContext;
     options?: {
-        allowRemoteAssets?: boolean;
+        allowRemoteResources?: boolean;
         qrContext?: {
             host?: string | null;
             containerName?: string | null;
@@ -775,6 +860,8 @@ export interface RenderDrawingInput {
          *
          * Each entry needs a `product` (BIM object with gid, name, class, properties)
          * and `polylines` (for centroid computation and fill polygon rendering).
+         * Either one flat list applied to every viewport, or a record keyed by
+         * viewport id when viewports show different cuts.
          *
          * When provided, renderDrawing builds NormalizedProductItems per viewport,
          * resolving fill colors from each viewport's fill rules. This replaces
@@ -782,10 +869,7 @@ export interface RenderDrawingInput {
          *
          * Ignored when `viewportItems` is also provided (explicit items take priority).
          */
-        productEntries?: Array<{
-            product: unknown;
-            polylines: Array<{ points: Array<{ x: number; z: number }> }>;
-        }>;
+        productEntries?: ProductPolylineEntry[] | Record<string, ProductPolylineEntry[]>;
         /**
          * Pre-built product items when `models` is provided directly.
          * Keyed by viewport ID, each containing an array of NormalizedProductItems.
@@ -795,13 +879,13 @@ export interface RenderDrawingInput {
          */
         viewportItems?: Record<string, { items: NormalizedProductItem[] }>;
         /**
-         * App default section settings. Used as fallback when viewports don't specify
-         * their own cutHeight/depth configuration.
+         * gid → class/property metadata for products beyond the entry lists. Entries
+         * only cover cut-bearing products, but render-time includeClasses filtering
+         * must classify every product with drawable lines — without this map, products
+         * whose geometry never crosses the cut (furniture below a plan cut) lose their
+         * visible/hidden lines. Entry-derived metadata overrides on shared gids.
          */
-        sectionDefaults?: {
-            cutHeight?: number;
-            depth?: { above?: number; below?: number };
-        };
+        metadataById?: ModelMetadata;
         /**
          * Template variable values.
          *
@@ -829,6 +913,12 @@ export interface RenderDrawingInput {
     };
 }
 
+/** Raw per-product item-data entry: the product plus its cut polylines in world x/z. */
+export interface ProductPolylineEntry {
+    product: unknown;
+    polylines: Array<{ points: Array<{ x: number; z: number }> }>;
+}
+
 export interface RenderDrawingResult {
     svg: string;
     warnings: string[];