graphein 0.9.1 → 0.11.0

package/dist/index.d.ts

@@ -175,6 +175,7 @@ declare function interpolateOklab(a: RGBA, b: RGBA): Interpolator;
 
 /** Get a categorical palette by name (defaults to the 'graphein' palette). */
 declare function categorical(name?: string): string[];
+declare const categoricalSchemes: string[];
 /**
  * Build a continuous ramp from ordered color stops, interpolating each segment
  * in OKLab. Endpoints (t=0,1) return the first/last stop exactly.
@@ -1131,6 +1132,10 @@ interface LegendConfig {
     show?: boolean;
     position?: LegendPosition;
     title?: string;
+    /** Allow clicking legend items to toggle/isolate series; publishes a selection. */
+    interactive?: boolean;
+    /** Selection param to publish legend visibility to; defaults to the series field name. */
+    param?: string;
 }
 interface TooltipConfig {
     show?: boolean;
@@ -1181,6 +1186,8 @@ interface BaseSpec {
     transform?: Transform[];
     /** Theme name ('light' | 'dark') or a partial override object. */
     theme?: ThemeInput;
+    /** Named categorical palette ('graphein'|'colorblind'|'bright'|'muted') or an explicit array of series colors. */
+    palette?: string | string[];
     dimensions?: Dimensions;
     title?: string | TitleConfig;
     /**
@@ -1364,6 +1371,12 @@ interface BarSpec extends BaseSpec {
         x: FieldDef;
         y: FieldDef;
     };
+    /**
+     * Bar direction. `'vertical'` (default) draws columns growing up from the
+     * x-axis; `'horizontal'` draws bars growing rightward from the y-axis, with the
+     * `x` categories listed down the left — ideal when category names are long.
+     * The `encoding` is unchanged either way (`x` = category, `y` = value).
+     */
     orientation?: 'vertical' | 'horizontal';
     /** Stack series (default false). */
     stack?: boolean;
@@ -2361,6 +2374,23 @@ interface RegressionFit {
  */
 declare function linearRegression(xs: readonly number[], ys: readonly number[]): RegressionFit | null;
 
+interface ColumnProfile {
+    field: string;
+    type: 'quantitative' | 'temporal' | 'nominal' | 'ordinal';
+    cardinality: number;
+}
+interface RecommendedChart {
+    spec: ChartSpec;
+    score: number;
+    rationale: string;
+}
+interface RecommendOptions {
+    intent?: 'trend' | 'comparison' | 'distribution' | 'relationship' | 'composition';
+    maxResults?: number;
+}
+declare function profileColumns(data: Datum[]): ColumnProfile[];
+declare function recommendChart(data: Datum[], opts?: RecommendOptions): RecommendedChart[];
+
 /** Environment helpers — safe in both browser and Node (SSR/test). */
 declare const isBrowser: boolean;
 /** Current device pixel ratio (defaults to 1 outside the browser). */
@@ -2981,6 +3011,17 @@ interface Hover {
      */
     draw?(ctx: CanvasRenderingContext2D): void;
 }
+/** A click target for an interactive legend item. */
+interface LegendHitRegion {
+    /** Swatch rectangle in CSS px. */
+    rect: Rect;
+    /** Stable string key for the series. */
+    key: string;
+    /** Raw series value used when publishing a selection. */
+    value: unknown;
+    /** Human-readable legend label. */
+    label: string;
+}
 /** A chart's hit-testable description for the current frame. */
 interface InteractionModel {
     /** Hit region in CSS px. Moves outside it clear the hover. */
@@ -2993,6 +3034,8 @@ interface InteractionModel {
      * a `pick` are hover-only.
      */
     pick?(px: number, py: number): SelectionValue | null;
+    /** Optional interactive legend click targets for this frame. */
+    legendHits?: LegendHitRegion[];
 }
 /**
  * Resolved emphasis for the current frame: which rows are "in" the active
@@ -3063,6 +3106,23 @@ interface CartesianModel {
     series: ResolvedSeries[];
     seriesField?: string;
     stacked: boolean;
+    /**
+     * Bar orientation. Only `bar` ever sets `'horizontal'`; every other chart is
+     * `'vertical'`. In horizontal mode the `x` (category/band) axis runs vertically
+     * and the `y` (value) axis runs horizontally — so `x.pixel`/`x.bandwidth` are
+     * vertical extents and `y.pixel`/`y.baseline` are horizontal ones. Consumers map
+     * an (category-axis, value-axis) pixel pair to screen coords via {@link project}.
+     */
+    orientation: 'vertical' | 'horizontal';
+    /**
+     * Map a (category-axis pixel, value-axis pixel) pair to screen `{x, y}`,
+     * accounting for orientation. Vertical is the identity; horizontal swaps the
+     * pair (value → screen x, category → screen y).
+     */
+    project(catPixel: number, valPixel: number): {
+        x: number;
+        y: number;
+    };
     xTicks: Tick[];
     yTicks: Tick[];
     colorOf(key: string): string;
@@ -3074,6 +3134,13 @@ interface CartesianModel {
      * `highlight` param + the shared store; `buildCartesianModel` leaves it null.
      */
     emphasis?: Emphasis | null;
+    /** Interactive legend swatch hit targets; only present when legend.interactive is true. */
+    legendHits?: LegendHitRegion[];
+    /** Draw-side mark counts for render diagnostics; semantic markCount stays data-based. */
+    markStats?: {
+        drawn: number;
+        original: number;
+    };
 }
 declare function resolveCurve(curve?: CurveType): Curve;
 interface BuildOptions {
@@ -3253,7 +3320,9 @@ declare const customRenderers: Partial<Record<ChartType, CustomRenderer>>;
 /** How the controller publishes a click/tap selection from the current model. */
 interface ControllerSelect {
     /** Called with the picked value (or `null` when empty space is clicked). */
-    onPick(value: SelectionValue | null): void;
+    onPick?(value: SelectionValue | null): void;
+    /** Called when an interactive legend swatch is clicked. */
+    onLegendToggle?(hit: LegendHitRegion, event: MouseEvent): void;
 }
 declare class InteractionController {
     private readonly surface;
@@ -3498,6 +3567,10 @@ interface RenderDiagnostic {
     axis?: 'x' | 'y';
     /** Structured extras (counts, ratios) for programmatic consumers. */
     details?: Record<string, unknown>;
+    /** Safe JSON Patch operations an agent may apply to address this finding. */
+    fix?: JsonPatchOp[];
+    /** One-line advisory when there is no unambiguous safe patch. */
+    hint?: string;
 }
 /** A post-render, vision-free description of what was drawn. */
 interface RenderReport {
@@ -3538,6 +3611,11 @@ interface ReportInput {
  * resolved model + theme, never the canvas bitmap.
  */
 declare function buildRenderReport(input: ReportInput): RenderReport;
+/** Apply safe render-report JSON Patch fixes to a clone of the spec. Pure: no rendering. */
+declare function repairReport(spec: ChartSpec, report: RenderReport): {
+    spec: ChartSpec;
+    applied: JsonPatchOp[];
+};
 
 /**
  * Faceting / small multiples.
@@ -3803,4 +3881,4 @@ declare function renderDashboard(target: HTMLElement | string, spec: DashboardSp
  */
 declare const VERSION = "0.1.0";
 
-export { type AggOp, type AggregateOp, type AggregateTransform, type AnimateOptions, type AnimationConfig, type AnimationHandle, type Annotation, type AnySpec, type ArcOptions, type AreaOptions, type AreaPoint, type AreaSpec, type AxesConfig, type AxisConfig, type AxisInput, type BackingSize, type BandScale, type BandScaleOptions, type BarSpec, type BaseSlicerSpec, type BaseSpec, type BinLayout, type BinTransform, type BoxSpec, type BuildOptions, type BulletSpec, CARTESIAN_TYPES, CHART_TYPES, type CalculateTransform, type CalendarHeatmapSpec, CanvasLayer, type CanvasPillStyle, type CanvasTextCmd, type CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type CategoryInsights, type ChartInsights, type ChartInstance, type ChartSpec, type ChartSummary, type ChartType, type ChoroplethSpec, type ColorScale, type ComboAxisModel, type ComboLayer, type ComboLayerModel, type ComboMark, type ComboModel, type ComboSide, type ComboSpec, type Comparable, type ConditionalFormat, type ContinuousScale, type ControllerSelect, type Curve, type CurveType, type CustomRenderer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, type DashboardCell, type DashboardInstance, type DashboardLayout, type DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DateRangeSlicerSpec, type Datum, type DecimateOptions, type Dimensions, type DropdownSlicerSpec, type DumbbellSpec, type EasingFunction, type Emphasis, type Encoding, type EntranceContext, ExpressionError, type Extent, FACETABLE_TYPES, FUNCTION_NAMES, type FacetConfig, type FacetLayout, type FacetPanel, type FieldDef, type FieldType, type FieldValue, type FillStyle, type FilterClause, type FilterPredicate, type FilterTransform, type FoldTransform, type Frame, type FrameInput, type FunnelSpec, type GaugeSpec, type GeoFeature, type GeoFeatureCollection, type GeoGeometry, type GeoMultiPolygon, type GeoPolygon, type GeoPosition, type GroupedMap, type HachureSegment, type HeadlessTarget, type HeatmapSpec, type HighlightConfig, type HistogramBin, type HistogramBinDatum, type HistogramModel, type HistogramSpec, type Hover, type IconRule, type Insets, type InsightFamily, type InsightOptions, InteractionController, type InteractionLink, type InteractionModel, type Interpolator, type JsonPatchOp, type KpiSpec, type LegendConfig, type LegendItem, type LegendPosition, type LegendSymbol, type LineOptions, type LineSpec, type LinearScaleOptions, type LintFinding, type ListSlicerSpec, type LiteralPredicate, type LogScaleOptions, type MapProjection, type MarkOptions, type MatrixSpec, type MatrixValueDef, type NumberFormatSpec, type OKLCH, type OKLab, type OverlayTextOpts, type PathSink, type PieLabels, type PieSpec, type PivotCell, type PivotFlatRow, type PivotHeaderNode, type PivotOptions, type PivotResult, type PivotValueDef, type Point, type PointRef, type PointScale, type PointScaleOptions, type PointSelection, type PositionedLegendItem, type RGBA, type RangeSelection, type RangeSlicerSpec, type Rect, type RegressionFit, type RenderContext, type RenderDashboardOptions, type RenderDiagnostic, type RenderOptions, type RenderReport, type RepairResult, type ReportInput, type ReportSeverity, type ResolvedEntrance, type ResolvedSeries, type ResolvedSketch, type Rng, type RoughContext, RoughPen, type RoughStyle, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SR_ONLY_STYLE, type SankeySpec, type ScaleConfig, type ScaleType, type ScatterInsights, type ScatterSpec, type SearchSlicerSpec, type SelectConfig, type SelectionChangeListener, type SelectionDef, type SelectionListener, type SelectionParam, type SelectionStore, type SelectionValue, type SeriesInsights, type SetSelection, type SharedScales, type Size, type SketchConfig, type SlicerSpec, type SlicerType, type SlopeSpec, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, type TableColumn, type TableSpec, type TextMetricsLite, type TextSelection, type ThemeColors, type ThemeFont, type ThemeInput, type ThemeTokens, type Tick, type TimeScaleOptions, type TimeUnit, type TimeUnitTransform, type TitleConfig, type TitleInput, Tooltip, type TooltipConfig, type TooltipContent, type TooltipRow, type Transform, type TreemapSpec, type TrendlineConfig, type UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueInsights, type ValueRef, type ValueRule, type WaterfallSpec, type WiredView, type XKind, type XModel, type YModel, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, chartTitleText, chartTypeLabel, checkExpression, clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatDate, formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, relativeLuminance, render, renderDashboard, renderToContext, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
+export { type AggOp, type AggregateOp, type AggregateTransform, type AnimateOptions, type AnimationConfig, type AnimationHandle, type Annotation, type AnySpec, type ArcOptions, type AreaOptions, type AreaPoint, type AreaSpec, type AxesConfig, type AxisConfig, type AxisInput, type BackingSize, type BandScale, type BandScaleOptions, type BarSpec, type BaseSlicerSpec, type BaseSpec, type BinLayout, type BinTransform, type BoxSpec, type BuildOptions, type BulletSpec, CARTESIAN_TYPES, CHART_TYPES, type CalculateTransform, type CalendarHeatmapSpec, CanvasLayer, type CanvasPillStyle, type CanvasTextCmd, type CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type CategoryInsights, type ChartInsights, type ChartInstance, type ChartSpec, type ChartSummary, type ChartType, type ChoroplethSpec, type ColorScale, type ColumnProfile, type ComboAxisModel, type ComboLayer, type ComboLayerModel, type ComboMark, type ComboModel, type ComboSide, type ComboSpec, type Comparable, type ConditionalFormat, type ContinuousScale, type ControllerSelect, type Curve, type CurveType, type CustomRenderer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, type DashboardCell, type DashboardInstance, type DashboardLayout, type DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DateRangeSlicerSpec, type Datum, type DecimateOptions, type Dimensions, type DropdownSlicerSpec, type DumbbellSpec, type EasingFunction, type Emphasis, type Encoding, type EntranceContext, ExpressionError, type Extent, FACETABLE_TYPES, FUNCTION_NAMES, type FacetConfig, type FacetLayout, type FacetPanel, type FieldDef, type FieldType, type FieldValue, type FillStyle, type FilterClause, type FilterPredicate, type FilterTransform, type FoldTransform, type Frame, type FrameInput, type FunnelSpec, type GaugeSpec, type GeoFeature, type GeoFeatureCollection, type GeoGeometry, type GeoMultiPolygon, type GeoPolygon, type GeoPosition, type GroupedMap, type HachureSegment, type HeadlessTarget, type HeatmapSpec, type HighlightConfig, type HistogramBin, type HistogramBinDatum, type HistogramModel, type HistogramSpec, type Hover, type IconRule, type Insets, type InsightFamily, type InsightOptions, InteractionController, type InteractionLink, type InteractionModel, type Interpolator, type JsonPatchOp, type KpiSpec, type LegendConfig, type LegendHitRegion, type LegendItem, type LegendPosition, type LegendSymbol, type LineOptions, type LineSpec, type LinearScaleOptions, type LintFinding, type ListSlicerSpec, type LiteralPredicate, type LogScaleOptions, type MapProjection, type MarkOptions, type MatrixSpec, type MatrixValueDef, type NumberFormatSpec, type OKLCH, type OKLab, type OverlayTextOpts, type PathSink, type PieLabels, type PieSpec, type PivotCell, type PivotFlatRow, type PivotHeaderNode, type PivotOptions, type PivotResult, type PivotValueDef, type Point, type PointRef, type PointScale, type PointScaleOptions, type PointSelection, type PositionedLegendItem, type RGBA, type RangeSelection, type RangeSlicerSpec, type RecommendOptions, type RecommendedChart, type Rect, type RegressionFit, type RenderContext, type RenderDashboardOptions, type RenderDiagnostic, type RenderOptions, type RenderReport, type RepairResult, type ReportInput, type ReportSeverity, type ResolvedEntrance, type ResolvedSeries, type ResolvedSketch, type Rng, type RoughContext, RoughPen, type RoughStyle, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SR_ONLY_STYLE, type SankeySpec, type ScaleConfig, type ScaleType, type ScatterInsights, type ScatterSpec, type SearchSlicerSpec, type SelectConfig, type SelectionChangeListener, type SelectionDef, type SelectionListener, type SelectionParam, type SelectionStore, type SelectionValue, type SeriesInsights, type SetSelection, type SharedScales, type Size, type SketchConfig, type SlicerSpec, type SlicerType, type SlopeSpec, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, type TableColumn, type TableSpec, type TextMetricsLite, type TextSelection, type ThemeColors, type ThemeFont, type ThemeInput, type ThemeTokens, type Tick, type TimeScaleOptions, type TimeUnit, type TimeUnitTransform, type TitleConfig, type TitleInput, Tooltip, type TooltipConfig, type TooltipContent, type TooltipRow, type Transform, type TreemapSpec, type TrendlineConfig, type UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueInsights, type ValueRef, type ValueRule, type WaterfallSpec, type WiredView, type XKind, type XModel, type YModel, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatDate, formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, relativeLuminance, render, renderDashboard, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };