@welldot/render 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { Well, Lithology, Fracture, Cave, BoreHole, WellCase, WellScreen, HoleFill, SurfaceCase, Reduction, Units, DiameterUnits, LengthUnits } from '@welldot/core';
+import { LanguageText, Well, Lithology, Fracture, Cave, BoreHole, WellCase, WellScreen, HoleFill, SurfaceCase, Reduction, Units, DiameterUnits, LengthUnits } from '@welldot/core';
+export { importFgdcTextures } from './textures.cjs';
 
 type PadTextureConfig = {
     background: string;
@@ -129,6 +130,9 @@ type ConstructionTheme = {
     wellScreen: {
         stroke: string;
         strokeWidth: number;
+        /** Width of the dashed line at each screen's top and base. */
+        endStrokeWidth: number;
+        endDasharray: string;
     };
     reduction: {
         fill: string;
@@ -140,6 +144,16 @@ type ConstructionTheme = {
         stroke: string;
         strokeWidth: number;
     };
+    /** Current pump body and its riser pipe (`.well` v2.3 `pump_installations`). */
+    pump: {
+        fill: string;
+        stroke: string;
+        strokeWidth: number;
+        /** Riser interior: a tone between the casing's and the body's, so the riser reads as part of the pump, not as a casing. */
+        riserFill: string;
+        riserStroke: string;
+        riserStrokeWidth: number;
+    };
     conflict: {
         stroke: string;
         strokeWidth: number;
@@ -185,6 +199,46 @@ type LabelsTheme = {
         caveLabelFontSize?: number;
     };
 };
+/** Mini-map drawn by `RenderConfig.overview`. */
+type OverviewTheme = {
+    stroke: string;
+    strokeWidth: number;
+    /** Fill of layers without a `color`. */
+    emptyFill: string;
+    /** Outline of the window marking the panel's depth range. */
+    windowStroke: string;
+    windowStrokeWidth: number;
+};
+/** Column titles drawn by `RenderConfig.columnHeaders`. */
+type ColumnHeadersTheme = {
+    fontSize: number;
+    color: string;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    ruleStroke: string;
+    ruleStrokeWidth: number;
+};
+/** Layer and fracture markers drawn by `RenderConfig.markers`. */
+type MarkersTheme = {
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+    color: string;
+    fontSize: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+};
+/** Hatched band drawn over the depths a panel repeats from the previous one. */
+type OverlapTheme = {
+    stroke: string;
+    strokeWidth: number;
+    /** Spacing of the hatch lines in pixels. */
+    size: number;
+    ruleStroke: string;
+    labelColor: string;
+    fontSize: number;
+    fontFamily?: string;
+};
 type LegendTheme = {
     borderStrokeWidth: number;
     fractureStrokeWidth: number;
@@ -203,6 +257,10 @@ type WellTheme = {
     fracture: FractureTheme;
 } & ConstructionTheme & LabelsTheme & {
     legend: LegendTheme;
+    overview: OverviewTheme;
+    columnHeaders: ColumnHeadersTheme;
+    markers: MarkersTheme;
+    overlap: OverlapTheme;
 };
 type ComponentsClassNames = {
     tooltip: {
@@ -275,6 +333,10 @@ type ComponentsClassNames = {
         group: string;
         item: string;
     };
+    pump: {
+        group: string;
+        item: string;
+    };
     conflict: {
         group: string;
         rect: string;
@@ -294,6 +356,26 @@ type ComponentsClassNames = {
         caveFill: string;
         constructionRect: string;
     };
+    overview: {
+        group: string;
+        item: string;
+        window: string;
+    };
+    columnHeaders: {
+        group: string;
+        text: string;
+        rule: string;
+    };
+    markers: {
+        group: string;
+        lithology: string;
+        fracture: string;
+    };
+    overlap: {
+        group: string;
+        band: string;
+        label: string;
+    };
     highlights: {
         geologicGroup: string;
         constructionGroup: string;
@@ -305,17 +387,14 @@ type ComponentsClassNames = {
     };
 };
 /** Keys identifying which tooltip types are active. Pass to `RenderConfig.tooltips` to control visibility. */
-type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'reduction' | 'centralizer' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
+type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'reduction' | 'centralizer' | 'pump' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
 /**
- * A paired-locale string for renderer-drawn text, or a bare string when the
- * value doesn't vary by locale. `pt` is the required fallback locale in the
- * object form; `en` is optional. Resolve via `resolveRenderLabel()` — never
- * read `.pt`/`.en` directly, since the value may be a plain string.
+ * Renderer-drawn text: a core `LanguageText` with `pt` required (the fallback
+ * locale; `en` and any other tag optional), or a bare string when the value
+ * doesn't vary by locale. Resolve via `resolveRenderLabel()` — never read a
+ * tag directly, since the value may be a plain string.
  */
-type RenderLocalizedText = {
-    pt: string;
-    en?: string;
-} | string;
+type RenderLocalizedText = LanguageText<'pt'> | string;
 /**
  * Shape shared by `RenderConfig.tooltipLabels` (resolved, `T = string`) and
  * `RenderLabelPack.tooltipLabels` (authoring, `T = RenderLocalizedText`) —
@@ -349,6 +428,8 @@ type TooltipLabels<T = string> = {
     wellScreen: {
         title: T;
         slot: T;
+        material: T;
+        slotType: T;
     };
     reduction: {
         title: T;
@@ -358,6 +439,19 @@ type TooltipLabels<T = string> = {
         depth: T;
         spacing: T;
     };
+    pump: {
+        title: T;
+        intakeDepth: T;
+        model: T;
+        power: T;
+        riser: T;
+        type_submersible: T;
+        type_vertical_turbine: T;
+        type_jet: T;
+        type_progressive_cavity: T;
+        type_hand_pump: T;
+        type_compressor_airlift: T;
+    };
     conflict: {
         title: T;
     };
@@ -402,7 +496,22 @@ type RenderLabelPack = {
         cave: RenderLocalizedText;
         caveWater: RenderLocalizedText;
     };
+    columnHeaders: Record<keyof RenderConfig['columnHeaders']['labels'], RenderLocalizedText>;
+    continuation: {
+        prefix: RenderLocalizedText;
+    };
+    overlap: {
+        label: RenderLocalizedText;
+    };
 };
+/** Sub-items of the lithology annotations (`RenderConfig.labels.lithology`). */
+type LithologyLabelItem = 'depth' | 'description' | 'dividers'
+/** Bold `geologic_unit` line and italic `aquifer_unit` line. */
+ | 'units'
+/** Square of the layer's fill before the depth range. */
+ | 'swatch'
+/** Rule above each annotation, as wide as the annotation. */
+ | 'rules';
 /** Full rendering behaviour configuration. Use `INTERACTIVE_RENDER_CONFIG` or `STATIC_RENDER_CONFIG` as a starting point. */
 type RenderConfig = {
     zoom: boolean;
@@ -450,9 +559,34 @@ type RenderConfig = {
         };
     };
     construction: {
+        /**
+         * Fixed-size pad drawn above the surface as two slabs around the
+         * outermost pipe, with break lines at the outer ends (not to scale). The
+         * profile's `cement_pad` width and thickness don't change it (they only
+         * show in the tooltip).
+         */
         cementPad: {
-            widthMultiplier: number;
-            thicknessMultiplier: number;
+            /** Pad width as a ratio of the construction column width; widened when the pipe opening needs it. */
+            widthRatio: number;
+            /** Pad height in pixels (constant regardless of zoom). */
+            height: number;
+        };
+        /**
+         * Casing shoe: a filled triangle outside each wall where the casing /
+         * screen string really ends (not at panel cuts or joints).
+         */
+        casingShoe: {
+            active: boolean;
+            /** Triangle leg in pixels (constant regardless of zoom). */
+            size: number;
+        };
+        /**
+         * Screen ends: a dashed line across the pipe at the top and base of
+         * every screen (not at panel cuts). Styled by `theme.wellScreen`
+         * `endStrokeWidth` / `endDasharray`.
+         */
+        screenEnds: {
+            active: boolean;
         };
         surfaceCase: {
             diameterPaddingRatio: number;
@@ -461,10 +595,27 @@ type RenderConfig = {
             /** Half the marker height in pixels (constant regardless of zoom). */
             markerHalfHeight: number;
         };
+        /** Current pump + riser layer (`.well` v2.3 `pump_installations`). */
+        pump: {
+            /** Whether the current pump is drawn. */
+            active: boolean;
+            /** Pump body height in pixels (constant regardless of zoom); the body ends at `intake_depth`. */
+            bodyHeight: number;
+            /** Pump body width as a fraction of the casing/screen diameter at the intake. */
+            bodyWidthRatio: number;
+            /** Riser width as a fraction of the casing diameter, used when `riser_diameter` is absent. */
+            riserWidthRatio: number;
+        };
     };
     textures?: TexturesConfig;
     constructionLabels: {
         active: boolean;
+        /**
+         * `left` (default): each label ends `xOffset` px left of its own casing
+         * wall. `right`: labels start `xOffset` px right of the construction
+         * column, in one aligned column.
+         */
+        side?: 'left' | 'right';
         xOffset: number;
         labelRadius: number;
         labelMaxWidth?: number;
@@ -477,8 +628,17 @@ type RenderConfig = {
     labels: {
         /** false = hide all; true = show all; array = show only listed types */
         active: boolean | ('lithology' | 'fractures' | 'caves')[];
-        /** Fine-grained lithology sub-item control; defaults to true when lithology is active */
-        lithology?: boolean | ('depth' | 'description' | 'dividers')[];
+        /** Fine-grained lithology sub-item control; `true` = depth, description and dividers */
+        lithology?: boolean | LithologyLabelItem[];
+        /**
+         * Marks layers and construction items that start above the panel (they
+         * continue from the previous one): `↑ {prefix} · from–to` on lithology
+         * annotations, a leading `↑` on construction labels.
+         */
+        continuation: {
+            active: boolean;
+            prefix: string;
+        };
         typeLabels?: {
             fracture?: string;
             fractureWater?: string;
@@ -510,6 +670,46 @@ type RenderConfig = {
         outerEdgeWidth: number;
     };
     legend: LegendRenderConfig;
+    /**
+     * Mini-map: the whole well's lithology drawn as a thin column in the
+     * panel's left margin, with a window outlining the panel's depth range.
+     */
+    overview: {
+        active: boolean;
+        /** Left edge in SVG coordinates. */
+        x: number;
+        width: number;
+        /** Height in pixels; capped at the panel's drawing height. */
+        height: number;
+    };
+    /**
+     * Column titles drawn in the panel's top margin, over a rule that sits
+     * `construction.cementPad.height` px above the drawing area (clear of the
+     * pad). The top margin must hold `height` plus that.
+     */
+    columnHeaders: {
+        active: boolean;
+        /** Height of the header row, taken from the top margin. */
+        height: number;
+        labels: {
+            depth: string;
+            lithology: string;
+            construction: string;
+            /** Shown only when lithology annotations are drawn. */
+            description: string;
+        };
+    };
+    /** Circled 1-based index on each lithology layer, `F{n}` next to each fracture. */
+    markers: {
+        lithology: boolean;
+        fractures: boolean;
+        radius: number;
+    };
+    /** Band over the depths a panel repeats (`SvgInstance.repeatedTo`). */
+    overlap: {
+        /** `{range}` is replaced by the repeated depth range, e.g. `116–124 m`. */
+        label: string;
+    };
     highlights: {
         stroke: string;
         strokeWidth: number;
@@ -545,6 +745,7 @@ type LegendRenderConfig = {
         wellScreen: string;
         reduction: string;
         centralizer: string;
+        pump: string;
         cementPad: string;
         conflict: string;
     };
@@ -566,6 +767,18 @@ type SvgInstance = {
         top: number;
         bottom: number;
     };
+    /**
+     * Depth window `[from, to]` (m) drawn in this panel. When every panel has
+     * one, `draw()` uses them instead of splitting the depth in proportion to
+     * the panel heights, so panels may overlap or skip depths.
+     */
+    depthRange?: [number, number];
+    /**
+     * Depth (m) down to which the panel repeats the bottom of the previous
+     * one. The repeated band `[depthRange[0], repeatedTo]` is hatched and
+     * labelled with `RenderConfig.overlap.label`.
+     */
+    repeatedTo?: number;
 };
 /**
  * Attaches an optional stable render identity to any feature type.
@@ -611,21 +824,56 @@ type RenderableWell = Omit<Well, 'lithology' | 'fractures' | 'caves' | 'bore_hol
 declare const RENDER_LABELS: RenderLabelPack;
 /**
  * Returns a copy of `config` with `constructionLabels.labels`, `legend.labels`,
- * `tooltipLabels`, and `labels.typeLabels` resolved from `RENDER_LABELS` for
- * `locale`. Every other field of `config` is preserved unchanged.
+ * `tooltipLabels`, `labels.typeLabels`, `labels.continuation.prefix`,
+ * `columnHeaders.labels` and `overlap.label` resolved from `RENDER_LABELS`
+ * for `locale`. Every other field of `config` is preserved unchanged.
  */
 declare function applyRenderLocale(config: RenderConfig, locale: 'en' | 'pt'): RenderConfig;
 declare const DEFAULT_WELL_THEME: WellTheme;
 declare const STATIC_RENDER_CONFIG: RenderConfig;
 declare const INTERACTIVE_RENDER_CONFIG: RenderConfig;
 
+type LegendLabelKey = keyof LegendRenderConfig['labels'];
+/**
+ * One entry of a well's legend: `key` names the entry (and its label in
+ * `LegendRenderConfig['labels']`), the other fields select its symbol.
+ */
+type WellLegendItem = {
+    kind: 'fracture';
+    key: 'fractureSingle' | 'fractureSwarm' | 'fractureWater';
+    label: string;
+    swarm: boolean;
+    water_intake: boolean;
+} | {
+    kind: 'cave';
+    key: 'caveDry' | 'caveWet';
+    label: string;
+    water_intake: boolean;
+} | {
+    kind: 'construction';
+    key: ConstructionSubKind;
+    label: string;
+    subKind: ConstructionSubKind;
+};
+type ConstructionSubKind = Exclude<LegendLabelKey, 'fractureSingle' | 'fractureSwarm' | 'fractureWater' | 'caveDry' | 'caveWet'>;
 /**
- * Dynamically imports the FGDC texture registry (SVG path data keyed by texture code).
- * Useful for external UIs that need to display texture thumbnails in selection controls.
+ * Lists the legend entries `profile` needs, in display order, labeled from
+ * `labels` (defaults to the built-in Portuguese labels).
  */
-declare function importFgdcTextures(): Promise<{
-    [code: TextureCode]: string;
-}>;
+declare function getWellLegendItems(profile: Well, labels?: LegendRenderConfig['labels']): WellLegendItem[];
+type LegendOptions = {
+    config?: Partial<LegendRenderConfig>;
+    theme?: Partial<WellTheme>;
+    classNames?: ComponentsClassNames['legend'];
+    textures?: TexturesConfig;
+};
+/**
+ * Draws a single legend symbol into its own `<svg>` (matched by `selector`),
+ * sized to the symbol plus a small margin, with the textures it needs
+ * defined inside — so the markup renders standalone, e.g. in a PDF table.
+ */
+declare function drawWellLegendSymbol(selector: string, item: WellLegendItem, options?: Omit<LegendOptions, 'config'>): void;
+declare function drawWellLegend(selector: string, profile: Well, options?: LegendOptions): void;
 
 /**
  * SVG-based renderer for geological well profiles.
@@ -677,6 +925,20 @@ declare class WellRenderer {
     private initInstanceSvg;
     /** Renders a standalone legend into the element matched by `selector`. */
     renderLegend(selector: string, profile: Well): void;
+    /** Lists the legend entries `profile` needs, labeled from `renderConfig.legend.labels`. */
+    getLegendItems(profile: Well): WellLegendItem[];
+    /**
+     * Renders one legend entry's symbol (see {@link getLegendItems}) into its
+     * own SVG matched by `selector`, with the textures it needs defined inside.
+     */
+    renderLegendSymbol(selector: string, item: WellLegendItem): void;
+    /**
+     * Renders one lithology layer's fill as a `size`×`size` square into its
+     * own SVG matched by `selector`, with its texture defined inside (e.g. for
+     * a swatch in a PDF table). Call after `prepareSvg()`, which loads the
+     * FGDC textures.
+     */
+    renderLithologySwatch(selector: string, layer: Lithology, size?: number): void;
     /**
      * Multiplies the current zoom scale by `factor` (e.g. `1.25` to zoom in,
      * `1 / 1.25` to zoom out) on every panel. No-op if both `renderConfig.zoom`
@@ -693,13 +955,21 @@ declare class WellRenderer {
      * Returns `1` if zoom/pan is disabled or `prepareSvg()` hasn't run yet.
      */
     getZoomScale(): number;
+    /**
+     * Removes everything drawn on every panel (layers, labels, axis,
+     * highlights) and keeps the structure `prepareSvg()` built, so the next
+     * `draw()` needs no new `prepareSvg()`. `draw()` calls it for an empty well.
+     */
+    clear(): void;
     /**
      * Initialises the SVG DOM structure and preloads FGDC textures.
      * Must be called once before the first `draw()`.
      */
     prepareSvg(): Promise<void>;
     /**
-     * Renders the well profile into all configured SVG panels.
+     * Renders the well profile into all configured SVG panels. Layers the
+     * profile no longer has are removed; an empty well (`isWellEmpty`) clears
+     * the panels (see {@link clear}).
      * @param profile - The well data to render.
      * @param options.units - Override the instance-level measurement units for this render.
      * @param options.locale - Override the instance-level locale for this render.
@@ -713,13 +983,6 @@ declare class WellRenderer {
     private drawLogToInstance;
 }
 
-declare function drawWellLegend(selector: string, profile: Well, options?: {
-    config?: Partial<LegendRenderConfig>;
-    theme?: Partial<WellTheme>;
-    classNames?: ComponentsClassNames['legend'];
-    textures?: TexturesConfig;
-}): void;
-
 /**
  * Formats a depth value in metres to the active length unit string, rounded
  * (never raw floating-point) and using the target locale's decimal separator.
@@ -740,10 +1003,27 @@ declare function getLengthUnit(units: LengthUnits): string;
  */
 declare function getDiameterUnit(units: DiameterUnits, locale?: 'en' | 'pt'): string;
 /**
- * Resolves a paired-locale render label to a plain string. A bare string is
- * returned as-is (locale-invariant); for the `{ pt, en }` object form, `pt`
- * is always the fallback — mirrors the org-wide `resolveLanguageText()` contract.
+ * Resolves a render label to a plain string: core `resolveLanguageText()`
+ * with `pt` as the fallback locale. A bare string is returned as-is
+ * (locale-invariant).
  */
 declare function resolveRenderLabel(value: RenderLocalizedText, locale: 'en' | 'pt'): string;
 
-export { type CaveTheme, type ComponentsClassNames, type ConstructionTheme, DEFAULT_WELL_THEME, type DeepPartial, type FractureTheme, type HighlightItem, type Highlights, INTERACTIVE_RENDER_CONFIG, type LabelsTheme, type LegendRenderConfig, type LegendTheme, type LithologyTextureTheme, type LithologyTheme, RENDER_LABELS, type RenderConfig, type RenderLabelPack, type RenderLocalizedText, type RenderableWell, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, type TooltipLabels, WellRenderer, type WellTheme, type WithKey, applyRenderLocale, drawWellLegend, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, importFgdcTextures, resolveRenderLabel };
+/**
+ * Topmost depth (m) the profile draws: `0` (the surface), or above it when
+ * a casing, screen or surface case starts at a negative depth (pipe
+ * stick-up above the ground).
+ */
+declare function getProfileTopDepth(profile: {
+    surface_case?: {
+        from: number;
+    }[];
+    well_case?: {
+        from: number;
+    }[];
+    well_screen?: {
+        from: number;
+    }[];
+}): number;
+
+export { type CaveTheme, type ColumnHeadersTheme, type ComponentsClassNames, type ConstructionTheme, DEFAULT_WELL_THEME, type DeepPartial, type FractureTheme, type HighlightItem, type Highlights, INTERACTIVE_RENDER_CONFIG, type LabelsTheme, type LegendRenderConfig, type LegendTheme, type LithologyLabelItem, type LithologyTextureTheme, type LithologyTheme, type MarkersTheme, type OverlapTheme, type OverviewTheme, RENDER_LABELS, type RenderConfig, type RenderLabelPack, type RenderLocalizedText, type RenderableWell, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, type TooltipLabels, type WellLegendItem, WellRenderer, type WellTheme, type WithKey, applyRenderLocale, drawWellLegend, drawWellLegendSymbol, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, getProfileTopDepth, getWellLegendItems, resolveRenderLabel };