@lamatemaga/sterling 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,505 @@
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import { ScaleLinear, ScaleTime } from 'd3-scale';
+
+/** Languages bundled with Sterling's default editorial copy. */
+type SterlingLocale = "es" | "en";
+
+type SterlingLegendShape = "circle" | "square" | "triangle" | "line";
+interface SterlingLegendItem {
+    label: string;
+    colorIndex?: number;
+    color?: string;
+    textColor?: string;
+    shape?: SterlingLegendShape;
+}
+declare function SterlingInlineLegend({ items, locale, }: {
+    items: SterlingLegendItem[];
+    locale: SterlingLocale;
+}): react.JSX.Element;
+
+interface BarDatum {
+    label: string;
+    value: number;
+    colorIndex?: number;
+}
+declare function SterlingBarChart({ data, ariaLabel, unit, xLabel, }: {
+    data: BarDatum[];
+    ariaLabel: string;
+    unit?: string;
+    xLabel?: string;
+}): react.JSX.Element;
+interface ScatterDatum {
+    x: number;
+    y: number;
+    group: string;
+    label?: string;
+}
+declare function SterlingScatterPlot({ data, ariaLabel, xLabel, yLabel, showLegend, zeroX, zeroY, }: {
+    data: ScatterDatum[];
+    ariaLabel: string;
+    xLabel: string;
+    yLabel: string;
+    showLegend?: boolean;
+    zeroX?: boolean;
+    zeroY?: boolean;
+}): react.JSX.Element;
+interface LineSeries {
+    label: string;
+    values: number[];
+}
+declare function SterlingLineChart({ labels, series, ariaLabel, yLabel, xLabel, times, markers, showLegend, }: {
+    labels: string[];
+    series: LineSeries[];
+    ariaLabel: string;
+    yLabel: string;
+    xLabel?: string;
+    /** Epoch-ms per point (parallel to labels); enables the adaptive time axis. */
+    times?: number[];
+    /** Draw a dot at every point. Off by default for dense time series. */
+    markers?: boolean;
+    showLegend?: boolean;
+}): react.JSX.Element;
+declare function SterlingHeatmap({ values, rowLabels, columnLabels, ariaLabel, domain, legendTitle, showValues, }: {
+    values: number[][];
+    rowLabels: string[];
+    columnLabels: string[];
+    ariaLabel: string;
+    /** Symmetric color domain [-domain, +domain]; defaults to the data's max |value|. */
+    domain?: number;
+    legendTitle?: string;
+    showValues?: boolean;
+}): react.JSX.Element;
+declare function SterlingSequentialSurface({ values: suppliedValues, ariaLabel, lowLabel, highLabel, }: {
+    values?: number[][];
+    ariaLabel: string;
+    lowLabel?: string;
+    highLabel?: string;
+}): react.JSX.Element;
+declare function SterlingCorrelogram({ values, labels, ariaLabel, }: {
+    values: number[][];
+    labels: string[];
+    ariaLabel: string;
+}): react.JSX.Element;
+declare function SterlingHistogram({ values, bins, ariaLabel, xLabel, yLabel, }: {
+    values: number[];
+    bins?: number;
+    ariaLabel: string;
+    xLabel: string;
+    yLabel?: string;
+}): react.JSX.Element;
+interface BoxPlotGroup {
+    label: string;
+    values: number[];
+}
+declare function SterlingBoxPlot({ groups, ariaLabel, yLabel }: {
+    groups: BoxPlotGroup[];
+    ariaLabel: string;
+    yLabel: string;
+}): react.JSX.Element;
+interface DumbbellDatum {
+    label: string;
+    left: number;
+    right: number;
+}
+declare function SterlingDumbbellChart({ data, ariaLabel, leftLabel, rightLabel, xLabel, }: {
+    data: DumbbellDatum[];
+    ariaLabel: string;
+    leftLabel: string;
+    rightLabel: string;
+    xLabel?: string;
+}): react.JSX.Element;
+declare function kernelDensity(values: number[], steps?: number, domain?: [number, number]): {
+    value: number;
+    density: number;
+}[];
+declare function SterlingDensityChart({ values, ariaLabel, xLabel, yLabel }: {
+    values: number[];
+    ariaLabel: string;
+    xLabel: string;
+    yLabel?: string;
+}): react.JSX.Element;
+interface ViolinGroup {
+    label: string;
+    values: number[];
+}
+declare function SterlingViolinPlot({ groups, ariaLabel, yLabel }: {
+    groups: ViolinGroup[];
+    ariaLabel: string;
+    yLabel: string;
+}): react.JSX.Element;
+interface DonutDatum {
+    label: string;
+    value: number;
+}
+declare function SterlingDonutChart({ data, ariaLabel, centerLabel, centerValue }: {
+    data: DonutDatum[];
+    ariaLabel: string;
+    centerLabel: string;
+    centerValue?: string;
+}): react.JSX.Element;
+declare function SterlingLollipopChart({ data, ariaLabel, unit, xLabel }: {
+    data: BarDatum[];
+    ariaLabel: string;
+    unit?: string;
+    xLabel?: string;
+}): react.JSX.Element;
+declare function SterlingPieChart({ data, ariaLabel }: {
+    data: DonutDatum[];
+    ariaLabel: string;
+}): react.JSX.Element;
+declare function SterlingChordChart({ rowLabels, columnLabels, values, ariaLabel, }: {
+    rowLabels: string[];
+    columnLabels: string[];
+    values: number[][];
+    ariaLabel: string;
+}): react.JSX.Element;
+interface SankeyLinkDatum {
+    source: string;
+    target: string;
+    value: number;
+}
+declare function SterlingSankeyChart({ links, ariaLabel }: {
+    links: SankeyLinkDatum[];
+    ariaLabel: string;
+}): react.JSX.Element;
+
+declare function SterlingVerticalBarChart({ data, ariaLabel, yLabel, xLabel }: {
+    data: Array<[string, number]>;
+    ariaLabel: string;
+    yLabel?: string;
+    xLabel?: string;
+}): react.JSX.Element;
+declare function SterlingCandlestickChart({ rows, ariaLabel, yLabel, xLabel }: {
+    rows: Array<[string, number, number, number, number]>;
+    ariaLabel: string;
+    yLabel?: string;
+    xLabel?: string;
+}): react.JSX.Element;
+declare function SterlingRadarChart({ labels, series, domain, ariaLabel, unit }: {
+    labels: string[];
+    series: Array<[string, ...number[]]>;
+    domain: number[];
+    ariaLabel: string;
+    unit?: string;
+}): react.JSX.Element;
+declare function SterlingRidgelineChart({ groups, ariaLabel, xLabel, unit }: {
+    groups: Array<{
+        label: string;
+        values: number[];
+    }>;
+    ariaLabel: string;
+    xLabel?: string;
+    unit?: string;
+}): react.JSX.Element;
+declare function SterlingDensity2DChart({ points, regionLabels, ariaLabel, xLabel, yLabel }: {
+    points: Array<[number, number, number]>;
+    regionLabels: string[];
+    ariaLabel: string;
+    xLabel?: string;
+    yLabel?: string;
+}): react.JSX.Element;
+declare function SterlingTreemapChart({ rows, ariaLabel }: {
+    rows: Array<[string, string, string, number]>;
+    ariaLabel: string;
+}): react.JSX.Element;
+declare function SterlingNetworkChart({ nodes, edges, ariaLabel }: {
+    nodes: Array<[string, number, number, number, number]>;
+    edges: Array<[number, number]>;
+    ariaLabel: string;
+}): react.JSX.Element;
+declare function SterlingDendrogramChart({ labels, merge, height, order, groups, ariaLabel, yLabel, cutLabel }: {
+    labels: string[];
+    merge: Array<[number, number]>;
+    height: number[];
+    order: number[];
+    groups: number[][];
+    ariaLabel: string;
+    yLabel?: string;
+    cutLabel?: string;
+}): react.JSX.Element;
+declare function SterlingVolcanoChart({ hex, labels, ariaLabel, xLabel, yLabel }: {
+    hex: string;
+    labels: Array<[string, number, number]>;
+    ariaLabel: string;
+    xLabel?: string;
+    yLabel?: string;
+}): react.JSX.Element;
+declare function SterlingManhattanChart({ hex, labels, chromosomeCenters, ariaLabel, xLabel, yLabel }: {
+    hex: string;
+    labels: Array<[string, number, number, number]>;
+    chromosomeCenters: number[];
+    ariaLabel: string;
+    xLabel?: string;
+    yLabel?: string;
+}): react.JSX.Element;
+/**
+ * Clustered correlation heatmap of NCI60 expression profiles. Rows and columns
+ * are reordered by hierarchical clustering so shared signatures surface as
+ * diagonal blocks; dendrograms, type annotations, and region frames match the
+ * canonical v1.5 figure. Violet = positive correlation, teal = negative.
+ */
+declare function SterlingExpressionChart({ hex, groups, types, ariaLabel }: {
+    hex: string;
+    groups: number[];
+    types: string[];
+    ariaLabel: string;
+}): react.JSX.Element;
+declare function SterlingGeoMapChart({ atlas, rows, ariaLabel }: {
+    atlas: unknown;
+    rows: Array<{
+        state: string;
+        id: number;
+        engineers: number;
+    }>;
+    ariaLabel: string;
+}): react.JSX.Element;
+
+type SterlingMode = "light" | "dark" | "print";
+interface SterlingSurfacePalette {
+    paper?: string;
+    plot?: string;
+    plotAlt?: string;
+    text?: string;
+    muted?: string;
+    grid?: string;
+    edge?: string;
+    period?: string;
+}
+/**
+ * Optional theme overrides for the Sterling grammar. Omitted values keep the
+ * Sterling defaults. Values may be CSS variables, which lets a consuming site
+ * provide its own light and dark definitions without changing the components.
+ */
+interface SterlingPalette {
+    surface?: SterlingSurfacePalette;
+    categorical?: readonly string[];
+    legend?: readonly string[];
+    sequential?: readonly string[];
+    divergent?: readonly string[];
+    heat?: readonly string[];
+    ramps?: readonly (readonly string[])[];
+}
+type SterlingCssVariables = CSSProperties & Record<`--sterling-${string}`, string>;
+/** Identity helper that preserves literal color values in TypeScript. */
+declare function defineSterlingPalette<const T extends SterlingPalette>(palette: T): T;
+/** Convert a palette override into the CSS variables consumed by every chart. */
+declare function sterlingPaletteStyle(palette?: SterlingPalette): SterlingCssVariables;
+declare const sterlingCategorical: {
+    readonly light: readonly ["#9A79E7", "#25A08D", "#D45AC7", "#E4A43A", "#5A83D7", "#E87864", "#96AB51", "#536B78"];
+    readonly dark: readonly ["#B69AF2", "#5EC9AE", "#E88BDD", "#F2C46D", "#86A8E8", "#F29A88", "#B7C974", "#B7C8D1"];
+    readonly print: readonly ["#8E68D8", "#218C7C", "#C653BC", "#D39A32", "#4F73C6", "#DC6A55", "#879347", "#607986"];
+};
+declare const sterlingColorNames: readonly ["Violet", "Teal", "Orchid", "Amber", "Blue", "Coral", "Moss", "Payne"];
+/** CSS variables let one SVG respond to the site's light and dark themes. */
+declare const sterlingChartColors: string[];
+/** Hue-matched text colors keep inline legends readable in both themes. */
+declare const sterlingLegendColors: string[];
+declare const sterlingDivergentColors: string[];
+/** A single-hue ramp for ordered magnitudes such as histogram frequency. */
+declare const sterlingSequentialColors: string[];
+/** Multi-hue ordered ramp from the v1.5 topography field test. */
+declare const sterlingHeatColors: string[];
+/** Stops available in every per-family sequential ramp (ramp stops 200-800). */
+declare const sterlingRampStops = 7;
+/**
+ * One sequential ramp per categorical family, mirroring `lm_ramps` in
+ * `theme_lamatemaga.R`. `family` is the categorical index (0 = Violet, 1 = Teal,
+ * ...) and `stop` runs 1..7 from faintest to strongest. The token order mirrors
+ * per theme, so a higher stop always reads as the higher-contrast tone.
+ *
+ * The band runs 200-800, not the full 100-950. The 900-950 end is nearly flat in
+ * luminance (Δ 0.014) so those tones stop reading as separate steps and turn
+ * light mode heavy; the 100 end is a near-white tint that all but disappears
+ * against the chart surface (contrast 1.11).
+ */
+declare function sterlingRamp(family: number, stop: number): string;
+
+/**
+ * Shared cartesian foundation for every Sterling chart.
+ *
+ * One geometry, one axis grammar: gridlines, tick marks, tick labels, and axis
+ * titles are drawn the same way everywhere so the whole catalog reads as a
+ * single visualization package. Colors come from the theme tokens only.
+ */
+declare const axisText = "var(--sterling-text)";
+declare const axisMuted = "var(--sterling-muted)";
+declare const axisGrid = "var(--sterling-grid)";
+declare const axisLine = "var(--sterling-edge)";
+declare const TICK = 5;
+declare const TICK_LABEL = 11;
+declare const AXIS_TITLE = 12;
+interface Margin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Room on the left/bottom for tick labels plus an axis title. */
+declare const defaultMargin: Margin;
+interface Frame {
+    width: number;
+    height: number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+}
+declare function frame(width: number, height: number, margin?: Margin): Frame;
+/** Linear scale with a nice domain; `zero` anchors magnitude charts at 0. */
+declare function linearScale(values: number[], range: [number, number], { zero, padFraction }?: {
+    zero?: boolean;
+    padFraction?: number;
+}): ScaleLinear<number, number>;
+declare function timeScale(domain: [number, number], range: [number, number]): ScaleTime<number, number>;
+/** Horizontal gridlines aligned to the left-axis ticks. */
+declare function Gridlines({ scale, x0, x1, count, }: {
+    scale: ScaleLinear<number, number>;
+    x0: number;
+    x1: number;
+    count?: number;
+}): react.JSX.Element;
+declare function AxisLeft({ scale, x, gridX1, count, title, format, }: {
+    scale: ScaleLinear<number, number>;
+    x: number;
+    gridX1?: number;
+    count?: number;
+    title?: string;
+    format?: (value: number) => string;
+}): react.JSX.Element;
+declare function AxisBottom({ scale, y, count, title, format, titleGap, }: {
+    scale: ScaleLinear<number, number>;
+    y: number;
+    count?: number;
+    title?: string;
+    format?: (value: number) => string;
+    titleGap?: number;
+}): react.JSX.Element;
+/**
+ * Time axis whose interval adapts to the span and the available width: d3
+ * chooses days, weeks, months, or years and formats each tick to match. One
+ * tick roughly every `targetPx` pixels keeps labels from ever colliding.
+ */
+declare function TimeAxisBottom({ scale, y, title, targetPx, titleGap, }: {
+    scale: ScaleTime<number, number>;
+    y: number;
+    title?: string;
+    targetPx?: number;
+    titleGap?: number;
+}): react.JSX.Element;
+/** Evenly spaced band centers for categorical axes. */
+declare function bandCenters(count: number, x0: number, x1: number): {
+    centers: number[];
+    step: number;
+};
+/**
+ * Signed diverging color with the brand orientation: violet encodes positive,
+ * teal encodes negative. The palette token order is violet -> ... -> teal, so a
+ * positive value maps to the low (violet) end. Palette values are never mutated.
+ */
+declare function divergentSignedColor(value: number, maxAbs: number): string;
+/** Legend ramp for signed diverging scales, left (negative/teal) to right (positive/violet). */
+declare const divergentSignedRamp: readonly string[];
+/** Tukey five-number summary with 1.5*IQR fences and the outliers beyond them. */
+declare function tukeySummary(values: number[]): {
+    q1: number;
+    median: number;
+    q3: number;
+    iqr: number;
+    whiskerLow: number;
+    whiskerHigh: number;
+    outliers: number[];
+    min: number;
+    max: number;
+};
+
+/**
+ * The table that produced a figure, after any transformations used by the
+ * wrapper. This deliberately does not claim to be the original source file.
+ */
+interface SterlingDataExport {
+    rows: readonly Record<string, unknown>[];
+    /** Optional stem for the generated CSV. The title is used when omitted. */
+    fileName?: string;
+}
+/** Turn the exact rows supplied to a Sterling figure into a portable UTF-8 CSV. */
+declare function sterlingRowsToCsv(rows: SterlingDataExport["rows"]): string;
+/**
+ * A graceful fallback for wrappers that have not supplied `dataExport` yet.
+ * It only inspects the already-processed props passed to common primitives;
+ * explicit `dataExport` is preferable when field names need editorial care.
+ */
+declare function inferSterlingDataExport(props: Record<string, unknown>): SterlingDataExport | undefined;
+
+/** Writing conventions around a figure, kept separate from every chart primitive. */
+interface SterlingEditorial {
+    /** Use `false` to remove the QED-like title mark, or supply another mark. */
+    titleMark?: ReactNode | false;
+    /** Optional destination for an interactive title mark. */
+    titleMarkHref?: string;
+    /** Accessible label for an interactive title mark. */
+    titleMarkLabel?: string;
+    /** Use `false` to omit the credit from the caption. */
+    signature?: ReactNode | false;
+    /** Replaces the localized Source/Fuente label. */
+    sourceLabel?: ReactNode;
+}
+interface SterlingCreditOptions {
+    author?: ReactNode;
+    productName?: ReactNode;
+    /** Link the product name to its public documentation. Defaults to true. */
+    linkToSterling?: boolean;
+    sterlingUrl?: string;
+}
+/** A portable credit, e.g. “Made by Ada with Sterling ✦”. */
+declare function sterlingCredit({ author, productName, linkToSterling, sterlingUrl, }: SterlingCreditOptions, locale?: SterlingLocale): ReactNode;
+
+type TailwindStep = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950;
+type TailwindScale = Partial<Record<TailwindStep, string>>;
+interface TailwindSterlingPaletteOptions {
+    /** Eight or fewer Tailwind color scales. Their 500 stops become categories. */
+    categorical: readonly TailwindScale[];
+    /** Use your own surfaces so text and grid contrast remain intentional. */
+    surface: SterlingSurfacePalette;
+    divergent?: TailwindScale;
+    heat?: TailwindScale;
+}
+/**
+ * Convert Tailwind-like 100–950 scales into Sterling's palette contract
+ * without making Tailwind a runtime dependency.
+ */
+declare function createTailwindSterlingPalette({ categorical, surface, divergent, heat, }: TailwindSterlingPaletteOptions): SterlingPalette;
+
+/**
+ * Shared optical weights for Sterling primitives. Values are intentionally
+ * modest: data marks lead, while axes and construction lines recede.
+ */
+declare const sterlingVisualStyle: {
+    readonly stroke: {
+        readonly grid: 1;
+        readonly detail: 1.5;
+        readonly candle: 1.75;
+        readonly mark: 2;
+        readonly series: 2.25;
+        readonly emphasis: 2.5;
+        readonly interval: 7;
+        readonly halo: 3;
+        readonly ring: 44;
+        readonly flowMinimum: 1;
+    };
+    readonly opacity: {
+        readonly ghost: 0.04;
+        readonly contour: 0.08;
+        readonly surface: 0.1;
+        readonly area: 0.24;
+        readonly ridge: 0.34;
+        readonly interval: 0.28;
+        readonly relationship: 0.42;
+        readonly secondaryMark: 0.66;
+        readonly guide: 0.7;
+        readonly signal: 0.84;
+        readonly mutedMark: 0.34;
+    };
+};
+
+export { AXIS_TITLE, AxisBottom, AxisLeft, type BarDatum, type BoxPlotGroup, type DonutDatum, type DumbbellDatum, type Frame, Gridlines, type LineSeries, type Margin, type SankeyLinkDatum, type ScatterDatum, SterlingBarChart, SterlingBoxPlot, SterlingCandlestickChart, SterlingChordChart, SterlingCorrelogram, type SterlingCreditOptions, type SterlingDataExport, SterlingDendrogramChart, SterlingDensity2DChart, SterlingDensityChart, SterlingDonutChart, SterlingDumbbellChart, type SterlingEditorial, SterlingExpressionChart, SterlingGeoMapChart, SterlingHeatmap, SterlingHistogram, SterlingInlineLegend, type SterlingLegendItem, type SterlingLegendShape, SterlingLineChart, type SterlingLocale, SterlingLollipopChart, SterlingManhattanChart, type SterlingMode, SterlingNetworkChart, type SterlingPalette, SterlingPieChart, SterlingRadarChart, SterlingRidgelineChart, SterlingSankeyChart, SterlingScatterPlot, SterlingSequentialSurface, type SterlingSurfacePalette, SterlingTreemapChart, SterlingVerticalBarChart, SterlingViolinPlot, SterlingVolcanoChart, TICK, TICK_LABEL, type TailwindScale, type TailwindStep, type TailwindSterlingPaletteOptions, TimeAxisBottom, type ViolinGroup, axisGrid, axisLine, axisMuted, axisText, bandCenters, createTailwindSterlingPalette, defaultMargin, defineSterlingPalette, divergentSignedColor, divergentSignedRamp, frame, inferSterlingDataExport, kernelDensity, linearScale, sterlingCategorical, sterlingChartColors, sterlingColorNames, sterlingCredit, sterlingDivergentColors, sterlingHeatColors, sterlingLegendColors, sterlingPaletteStyle, sterlingRamp, sterlingRampStops, sterlingRowsToCsv, sterlingSequentialColors, sterlingVisualStyle, timeScale, tukeySummary };