sk-chart-duo 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,520 @@
+interface ExportOptions {
+    /** 'png' rasterizes through a canvas; 'svg' returns the vector markup as a data URL. */
+    type?: 'png' | 'svg';
+    /** Pixel-density multiplier for PNG output. */
+    scale?: number;
+    /** Canvas backdrop painted before drawing the SVG; omit for transparency. */
+    background?: string;
+}
+interface DownloadOptions extends ExportOptions {
+    filename?: string;
+}
+
+type ContainerLike = string | HTMLElement;
+interface BaseConfig {
+    /** viewBox design-space width. */
+    width?: number;
+    /** viewBox design-space height. */
+    height?: number;
+}
+interface ColumnEventPayload<D = unknown> {
+    index: number;
+    datum: D;
+}
+interface ChartEventMap<D = unknown> {
+    'column:enter': ColumnEventPayload<D>;
+    'column:leave': ColumnEventPayload<D>;
+    'column:click': ColumnEventPayload<D>;
+}
+
+/**
+ * Shared lifecycle for all chart classes: container resolution, config merge,
+ * full-rebuild update/resize, event bus and teardown.
+ *
+ * E is the chart-type-specific event map, so each chart declares its own events
+ * without touching core.
+ */
+declare abstract class ChartBase<C extends BaseConfig, E extends object = ChartEventMap> {
+    protected container: HTMLElement;
+    protected config: C;
+    protected svg: SVGSVGElement | null;
+    private handlers;
+    private destroyed;
+    constructor(container: ContainerLike, config: C);
+    get isDestroyed(): boolean;
+    on<K extends keyof E & string>(event: K, handler: (payload: E[K]) => void): this;
+    off<K extends keyof E & string>(event: K, handler: (payload: E[K]) => void): this;
+    protected emit<K extends keyof E & string>(event: K, payload: E[K]): void;
+    /** Merges the partial config and rebuilds the chart. */
+    update(config: Partial<C>): void;
+    /** Changes the viewBox design space and rebuilds (userSpaceOnUse coordinates depend on it). */
+    resize(width: number, height: number): void;
+    /** Standalone SVG markup (embedded style + defs included), renderable as-is. */
+    toSVGString(): string;
+    /** Data URL of the current chart; PNG is rasterized through canvas at `scale` (default 2x). */
+    getDataURL(options?: ExportOptions): Promise<string>;
+    /** Triggers a browser download of the chart, PNG at 2x by default. */
+    download(options?: DownloadOptions): Promise<void>;
+    private requireSvg;
+    destroy(): void;
+    /** Subclasses build (or rebuild) the SVG and attach it to the container. */
+    protected abstract renderChart(): void;
+    /** Subclass teardown hook, called before the SVG is removed. */
+    protected onDestroy(): void;
+}
+
+type GradientStop = readonly [offset: number, color: string];
+
+interface ResolvedFoldBarStyle {
+    stripePattern: StripePatternStyle;
+    barGradientActive: GradientStop[];
+    barGradientNormal: GradientStop[];
+    foldGradient: GradientStop[];
+    creaseGradient: GradientStop[];
+    washTop: number;
+    washGradient: GradientStop[];
+    washEnabled: boolean;
+    pill: PillStyle;
+    shadow: DropShadowStyle;
+    fadeMask: {
+        start: number;
+        end: number;
+    };
+    fadeEnabled: boolean;
+    labelY: number;
+    numberY: number;
+    labelXOffset: number;
+}
+interface FoldBarThemeTokens {
+    fontFamily: string;
+    title: {
+        fill: string;
+        fontSize: number;
+        fontWeight: number;
+        letterSpacing: string;
+    };
+    axis: {
+        fill: string;
+        fontSize: number;
+        fontWeight: number;
+    };
+    label: {
+        fill: string;
+        activeFill: string;
+        fontSize: number;
+        fontWeight: number;
+    };
+    number: {
+        fill: string;
+        activeFill: string;
+        fontSize: number;
+        fontWeight: number;
+        letterSpacing: string;
+    };
+    grid: {
+        stroke: string;
+        strokeWidth: number;
+    };
+    tooltip: {
+        bg: string;
+        stroke: string;
+        fill: string;
+        strongFill: string;
+        softFill: string;
+        fontSize: number;
+    };
+    transition: {
+        state: string;
+        tip: string;
+    };
+}
+/** Top-level optional theme override; nested token groups are partially overridable. */
+type DeepPartialTokens = {
+    [K in keyof FoldBarThemeTokens]?: FoldBarThemeTokens[K] extends object ? Partial<FoldBarThemeTokens[K]> : FoldBarThemeTokens[K];
+};
+
+interface ThemeFormats {
+    valueFormat?: (value: number) => string;
+    tickFormat?: (value: number) => string;
+}
+/** A theme bundle: visual style, typography tokens and default formatters. */
+interface ThemePack {
+    style?: FoldBarStyleConfig;
+    tokens?: DeepPartialTokens;
+    formats?: ThemeFormats;
+}
+/** Runtime type guard: pack keys are disjoint from DeepPartialTokens keys. */
+declare function isThemePack(value: object): value is ThemePack;
+/** Registers (or replaces) a named theme pack usable via `config.theme`. */
+declare function registerTheme(name: string, pack: ThemePack): void;
+declare function getTheme(name: string): ThemePack | undefined;
+
+interface Padding {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface PlotRect {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+interface FoldBarLayout {
+    plot: PlotRect;
+    count: number;
+    colWidth: number;
+    barWidth: number;
+    /** Bar top y when value is 0. */
+    stairBase: number;
+    /** Bar top y of the domain maximum (top tick). */
+    stairTop: number;
+    /** Maximum data value. */
+    maxValue: number;
+    /** Axis domain maximum the bars normalize against. */
+    domainMax: number;
+    barTopOf: (value: number) => number;
+}
+interface BarGeometry {
+    /** Leading edge of the column band (hit area / grid line). */
+    colStart: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    centerX: number;
+}
+interface FlapGeometry {
+    /** SVG polygon points attribute. */
+    points: string;
+    /** Crease segment: from current bar top to next bar top. */
+    crease: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+    /** y range for the userSpaceOnUse fold gradient. */
+    gradientY: [number, number];
+}
+interface PillGeometry {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx: number;
+    shadowX: number;
+    shadowY: number;
+    shadowWidth: number;
+    shadowHeight: number;
+    shadowRx: number;
+}
+interface RectGeometry {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+interface FoldBarDatum {
+    label: string;
+    value: number;
+    [key: string]: unknown;
+}
+interface FoldBarScaleConfig {
+    /** Power applied to normalized values. 1 = linear; 2 reproduces the fold-funnel silhouette. */
+    exponent?: number;
+}
+interface FoldBarFoldConfig {
+    /** Horizontal run reserved for the paper fold between columns. */
+    run?: number;
+    creaseColor?: string;
+    creaseWidth?: number;
+}
+interface FoldBarAxisConfig {
+    /** Explicit tick values, e.g. [70, 60, 50, 40, 30]. Positions map via barTopOf. */
+    ticks?: number[];
+    tickFormat?: (value: number) => string;
+}
+type XAxisLabelFormatter = (datum: FoldBarDatum, index: number, data: FoldBarDatum[]) => string;
+type XAxisBottomFormatter = (datum: FoldBarDatum, index: number, data: FoldBarDatum[]) => string | string[];
+interface FoldBarXAxisTitleConfig {
+    text?: string;
+    /** Defaults to the horizontal center of the plot. */
+    x?: number;
+    /** Defaults to the row below the bottom labels. */
+    y?: number;
+}
+interface FoldBarXAxisConfig {
+    /** Formats the header-row category labels; defaults to the xField value. */
+    labelFormat?: XAxisLabelFormatter;
+    /**
+     * Optional semantic row below the plot (e.g. stage index + step conversion).
+     * Returning an array renders one line per entry. Reserves bottom space.
+     */
+    bottomLabels?: XAxisBottomFormatter;
+    /** Axis caption rendered below the bottom labels. Reserves one bottom row. */
+    title?: FoldBarXAxisTitleConfig;
+    /** Baseline under the bar bottoms (below the fade). Default false to keep the dissolving-paper look. */
+    showLine?: boolean;
+    /** Small marks under each column center. Default false. */
+    showTick?: boolean;
+    /** Vertical column dividers. Default true (previous always-on behavior). */
+    showGrid?: boolean;
+}
+type TooltipTone = 'n' | 'b' | 's';
+interface TooltipPart {
+    text: string;
+    /** 'b' = bold ink, 's' = faded separator, 'n'/omitted = normal. */
+    tone?: TooltipTone;
+}
+type TooltipFormatter = (datum: FoldBarDatum, index: number, data: FoldBarDatum[]) => TooltipPart[];
+interface FoldBarTooltipConfig {
+    enabled?: boolean;
+    formatter?: TooltipFormatter;
+    height?: number;
+    radius?: number;
+    paddingX?: number;
+    anchorRatio?: number;
+    offsetY?: number;
+    minY?: number;
+    /** Skip text measurement and use a fixed width (SSR / testing escape hatch). */
+    fixedWidth?: number;
+}
+interface FoldBarStateConfig {
+    /** Active column when idle. Defaults to the last column. */
+    defaultActive?: number;
+}
+interface FoldBarTitleConfig {
+    text?: string;
+    x?: number;
+    y?: number;
+}
+interface StripePatternStyle {
+    enabled: boolean;
+    size: number;
+    lineWidth: number;
+    lineColor: string;
+    lineOpacity: number;
+    rotation: number;
+}
+interface PillShadowStyle {
+    width: number;
+    height: number;
+    rx: number;
+    offsetY: number;
+    color: string;
+    opacity: number;
+}
+interface PillStyle {
+    enabled: boolean;
+    width: number;
+    height: number;
+    rx: number;
+    offsetY: number;
+    gradient: GradientStop[];
+    shadow: PillShadowStyle;
+}
+interface DropShadowStyle {
+    dx: number;
+    dy: number;
+    blur: number;
+    color: string;
+    opacity: number;
+}
+interface FoldBarStyleConfig {
+    stripePattern?: Partial<StripePatternStyle>;
+    /** The active stops paint the default-active bar; all other bars use normal. */
+    barGradient?: {
+        active?: GradientStop[];
+        normal?: GradientStop[];
+    };
+    foldGradient?: GradientStop[];
+    creaseGradient?: GradientStop[];
+    washTop?: number;
+    washGradient?: GradientStop[];
+    /** Renders the active-column wash backdrop. Default true. */
+    washEnabled?: boolean;
+    pill?: Partial<Omit<PillStyle, 'shadow'>> & {
+        shadow?: Partial<PillShadowStyle>;
+    };
+    shadow?: Partial<DropShadowStyle>;
+    /** `enabled: false` removes the dissolving baseline mask. Default true. */
+    fadeMask?: Partial<{
+        start: number;
+        end: number;
+        enabled: boolean;
+    }>;
+    labelY?: number;
+    numberY?: number;
+    /** Nudge of the label and value away from the bar's horizontal center. */
+    labelXOffset?: number;
+}
+/** Preset name ('light' | 'dark' | registered), an inline pack, or a legacy tokens partial. */
+type ThemeRef = string | ThemePack | DeepPartialTokens;
+interface FoldBarChartConfig extends BaseConfig {
+    data: FoldBarDatum[];
+    xField?: string;
+    yField?: string;
+    /** Formats bar header values and feeds the default tooltip formatter. */
+    valueFormat?: (value: number) => string;
+    ariaLabel?: string;
+    padding?: Partial<Padding>;
+    stair?: Partial<{
+        bottomOffset: number;
+        topOffset: number;
+    }>;
+    scale?: FoldBarScaleConfig;
+    fold?: FoldBarFoldConfig;
+    axis?: FoldBarAxisConfig;
+    xAxis?: FoldBarXAxisConfig;
+    tooltip?: FoldBarTooltipConfig;
+    state?: FoldBarStateConfig;
+    title?: FoldBarTitleConfig;
+    style?: FoldBarStyleConfig;
+    /** Preset name, inline theme pack, or legacy typography tokens; deep-merged over the defaults. */
+    theme?: ThemeRef;
+}
+
+/**
+ * Fold-paper funnel bar chart: gradient columns joined by folded flaps,
+ * striped idle state, wash highlight on the active column.
+ */
+declare class FoldBarChart extends ChartBase<FoldBarChartConfig, ChartEventMap<FoldBarDatum>> {
+    private uid;
+    private model;
+    private rendered;
+    private interaction;
+    constructor(container: ContainerLike, config: FoldBarChartConfig);
+    /** Currently active (highlighted) column index. */
+    get activeIndex(): number;
+    /** Programmatically highlight a column. */
+    setActive(index: number): void;
+    protected renderChart(): void;
+    protected onDestroy(): void;
+}
+
+interface FoldBarOptions {
+    width: number;
+    height: number;
+    xField: string;
+    yField: string;
+    valueFormat: (value: number) => string;
+    ariaLabel: string;
+    padding: Padding;
+    stair: {
+        bottomOffset: number;
+        topOffset: number;
+    };
+    scale: {
+        exponent: number;
+    };
+    fold: {
+        run: number;
+        creaseColor: string;
+        creaseWidth: number;
+    };
+    axis: {
+        ticks: number[];
+        tickFormat: (value: number) => string;
+        /** Axis domain maximum; bars normalize against it so ticks map truthfully. */
+        domainMax: number;
+    };
+    xAxis: {
+        labelFormat: XAxisLabelFormatter;
+        bottomLabels?: XAxisBottomFormatter;
+        title: {
+            text: string;
+            x?: number;
+            y?: number;
+        };
+        showLine: boolean;
+        showTick: boolean;
+        showGrid: boolean;
+    };
+    tooltip: {
+        enabled: boolean;
+        formatter: TooltipFormatter;
+        height: number;
+        radius: number;
+        paddingX: number;
+        anchorRatio: number;
+        offsetY: number;
+        minY: number;
+        fixedWidth?: number;
+    };
+    state: {
+        defaultActive: number;
+    };
+    title: {
+        text: string;
+        x: number;
+        y: number;
+    };
+    style: ResolvedFoldBarStyle;
+    tokens: FoldBarThemeTokens;
+}
+/** Default header value formatter, matching the prototype's `65.2k` labels. */
+declare const defaultValueFormat: (value: number) => string;
+/** Neutral default tooltip: category label plus formatted value. */
+declare function defaultTooltipFormatter(datum: FoldBarDatum): TooltipPart[];
+interface NiceScale {
+    /** Nice axis maximum; bars normalize against it. */
+    axisMax: number;
+    step: number;
+    /** Nice tick values in descending order (topmost first), zero excluded. */
+    ticks: number[];
+}
+/** d3-style nice tick generation: step = multiplier × 10^power, keeping at most targetCount top ticks. */
+declare function niceScale(maxValue: number, targetCount?: number): NiceScale;
+interface FoldBarModel {
+    data: FoldBarDatum[];
+    labels: string[];
+    values: number[];
+    layout: FoldBarLayout;
+    bars: BarGeometry[];
+    flaps: (FlapGeometry | null)[];
+    /** Fade band that dissolves bar bottoms; derived from plot.bottom unless user-overridden. */
+    fade: {
+        start: number;
+        end: number;
+    };
+    options: FoldBarOptions;
+}
+
+interface ScaleOptions {
+    domain: [number, number];
+    range: [number, number];
+}
+/** Maps values from domain to range linearly. A degenerate domain maps everything to range[0]. */
+declare function createLinearScale({ domain: [d0, d1], range: [r0, r1], }: ScaleOptions): (value: number) => number;
+
+interface PowerScaleOptions extends ScaleOptions {
+    /** Power applied to the normalized value. 1 behaves exactly like a linear scale. */
+    exponent?: number;
+}
+/**
+ * Maps values from domain to range through t^exponent, where t is the normalized
+ * value clamped to [0, +inf). exponent < 1 emphasizes large values, > 1 compresses them.
+ */
+declare function createPowerScale({ domain: [d0, d1], range: [r0, r1], exponent, }: PowerScaleOptions): (value: number) => number;
+
+interface BandScale {
+    /** Full width of one band, including padding. */
+    step: number;
+    /** Usable width inside a band. */
+    bandwidth: number;
+    /** Leading edge of the band at index. */
+    position: (index: number) => number;
+    /** Center of the band at index. */
+    center: (index: number) => number;
+}
+/** Splits range into count equal bands. paddingRatio is the fraction of each step left empty. */
+declare function createBandScale(count: number, range: [number, number], paddingRatio?: number): BandScale;
+
+declare const VERSION = "0.1.0";
+
+export { type BandScale, type BarGeometry, type BaseConfig, ChartBase, type ChartEventMap, type ColumnEventPayload, type ContainerLike, type DeepPartialTokens, type DownloadOptions, type ExportOptions, type FlapGeometry, type FoldBarAxisConfig, FoldBarChart, type FoldBarChartConfig, type FoldBarDatum, type FoldBarFoldConfig, type FoldBarLayout, type FoldBarModel, type FoldBarOptions, type FoldBarScaleConfig, type FoldBarStateConfig, type FoldBarStyleConfig, type FoldBarThemeTokens, type FoldBarTitleConfig, type FoldBarTooltipConfig, type FoldBarXAxisConfig, type FoldBarXAxisTitleConfig, type NiceScale, type Padding, type PillGeometry, type PlotRect, type PowerScaleOptions, type RectGeometry, type ResolvedFoldBarStyle, type ScaleOptions, type ThemeFormats, type ThemePack, type ThemeRef, type TooltipFormatter, type TooltipPart, type TooltipTone, VERSION, type XAxisBottomFormatter, type XAxisLabelFormatter, createBandScale, createLinearScale, createPowerScale, defaultTooltipFormatter, defaultValueFormat, getTheme, isThemePack, niceScale, registerTheme };