@welldot/render 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,531 @@
+import { Units, Well, DiameterUnits, LengthUnits } from '@welldot/core';
+
+type PadTextureConfig = {
+    background: string;
+    stroke: string;
+};
+type ConflictTextureConfig = {
+    stroke: string;
+};
+type CaveDryTextureConfig = {
+    size: number;
+    stroke: string;
+    background: string;
+};
+type CaveWetTextureConfig = {
+    size: number;
+    stroke: string;
+    background: string;
+};
+type SealTextureConfig = {
+    background: string;
+};
+type GravelPackTextureConfig = {
+    size: number;
+    background: string;
+};
+type WellScreenTextureConfig = {
+    size: number;
+    strokeWidth: number;
+    background: string;
+};
+type SurfaceCaseTextureConfig = {
+    orientation: string[];
+    size: number;
+    strokeWidth: number;
+    shapeRendering: string;
+    stroke: string;
+    background: string;
+};
+type TexturesConfig = {
+    pad?: Partial<PadTextureConfig>;
+    conflict?: Partial<ConflictTextureConfig>;
+    cave_dry?: Partial<CaveDryTextureConfig>;
+    cave_wet?: Partial<CaveWetTextureConfig>;
+    seal?: Partial<SealTextureConfig>;
+    gravel_pack?: Partial<GravelPackTextureConfig>;
+    well_screen?: Partial<WellScreenTextureConfig>;
+    surface_case?: Partial<SurfaceCaseTextureConfig>;
+};
+
+/** Recursively makes all properties of T optional — used for deep-mergeable option objects. */
+type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** A single highlight overlay item. Use `from`+`to` for depth-range highlights, `depth` for point highlights. */
+type HighlightItem = {
+    label?: string;
+    from?: number;
+    to?: number;
+    depth?: number;
+    diameter?: number;
+};
+/** Highlight overlay configuration passed to `draw()`. Each key targets a specific well component. */
+type Highlights = {
+    lithology?: HighlightItem[];
+    caves?: HighlightItem[];
+    fractures?: HighlightItem[];
+    cement_pad?: HighlightItem;
+    bore_hole?: HighlightItem[];
+    surface_case?: HighlightItem[];
+    hole_fill?: HighlightItem[];
+    well_case?: HighlightItem[];
+    well_screen?: HighlightItem[];
+};
+type LithologyTheme = {
+    stroke: string;
+    strokeWidth: number;
+};
+type LithologyTextureTheme = {
+    size: number;
+    strokeWidth: number;
+    stroke: string;
+};
+type CaveTheme = {
+    dryStroke: string;
+    wetStroke: string;
+    fillOpacity: number;
+    contactStrokeWidth: number;
+};
+type FractureTheme = {
+    dryStroke: string;
+    wetStroke: string;
+    swarm: {
+        centralStrokeWidth: number;
+        sideStrokeWidthBase: number;
+        sideStrokeWidthVariance: number;
+    };
+    single: {
+        mainStrokeWidth: number;
+        crackStrokeWidth: number;
+    };
+};
+type ConstructionTheme = {
+    cementPad: {
+        stroke: string;
+        strokeWidth: number;
+    };
+    boreHole: {
+        fill: string;
+        stroke: string;
+        strokeDasharray: string;
+        opacity: number;
+        strokeWidth: number;
+    };
+    surfaceCase: {
+        stroke: string;
+        strokeWidth: number;
+    };
+    holeFill: {
+        stroke: string;
+        strokeWidth: number;
+    };
+    wellCase: {
+        fill: string;
+        stroke: string;
+        strokeWidth: number;
+    };
+    wellScreen: {
+        stroke: string;
+        strokeWidth: number;
+    };
+    conflict: {
+        stroke: string;
+        strokeWidth: number;
+    };
+};
+type LabelsTheme = {
+    unitLabels: {
+        geologicFill: string;
+        aquiferFill: string;
+        stroke: string;
+        strokeWidth: number;
+        fontSize: number;
+        fontFamily?: string;
+        fontWeight?: string | number;
+    };
+    constructionLabels: {
+        fontSize: number;
+        labelFill: string;
+        labelColor: string;
+        fontFamily?: string;
+        fontWeight?: string | number;
+    };
+    labels: {
+        dividerStroke: string;
+        dividerStrokeWidth: number;
+        dividerStrokeDasharray: string;
+        fontSize: number;
+        scaleFontSize?: number;
+        color: string;
+        headerFont: string;
+        bodyColor: string;
+        bodyFont?: string;
+        scaleFont?: string;
+        depthTipFill?: string;
+        depthTipRadius?: number;
+        annotationBg?: string;
+        annotationBgOpacity?: number;
+        annotationBorderColor?: string;
+        annotationRadius?: number;
+        headerFontWeight?: string | number;
+        bodyFontWeight?: string | number;
+        fractureLabelFontSize?: number;
+        caveLabelFontSize?: number;
+    };
+};
+type LegendTheme = {
+    borderStrokeWidth: number;
+    fractureStrokeWidth: number;
+    fractureSideStrokeWidth: number;
+    itemStrokeWidth: number;
+    fontSize: number;
+    fontFamily?: string;
+    titleFontWeight?: string | number;
+    labelFontWeight?: string | number;
+};
+/** Visual styling theme for all well components. Use `DEFAULT_WELL_THEME` as a base and pass `DeepPartial<WellTheme>` overrides. */
+type WellTheme = {
+    lithology: LithologyTheme;
+    lithologyTexture: LithologyTextureTheme;
+    cave: CaveTheme;
+    fracture: FractureTheme;
+} & ConstructionTheme & LabelsTheme & {
+    legend: LegendTheme;
+};
+type ComponentsClassNames = {
+    tooltip: {
+        root: string;
+        title: string;
+        primaryInfo: string;
+        secondaryInfo: string;
+    };
+    yAxis: string;
+    wellGroup: string;
+    geologicGroup: string;
+    lithology: {
+        group: string;
+        rect: string;
+    };
+    labels: {
+        lithology: {
+            group: string;
+            depth: string;
+            label: string;
+            divider: string;
+        };
+    };
+    fractures: {
+        group: string;
+        item: string;
+        hitArea: string;
+        line: string;
+        polyline: string;
+    };
+    caves: {
+        group: string;
+        item: string;
+        fill: string;
+        contact: string;
+    };
+    constructionGroup: string;
+    constructionLabels: {
+        group: string;
+    };
+    cementPad: {
+        group: string;
+        item: string;
+    };
+    boreHole: {
+        group: string;
+        rect: string;
+    };
+    surfaceCase: {
+        group: string;
+        rect: string;
+    };
+    holeFill: {
+        group: string;
+        rect: string;
+    };
+    wellCase: {
+        group: string;
+        rect: string;
+    };
+    wellScreen: {
+        group: string;
+        rect: string;
+    };
+    conflict: {
+        group: string;
+        rect: string;
+    };
+    unitLabels: {
+        group: string;
+        geoRect: string;
+        aqRect: string;
+        text: string;
+    };
+    legend: {
+        border: string;
+        title: string;
+        item: string;
+        label: string;
+        fracturePoly: string;
+        caveFill: string;
+        constructionRect: string;
+    };
+    highlights: {
+        geologicGroup: string;
+        constructionGroup: string;
+        fracturesGroup: string;
+        item: string;
+        rect: string;
+        label: string;
+        labelBg: string;
+    };
+};
+/** Keys identifying which tooltip types are active. Pass to `RenderConfig.tooltips` to control visibility. */
+type TooltipKey = 'geology' | 'hole' | 'surfaceCase' | 'holeFill' | 'wellCase' | 'wellScreen' | 'conflict' | 'fracture' | 'cementPad' | 'cave';
+/** Full rendering behaviour configuration. Use `INTERACTIVE_RENDER_CONFIG` or `STATIC_RENDER_CONFIG` as a starting point. */
+type RenderConfig = {
+    zoom: boolean;
+    pan: boolean;
+    /** Initial zoom scale applied on first render (1 = fit all, 2 = start 2× zoomed in). */
+    zoomLevel?: number;
+    /** undefined = show all; false or [] = show none; array = show only listed keys */
+    tooltips?: TooltipKey[] | false;
+    animation: {
+        duration: number;
+        ease: (t: number) => number;
+    };
+    geologic: {
+        xLeft: number;
+        xRightInset: number;
+    };
+    layout: {
+        pocoWidthRatio: number;
+        pocoCenterRatio: number;
+    };
+    caves: {
+        pathSteps: number;
+        amplitude: {
+            ratio: number;
+            min: number;
+            max: number;
+        };
+    };
+    fractures: {
+        widthMultiplier: number;
+        hitBuffer: {
+            single: number;
+            swarm: number;
+        };
+        swarm: {
+            lineCountBase: number;
+            lineCountVariance: number;
+            spread: number;
+        };
+    };
+    construction: {
+        cementPad: {
+            widthMultiplier: number;
+            thicknessMultiplier: number;
+        };
+        surfaceCase: {
+            diameterPaddingRatio: number;
+        };
+    };
+    textures?: TexturesConfig;
+    constructionLabels: {
+        active: boolean;
+        xOffset: number;
+        labelRadius: number;
+        labelMaxWidth?: number;
+        labels: {
+            wellCasePrefix: string;
+            wellScreenPrefix: string;
+            wellScreenSlotPrefix: string;
+        };
+    };
+    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')[];
+        typeLabels?: {
+            fracture?: string;
+            cave?: string;
+        };
+        depthTipHeight: number;
+        depthTipPadX: number;
+        descriptionXOffset: number;
+        descriptionMaxWidth: number;
+        stackingLineHeight: number;
+        stackingGap: number;
+        fractureLabelLeaderGap?: number;
+        fractureLabelPadX?: number;
+        fractureLabelPadY?: number;
+        caveLabelHeight?: number;
+        caveLabelPadX?: number;
+    };
+    unitLabels: {
+        /** Show geologic_unit and aquifer_unit strips to the left of the lithology column */
+        active: boolean;
+        /** X position of the first (leftmost) strip in geologic group coordinates */
+        xOffset: number;
+        stripWidth: number;
+        minHeightForText: number;
+        /** Stroke width of divider lines between adjacent segments of different units */
+        innerDividerWidth: number;
+        /** Stroke width of the top/bottom boundary (and page-clip edges in multi-SVG rendering) */
+        outerEdgeWidth: number;
+    };
+    legend: LegendRenderConfig;
+    highlights: {
+        stroke: string;
+        strokeWidth: number;
+        fill: string;
+        fillOpacity: number;
+        padding: number;
+        strokeDasharray?: string;
+        labelFontSize: number;
+        labelPadding: number;
+        labelBackground: string;
+        labelColor: string;
+        labelRadius: number;
+    };
+};
+type LegendRenderConfig = {
+    title: string;
+    itemWidth: number;
+    height: number;
+    padding: number;
+    maxWidth?: number;
+    borderRadius: number;
+    labels: {
+        fractureSingle: string;
+        fractureSwarm: string;
+        fractureWater: string;
+        caveDry: string;
+        caveWet: string;
+        boreHole: string;
+        surfaceCase: string;
+        holeFillGravel: string;
+        holeFillSeal: string;
+        wellCase: string;
+        wellScreen: string;
+        cementPad: string;
+        conflict: string;
+    };
+};
+/**
+ * Descriptor for a single SVG panel managed by `WellRenderer`.
+ * @param selector - CSS selector for the `<svg>` element (e.g. `"#well-panel-1"`).
+ * @param height - Inner drawing height in pixels (excludes margins).
+ * @param width - Inner drawing width in pixels (excludes margins).
+ * @param margins - Space reserved around the drawing area for axes and labels.
+ */
+type SvgInstance = {
+    selector: string;
+    height: number;
+    width: number;
+    margins: {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    };
+};
+
+declare const DEFAULT_WELL_THEME: WellTheme;
+declare const STATIC_RENDER_CONFIG: RenderConfig;
+declare const INTERACTIVE_RENDER_CONFIG: RenderConfig;
+
+/**
+ * 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.
+ */
+declare function importFgdcTextures(): Promise<{
+    [code: TextureCode]: string;
+}>;
+
+/**
+ * SVG-based renderer for geological well profiles.
+ *
+ * One instance manages one or more SVG panels (multi-panel layouts for long wells).
+ * Call `prepareSvg()` once to initialise the DOM and preload textures, then call
+ * `draw(profile)` whenever the profile data changes.
+ *
+ * @example
+ * ```ts
+ * const renderer = new WellRenderer(
+ *   [{ selector: '#well-svg', height: 600, width: 300, margins: { top: 20, right: 10, bottom: 20, left: 40 } }],
+ *   { renderConfig: INTERACTIVE_RENDER_CONFIG },
+ * );
+ * await renderer.prepareSvg();
+ * renderer.draw(profile);
+ * ```
+ */
+declare class WellRenderer {
+    private svgInstances;
+    private instanceStates;
+    private textures;
+    private onError?;
+    classes: ComponentsClassNames;
+    private renderConfig;
+    private theme;
+    private units;
+    /**
+     * @param svgs - One entry per SVG panel; multi-entry for split-panel layouts.
+     * @param options.classNames - Override default BEM CSS class names.
+     * @param options.units - Active measurement units (`length` and `diameter`).
+     * @param options.renderConfig - Rendering behaviour (zoom, pan, animation, layout). Defaults to `INTERACTIVE_RENDER_CONFIG`.
+     * @param options.theme - Visual theme overrides. Merged on top of `DEFAULT_WELL_THEME`.
+     * @param options.onError - Called when a draw error occurs (e.g., a renderer throws). Falls back to `console.error` if omitted.
+     */
+    constructor(svgs: SvgInstance[], options?: {
+        classNames?: DeepPartial<ComponentsClassNames>;
+        units?: Units;
+        renderConfig?: DeepPartial<RenderConfig>;
+        theme?: DeepPartial<WellTheme>;
+        onError?: (err: Error) => void;
+    });
+    private initInstanceSvg;
+    /** Renders a standalone legend into the element matched by `selector`. */
+    renderLegend(selector: string, profile: Well): 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.
+     * @param profile - The well data to render.
+     * @param options.units - Override the instance-level measurement units for this render.
+     * @param options.highlights - Highlight overlays to display on top of the profile.
+     */
+    draw(profile: Well, options?: {
+        units?: Units;
+        highlights?: Highlights;
+    }): void;
+    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. */
+declare function formatLength(m: number, units: LengthUnits): string;
+/** Formats a diameter value in millimetres to the active diameter unit string. */
+declare function formatDiameter(mm: number, units: DiameterUnits): string;
+/** Returns the display label for the active length unit (e.g. `"m"` or `"ft"`). */
+declare function getLengthUnit(units: LengthUnits): string;
+/** Returns the display label for the active diameter unit (e.g. `"mm"` or `'"'`). */
+declare function getDiameterUnit(units: DiameterUnits): 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, type RenderConfig, STATIC_RENDER_CONFIG, type SvgInstance, type TooltipKey, WellRenderer, type WellTheme, drawWellLegend, formatDiameter, formatLength, getDiameterUnit, getLengthUnit, importFgdcTextures };