katucharts.js 0.2.1

package/dist/layout/LayoutEngine.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Computes the plot area by measuring title, subtitle, axes, and legend space.
+ */
+import type { InternalConfig, PlotArea } from '../types/options';
+export interface LayoutResult {
+    plotArea: PlotArea;
+    titleArea: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    subtitleArea: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    legendArea: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export declare class LayoutEngine {
+    compute(config: InternalConfig, chartWidth: number, chartHeight: number): LayoutResult;
+    private isNonCartesian;
+    private getSpacing;
+    private estimateTextHeight;
+    private estimateWrappedTextHeight;
+    private computeAutoFontSize;
+    private estimateLegendHeight;
+    /**
+     * Horizontal space reserved for a vertical legend pinned to the left/right
+     * edge — the widest of the series labels and (when present) the bubble-legend
+     * size-reference cluster.
+     */
+    private estimateLegendWidth;
+    private estimateSeriesLegendHeight;
+    private estimateAxisWidth;
+    private estimateLabelWidth;
+    private estimateAxisHeight;
+}

package/dist/license/LicenseManager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Singleton that manages license state globally across all chart instances.
+ *
+ * Validation is hybrid:
+ *  - Offline: Ed25519 signature check, synchronous and instant. The bundle
+ *    carries only the public key, so it can verify keys but never sign them.
+ *    This alone governs behaviour when no verifyUrl is configured.
+ *  - Online (opt-in via configureLicensing): a background POST to the issuing
+ *    backend confirms the key is genuine, the subscription is active, and the
+ *    current host is within the key's seat limit. Results are cached with an
+ *    offline grace window. In 'strict' mode, once the grace window lapses a
+ *    successful online check becomes mandatory; in 'lenient' mode an unreachable
+ *    backend falls back to the offline signature.
+ */
+export interface LicensePayload {
+    customer: string;
+    domains?: string[];
+    expiry?: string;
+    kid?: string;
+}
+export type LicenseMode = 'strict' | 'lenient';
+export interface LicenseConfig {
+    /** Backend endpoint for the online check, e.g. https://api.host/api/v1/license/verify */
+    verifyUrl?: string;
+    /** Behaviour once the offline grace window lapses. Defaults to 'lenient'. */
+    mode?: LicenseMode;
+    /** How long an offline/unconfirmed key keeps working since its last successful
+     *  online 'valid', in milliseconds. Defaults to 7 days. */
+    gracePeriodMs?: number;
+    /** Background re-check cadence while a key is set, in milliseconds. Defaults to 1 hour. */
+    recheckIntervalMs?: number;
+}
+declare class LicenseManagerClass {
+    private licenseKey;
+    private payload;
+    private offlineValid;
+    private verifyUrl;
+    private mode;
+    private gracePeriodMs;
+    private recheckIntervalMs;
+    private cache;
+    private pending;
+    private timer;
+    private listeners;
+    private lastEmitted;
+    configure(config: LicenseConfig): void;
+    setKey(key: string): boolean;
+    isLicensed(): boolean;
+    getPayload(): LicensePayload | null;
+    /** Subscribe to license-state transitions. Returns an unsubscribe function. */
+    onChange(cb: (licensed: boolean) => void): () => void;
+    private startOnlineChecks;
+    private verifyOnline;
+    private applyResult;
+    private emit;
+    private loadCache;
+    private saveCache;
+    private validate;
+    private checkExpiry;
+    private checkDomain;
+}
+export declare const LicenseManager: LicenseManagerClass;
+export {};

package/dist/options/defaults.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Default option values for KatuCharts.
+ */
+import type { KatuChartsOptions } from '../types/options';
+export declare const defaultOptions: KatuChartsOptions;

package/dist/react/KatuChartsReact.d.ts

@@ -0,0 +1,16 @@
+import { type HTMLAttributes } from 'react';
+interface KatuChartsStatic {
+    chart(container: string | HTMLElement, options: Record<string, unknown>): KatuChartInstance;
+}
+interface KatuChartInstance {
+    update(options: Record<string, unknown>, redraw?: boolean): void;
+    destroy(): void;
+}
+export interface KatuChartsReactProps {
+    katuCharts: KatuChartsStatic;
+    options: Record<string, unknown>;
+    callback?: (chart: KatuChartInstance) => void;
+    containerProps?: HTMLAttributes<HTMLDivElement>;
+}
+export declare const KatuChartsReact: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<KatuChartsReactProps & import("react").RefAttributes<HTMLDivElement>>>;
+export {};

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+export { KatuChartsReact } from './react/KatuChartsReact';
+export type { KatuChartsReactProps } from './react/KatuChartsReact';

package/dist/responsive/ResponsiveEngine.d.ts

@@ -0,0 +1,15 @@
+import type { ResponsiveOptions, ResponsiveRuleOptions } from '../types/options';
+export declare class ResponsiveEngine {
+    private rules;
+    private activeIndices;
+    constructor(config: ResponsiveOptions);
+    evaluate(chartWidth: number, chartHeight: number): {
+        changed: boolean;
+        matchingIndices: number[];
+    };
+    getRules(): ResponsiveRuleOptions[];
+    getCurrentActiveIndices(): number[];
+    reset(): void;
+    private setsEqual;
+    private matchesCondition;
+}

package/dist/series/BaseSeries.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Base class for all series types. Defines the template method pattern
+ * with shared data labels, selection, clipping, shadow, and inactive state support.
+ */
+import { Selection } from 'd3-selection';
+import 'd3-transition';
+import type { InternalSeriesConfig, PointOptions, PlotArea, DashStyleType } from '../types/options';
+import type { AxisInstance } from '../axis/Axis';
+import { EventBus } from '../core/EventBus';
+export interface SeriesContext {
+    plotArea: PlotArea;
+    xAxis: AxisInstance;
+    yAxis: AxisInstance;
+    colorIndex: number;
+    colors: string[];
+    events: EventBus;
+    chartGroup: Selection<SVGGElement, unknown, null, undefined>;
+    plotGroup?: Selection<SVGGElement, unknown, null, undefined>;
+    totalSeriesOfType?: number;
+    indexInType?: number;
+    animate?: boolean;
+    stackOffsets?: Map<number | string, number>;
+    stackTotals?: Map<number | string, number>;
+    allSeries?: BaseSeries[];
+    inverted?: boolean;
+    legendConfig?: {
+        align?: string;
+        layout?: string;
+        verticalAlign?: string;
+        [key: string]: any;
+    };
+    pane?: {
+        size?: string | number;
+        [key: string]: any;
+    };
+    /** Chart background — lets labels drawn on it pick a readable color automatically. */
+    backgroundColor?: string;
+}
+type AnimatedRedrawFn = (duration?: number) => void;
+export declare const STAGGER_MAX_POINTS = 500;
+export declare function staggerDelay(index: number, base: number, perItem: number, totalItems: number): number;
+export declare const DASH_STYLE_MAP: Record<string, string>;
+export declare function resolveDashArray(style?: DashStyleType | string): string;
+export declare function brightenColor(color: string, amount: number): string;
+export declare abstract class BaseSeries {
+    config: InternalSeriesConfig;
+    protected context: SeriesContext;
+    protected group: Selection<SVGGElement, unknown, null, undefined>;
+    protected clipId?: string;
+    protected selectedPoints: Set<number>;
+    visible: boolean;
+    data: PointOptions[];
+    private _cachedExtents;
+    private _onVisibilityChange?;
+    constructor(config: InternalSeriesConfig);
+    init(context: SeriesContext): void;
+    setOnVisibilityChange(fn: AnimatedRedrawFn): void;
+    processData(): void;
+    getColor(): string;
+    /**
+     * Readable color for a label drawn on the chart background. An explicit color
+     * always wins; otherwise dark ink is used on light backgrounds and switched to
+     * light on dark ones (WCAG-based), so labels stay legible under any theme.
+     */
+    protected autoLabelColor(override?: string): string;
+    /**
+     * Text halo (`text-shadow`) for labels placed over busy fills like maps. The
+     * halo contrasts with the label so the outline reads on both light and dark
+     * backgrounds instead of glowing white on dark themes. `readableTextColor`
+     * returns white only when the background is dark enough to need light text.
+     */
+    protected labelHalo(): string;
+    /** Single halo color (for SVG `stroke` outlines) that contrasts with the label. */
+    protected labelHaloColor(): string;
+    /**
+     * Border/separator color for cells, slices, nodes and point markers. Matches
+     * the chart background so adjacent shapes read as clean gaps on any theme —
+     * dark gaps on dark backgrounds instead of harsh white grid lines. Falls back
+     * to white on transparent/unset backgrounds (the light-theme default).
+     */
+    protected autoBorderColor(): string;
+    getMultiLegendItems(): {
+        label: string;
+        color: string;
+    }[] | null;
+    getLegendSymbolShape(): string | null;
+    /**
+     * Size-reference data for a bubble legend. Returns null for every series
+     * type except bubble, which overrides this to report the pixel radius that
+     * maps to each reference z value so the legend can draw matching circles.
+     */
+    getBubbleLegendInfo(): {
+        sizeBy: 'area' | 'width';
+        color: string;
+        ranges: {
+            value: number;
+            radius: number;
+        }[];
+    } | null;
+    abstract render(): void;
+    /**
+     * Animate elements to new positions after axis domain change.
+     */
+    animateUpdate(duration: number): void;
+    /**
+     * Update context (axes, grouping info) without re-init.
+     */
+    updateContext(partial: Partial<SeriesContext>): void;
+    redraw(): void;
+    setVisible(visible: boolean, animate?: boolean): void;
+    toggleVisible(): void;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    getCategories(): string[];
+    destroy(): void;
+    /**
+     * Replace all data in the series and optionally trigger a redraw.
+     */
+    setData(data: PointOptions[], redraw?: boolean, animation?: boolean): void;
+    /**
+     * Append a single point and optionally shift the oldest one off.
+     */
+    addPoint(point: PointOptions, redraw?: boolean, shift?: boolean, animation?: boolean): void;
+    /**
+     * Batch-append multiple points and optionally shift the oldest ones off.
+     */
+    addPoints(points: PointOptions[], redraw?: boolean, shift?: boolean, animation?: boolean): void;
+    /**
+     * Remove a point by index.
+     */
+    removePoint(index: number, redraw?: boolean, animation?: boolean): void;
+    /**
+     * Merge new options into this series config and optionally redraw.
+     */
+    updateSeries(options: Partial<InternalSeriesConfig>, redraw?: boolean): void;
+    /**
+     * Apply a coalesced batch of updates from the UpdateScheduler.
+     * Override in subclasses for incremental rendering.
+     */
+    applyBatch(batch: {
+        entries: {
+            type: string;
+            payload: any;
+        }[];
+    }): void;
+    show(): void;
+    hide(): void;
+    /**
+     * Return all currently selected point indices and their data.
+     */
+    getSelectedPoints(): {
+        index: number;
+        point: PointOptions;
+    }[];
+    protected applyClipPath(): void;
+    protected applyShadowFilter(): void;
+    /**
+     * Dim all other series when this series is hovered.
+     */
+    protected applyInactiveState(): void;
+    protected clearInactiveState(): void;
+    /**
+     * Emit afterAnimate event and invoke animation.complete callback at the end of the entry animation.
+     */
+    protected emitAfterAnimate(delay: number): void;
+    /**
+     * Render data labels for all visible points based on dataLabels config.
+     */
+    protected renderDataLabels(data: PointOptions[], getX: (d: PointOptions, i: number) => number, getY: (d: PointOptions, i: number) => number): void;
+    /**
+     * Handle point selection toggle when allowPointSelect is enabled.
+     */
+    protected handlePointSelect(element: Selection<any, any, any, any>, point: PointOptions, index: number, event: MouseEvent): void;
+    protected applySelectStyle(element: Selection<any, any, any, any>): void;
+    protected clearSelectStyle(element: Selection<any, any, any, any>): void;
+    protected attachPointEvents(element: Selection<any, any, any, any>, point: PointOptions, index: number): void;
+    /**
+     * Apply jitter offset to a coordinate value.
+     */
+    protected applyJitter(value: number, range: number, jitterAmount?: number): number;
+}
+export {};

package/dist/series/bioinformatics/CircosChart.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export from modular circos system for backward compatibility.
+ */
+export { CircosChart } from './circos/CircosChart';

package/dist/series/bioinformatics/ClusteredHeatmapChart.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Clustered heatmap with row and column dendrograms.
+ * Extends heatmap concepts with hierarchical clustering visualization
+ * using d3-hierarchy cluster layout.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class ClusteredHeatmapChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private renderHeatmapCells;
+    private renderRowDendrogram;
+    private renderColDendrogram;
+    private renderLabels;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/ForestPlotChart.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Forest plot for meta-analysis visualization.
+ * Horizontal effect sizes with confidence intervals, weight-proportional markers,
+ * and diamond shapes for summary estimates.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class ForestPlotChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private renderNullEffectLine;
+    private renderDiamond;
+    private attachRowEvents;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/KaplanMeierChart.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Kaplan-Meier survival curve with step function, confidence interval bands,
+ * censoring marks, and optional at-risk table.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class KaplanMeierChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private renderSurvivalCurve;
+    private renderConfidenceInterval;
+    private renderCensoringMarks;
+    private renderMedianLine;
+    private renderAtRiskTable;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/ManhattanChart.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Manhattan plot for genome-wide association studies (GWAS).
+ * Points grouped by chromosome with alternating colors and significance threshold lines.
+ *
+ * Optimized for large datasets:
+ * - Canvas rendering when data exceeds canvasThreshold (default 20000)
+ * - Stack-safe min/max computations
+ * - Significance points rendered as SVG overlay on top of canvas for interactivity
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class ManhattanChart extends BaseSeries {
+    private chrGroups;
+    private positions;
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private groupByChromosome;
+    private getChrIndex;
+    private buildChrColorMap;
+    private renderSignificanceLines;
+    private renderPointsCanvas;
+    private renderSignificantPointsSVG;
+    private renderChromosomePoints;
+    private renderChromosomeLabels;
+    private renderTopLabels;
+    private attachManhattanEvents;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/PCoAChart.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PCoA / Ordination scatter plot with an optional confidence ellipse per series.
+ *
+ * Behaves like scatter for point rendering but owns the ellipse: its extents are
+ * contributed to the axis domain calculation and the ellipse path is rendered inside
+ * the series group, so ellipses always fit inside the plot area without callers having
+ * to pre-compute axis min/max.
+ */
+import { ScatterChart } from '../cartesian/ScatterChart';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class PCoAChart extends ScatterChart {
+    constructor(config: InternalSeriesConfig);
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    render(): void;
+    animateUpdate(duration: number): void;
+    private renderEllipse;
+}

package/dist/series/bioinformatics/PhyloTreeChart.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Phylogenetic tree for evolutionary relationship visualization.
+ * Supports rectangular and radial layouts with branch length scaling,
+ * bootstrap values, and interactive subtree collapse.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class PhyloTreeChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private getTreeData;
+    private estimateLabelSpace;
+    private renderRectangular;
+    private renderRadial;
+    private scaleBranchLengths;
+    private getDistanceFromRoot;
+    private getMaxDistance;
+    private renderScaleBar;
+    private attachTreeEvents;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/SequenceLogoChart.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sequence logo for visualizing conserved sequence motifs.
+ * Stacked letters proportional to information content at each position.
+ * Supports DNA, RNA, and protein alphabets with configurable color schemes.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class SequenceLogoChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private getDefaultColors;
+    private getColumnWidth;
+    private attachPositionEvents;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/ViolinChart.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Violin plot with kernel density estimation for distribution visualization.
+ * Supports optional inner boxplot, jittered points, and split violins.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class ViolinChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private renderInnerBoxplot;
+    private renderInnerPoints;
+    private quantile;
+    private median;
+    private computeViolinGeometry;
+    private attachViolinEvents;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/VolcanoChart.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Volcano plot for differential expression analysis.
+ * x = log2(fold change), y = -log10(p-value).
+ * Auto-colors points by significance and renders threshold lines.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../BaseSeries';
+import type { InternalSeriesConfig } from '../../types/options';
+export declare class VolcanoChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    getMultiLegendItems(): {
+        label: string;
+        color: string;
+    }[] | null;
+    render(): void;
+    private classifyPoint;
+    private getPointColor;
+    private renderThresholdLines;
+    private renderPoints;
+    private renderTopLabels;
+    private attachVolcanoEvents;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/circos/CircosChart.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Circos plot for circular multi-track genome visualization.
+ * Refactored to use modular track renderers and shared layout engine.
+ * Supports 14 track types: scatter, line, histogram, heatmap, link, highlight,
+ * stack, text, tile, ribbon, connector, area, glyph, lollipop.
+ */
+import { BaseSeries } from '../../BaseSeries';
+import type { InternalSeriesConfig } from '../../../types/options';
+export declare class CircosChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    private renderTrack;
+    private getCircosData;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+}

package/dist/series/bioinformatics/circos/CircosColorScales.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Color scale factory mapping named scales to D3 interpolator functions.
+ * Supports 24 named color scales across sequential, diverging, and multi-hue categories.
+ */
+import type { CircosColorScaleName } from './CircosTypes';
+export declare function getColorInterpolator(name?: CircosColorScaleName): (t: number) => string;

package/dist/series/bioinformatics/circos/CircosComparativeChart.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Species Synteny visualization.
+ * Arranges chromosomes from multiple species on a single circle with
+ * inter-species gaps larger than intra-species gaps, renders species label
+ * arcs above each group, and draws variable-width synteny ribbons between
+ * conserved regions across species.
+ */
+import 'd3-transition';
+import { BaseSeries } from '../../BaseSeries';
+import type { InternalSeriesConfig } from '../../../types/options';
+export declare class CircosComparativeChart extends BaseSeries {
+    constructor(config: InternalSeriesConfig);
+    render(): void;
+    getDataExtents(): {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    private getComparativeData;
+    /**
+     * Build a flat chromosome list with prefixed IDs and appropriate gaps.
+     * Inter-species gaps use speciesGap; intra-species gaps use chrGap.
+     */
+    private buildChromosomeList;
+    private buildPrefixedBlocks;
+    /** Render chromosome labels using the clean ID (without species prefix). */
+    private renderCleanLabels;
+    /** Render curved label arcs above each species group. */
+    private renderSpeciesLabelArcs;
+    /** Render synteny ribbons connecting conserved regions across species. */
+    private renderSyntenyRibbons;
+    /**
+     * Inner heatmap ring showing conservation scores at BOTH source and target
+     * positions of each synteny block, matching real circos conservation tracks.
+     */
+    private renderConservationTrack;
+    /** Build ribbon SVG path: source arc → bezier → target arc → bezier back. */
+    private buildRibbonPath;
+    private adjustColorBrightness;
+}