@opendata-ai/openchart-core 8.7.0 → 8.9.0

package/dist/index.d.ts

@@ -480,6 +480,13 @@ interface ResolvedChrome {
     brand?: ResolvedChromeElement;
     /** Annotation footnotes generated by auto-thinning. Rendered as a numbered list above the source line. */
     footnotes?: AnnotationFootnote[];
+    /** Responsive series readout above source/methodology. */
+    seriesSummary?: Array<{
+        key: string;
+        text: string;
+        lines: string[];
+        color: string;
+    }>;
     /** Absolute y at which bottom-chrome relative offsets are anchored: area.y + area.height + x-axis extent. */
     bottomAnchorY?: number;
 }
@@ -1206,6 +1213,8 @@ interface ContinuousLegendTick {
     x: number;
     /** Horizontal text anchor for the label. */
     anchor: 'start' | 'middle' | 'end';
+    /** Additional baseline offset for staggered class boundaries (pixels). */
+    offsetY?: number;
 }
 /** A discrete class swatch in a binned continuous legend. */
 interface ContinuousLegendBin {
@@ -1431,6 +1440,8 @@ interface A11yMetadata {
 }
 /** One fully-resolved animation phase. */
 interface ResolvedAnimationPhase {
+    /** Present for bounded spring mode; duration is its finite settling time. */
+    spring?: SpringConfig;
     /** Duration in ms. */
     duration: number;
     /** Easing preset name. */
@@ -2404,6 +2415,8 @@ type MeasureTextFn = (text: string, fontSize: number, fontWeight?: number) => {
  * chrome, axes, and legend to compute the chart drawing area.
  */
 interface CompileOptions {
+    /** Structured design review; emitted from the resolved chart geometry. */
+    onDiagnostic?: (diagnostic: DesignDiagnostic) => void;
     /** Total available width in pixels. */
     width: number;
     /** Total available height in pixels. */
@@ -4103,6 +4116,14 @@ interface SeriesStyle {
  * Uses CSS linear() curves. Named 'ease' (not 'easing') to match Vega convention.
  */
 type AnimationEase = 'smooth' | 'snappy';
+/** Opt-in motion language. `legacy` preserves the v8 tween timing. */
+type AnimationPreset = 'fluid' | 'subtle' | 'legacy';
+/** Physical spring parameters. Quantitative motion is bounded at critical damping. */
+interface SpringConfig {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+}
 /** Stagger configuration for sequential element reveal. */
 interface AnimationStagger {
     /** Delay between each element in ms. Default: 80 */
@@ -4112,6 +4133,10 @@ interface AnimationStagger {
 }
 /** Fine-grained responsive behavior configuration. */
 interface ResponsiveConfig {
+    /** Preserve the final temporal boundary before thinning interior ticks. */
+    preserveEnd?: boolean;
+    /** Move direct series labels into a keyed list when the inline column cannot fit. */
+    labelSummary?: boolean;
     /**
      * Automatic annotation thinning at narrow widths. When true (default),
      * annotations that can't be placed without overlap are demoted to numbered
@@ -4125,6 +4150,8 @@ interface ResponsiveConfig {
  * Each phase can be true (use defaults) or a config object.
  */
 interface AnimationPhaseConfig {
+    /** Spring mode. Cannot be combined with duration or ease in this phase. */
+    spring?: SpringConfig;
     /** Duration in ms. Default: 500 for enter. */
     duration?: number;
     /** Easing preset. Default: 'smooth'. */
@@ -4151,6 +4178,8 @@ interface UpdatePhaseConfig extends AnimationPhaseConfig {
  * following Vega's encoding set model.
  */
 interface AnimationConfig {
+    /** Base preset; explicit phase settings take precedence. */
+    preset?: AnimationPreset;
     /** Entrance animation when chart first renders. */
     enter?: AnimationPhaseConfig | boolean;
     /** Transition animation when data updates. */
@@ -4166,7 +4195,7 @@ interface AnimationConfig {
  * - false/omitted: no animation (current behavior)
  * - AnimationConfig: full control via enter/update/exit phases
  */
-type AnimationSpec = boolean | AnimationConfig;
+type AnimationSpec = boolean | AnimationPreset | AnimationConfig;
 /**
  * Chart display mode.
  * - `'full'` (default): standard chart with chrome, axes, legend, padding.
@@ -4417,6 +4446,8 @@ interface A11yConfig {
  * @internal
  */
 interface BaseChartSpec<TData extends DataRow = DataRow> {
+    /** Optional authored measure, unit, provenance, and supplied interval metadata. */
+    fields?: Record<string, FieldMetadata>;
     /**
      * Data array: each element is a row with field values.
      * The Vega-Lite object form `{ values: [...] }` is also accepted at runtime
@@ -4722,6 +4753,10 @@ type TableDensity = 'condensed' | 'regular' | 'relaxed';
  * heatmap coloring, inline sparklines, sorted columns, search, and pagination.
  */
 interface TableSpec {
+    /** Compact layout. v8 defaults to cards; priority retains comparable columns with expandable details. */
+    mobileLayout?: 'cards' | 'priority' | 'scroll';
+    /** Optional authored measure, unit, provenance, and supplied interval metadata. */
+    fields?: Record<string, FieldMetadata>;
     /** Discriminant: always "table". */
     type: 'table';
     /** Data array: each element is a row. */
@@ -5217,6 +5252,19 @@ type GeoMapFocus = string | number | Array<string | number> | {
     points: GeoMapPointsFocus;
     padding?: number;
 };
+/**
+ * Reader zoom and pan for a map. Opt-in: maps without it stay static.
+ *
+ * `maxZoom` caps how far readers can zoom in, as a multiple of the full map
+ * (the full map is 1, and readers can never zoom out past it). `controls`
+ * shows the on-screen zoom in / zoom out / reset buttons.
+ */
+interface GeoMapZoomConfig {
+    /** Largest zoom factor, relative to the full map. Default 12, minimum 1. */
+    maxZoom?: number;
+    /** Show on-screen zoom in / zoom out / reset buttons. Default true. */
+    controls?: boolean;
+}
 /** Geo configuration for map specs. */
 interface GeoMapGeo {
     /** TopoJSON topology object. User imports this from us-atlas, world-atlas, or their own source. */
@@ -5238,6 +5286,15 @@ interface GeoMapGeo {
      * story can pan between sub-clusters. null clears focus from a prior story step.
      */
     focus?: GeoMapFocus | null;
+    /**
+     * Let readers zoom and pan the map. Off by default. `true` enables it with
+     * defaults; an object tunes the zoom ceiling and the on-screen buttons.
+     * Gestures: ctrl/cmd + wheel or trackpad pinch zooms around the cursor (a
+     * plain wheel scrolls the page), drag pans, double-click zooms in, two-finger
+     * pinch zooms on touch, and +/-/arrows/0 work when the map has focus. One
+     * finger scrolls the page until the reader has zoomed in, then pans the map.
+     */
+    zoom?: boolean | GeoMapZoomConfig;
 }
 /** Encoding channels specific to map visualizations. */
 interface GeoMapEncoding {
@@ -5269,6 +5326,8 @@ interface GeoMapPointsLayer {
     opacity?: number;
 }
 interface GeoMapSpec {
+    /** Optional authored measure, unit, provenance, and supplied interval metadata. */
+    fields?: Record<string, FieldMetadata>;
     /** Discriminant: always "map". */
     type: 'map';
     /** Geo configuration: TopoJSON features, join key, and projection. */
@@ -5678,6 +5737,81 @@ declare function isRefLineAnnotation(annotation: Annotation): annotation is RefL
 /** Human-readable display names for mark types (used in alt text, error messages). */
 declare const MARK_DISPLAY_NAMES: Record<MarkType, string>;
 
+/** Supplied semantics; the library never invents a measure or uncertainty. */
+interface FieldMetadata {
+    /** Explicit imported field type; preserved with the portable document. */
+    type?: 'text' | 'number' | 'date';
+    /** Identifies an internal, persistent row identity column. */
+    role?: 'identity';
+    label?: string;
+    unit?: string;
+    measure?: string;
+    provenance?: string;
+    /** Percent is encoded 0–100; proportion is encoded 0–1. */
+    representation?: 'number' | 'percent' | 'proportion';
+    interval?: {
+        lower: string;
+        upper: string;
+    };
+    statusField?: string;
+}
+interface DesignDiagnostic {
+    code: string;
+    severity: 'info' | 'warning' | 'error';
+    status: 'failed' | 'uncheckable';
+    path: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    message: string;
+    origin: 'author' | 'default';
+    fix?: SpecPatch;
+}
+/** Atomic JSON-pointer edits guarded by the complete source document. */
+interface SpecPatch {
+    label: string;
+    /** Canonical source snapshot prevents stale fixes overwriting subsequent edits. */
+    precondition: string;
+    changes: Array<{
+        path: string;
+        value: unknown;
+    }>;
+}
+type DesignQuestion = 'comparison' | 'change' | 'distribution' | 'composition' | 'geography' | 'relationships';
+interface CompositionRecommendation {
+    id: string;
+    title: string;
+    reason: string;
+    tradeoff: string;
+    spec: VizSpec;
+}
+interface ObservationIdentity {
+    observation: string;
+    series?: string;
+    persistent: boolean;
+}
+interface ReaderObservation extends ObservationIdentity {
+    /** Aggregates are visible groups and never imply a raw-row selection. */
+    kind?: 'row' | 'aggregate';
+    datum: DataRow;
+    previous?: DataRow;
+    state: 'visible' | 'filtered';
+}
+interface ReaderSelection {
+    preview: ReaderObservation | null;
+    pinned: ReaderObservation[];
+    announcement: string;
+}
+/** Explicit relationships; aggregate groups never masquerade as raw rows. */
+interface DatasetBinding {
+    dataset: string;
+    entityField: string;
+    kind: 'row' | 'group';
+    transform?: string;
+    groupMembers?: Record<string, Array<string | number>>;
+}
+
 /**
  * Per-mark-type encoding validation rules.
  *
@@ -6224,6 +6358,10 @@ declare const broadsheet: ThemeConfig;
  * siblings, the register a monitoring UI wants.
  */
 declare const terminal: ThemeConfig;
+/** Next-generation editorial composition; opt in during v8. */
+declare const clarity: ThemeConfig;
+/** Documented v8 typography. This does not freeze the layout engine. */
+declare const legacyEditorial: ThemeConfig;
 
 /**
  * Theme resolver: deep-merges user overrides onto default theme.
@@ -6956,6 +7094,30 @@ declare function tileMap(data: Record<string, number | string | null> | DataRow[
  */
 declare function deepMergeSpec(target: any, source: any): any;
 
+/** Deterministic, bounded motion shared by rendering and timestamp-based export. */
+
+interface MotionPhase {
+    duration: number;
+    ease?: AnimationEase;
+    spring?: SpringConfig;
+}
+interface MotionSample {
+    /** Normalized progress; quantitative geometry never overshoots its endpoints. */
+    position: number;
+    /** Normalized distance per second. */
+    velocity: number;
+    settled: boolean;
+}
+declare const MOTION_REST_THRESHOLD = 0.001;
+declare const MAX_SPRING_DURATION = 1200;
+declare const FLUID_SPRING: Readonly<Required<SpringConfig>>;
+/** Resolve finite duration once, outside the frame loop. */
+declare function springDuration(config: SpringConfig): number;
+/** All callers, including exports, pass elapsed milliseconds explicitly. */
+declare function sampleMotion(phase: MotionPhase, elapsedMs: number): MotionSample;
+/** CSS samples use the same clock and evaluator as SVG, canvas, and export. */
+declare function motionCSS(phase: MotionPhase): string;
+
 interface CssTokenDef {
     name: string;
     light: string;
@@ -6980,4 +7142,4 @@ declare const CSS_TOKEN_ROOT_SELECTORS: readonly string[];
 declare const CSS_TOKENS: readonly CssTokenDef[];
 declare function cssTokenDefault(name: string, mode: 'light' | 'dark'): string;
 
-export { type A11yConfig, type A11yMetadata, ACHROMATIC_RAMP, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationFootnote, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BeeswarmEncoding, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_EXTENDED_PALETTE, CATEGORICAL_FILL_PALETTE, CATEGORICAL_FILL_PALETTE_DARK, CATEGORICAL_PALETTE, CATEGORICAL_PALETTE_DARK, COMPACT_MAX_X_TICKS, COMPACT_WIDTH, CSS_TOKENS, CSS_TOKEN_ROOT_SELECTORS, type CalculateExpression, type CalculateTransform, type CalendarEncoding, type CategoricalLegendLayout, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type Chrome, type ChromeDefaults, type ChromeEconomy, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type CompileWarning, type Condition, type ConditionalValueDef, type ConnectorConfig, type ConnectorType, type ContinuousLegendBin, type ContinuousLegendLayout, type ContinuousLegendTick, type CssTokenDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DeltaColumnConfig, type DeltaTableCell, type DensityEncoding, type DensityTransform, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelContent, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, FOOTNOTE_LINE_HEIGHT, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldFormatContext, type FieldPredicate, type FieldRef, type FieldType, type FillPatternType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GeoMapBorders, type GeoMapEncoding, type GeoMapFeatureMark, type GeoMapFocus, type GeoMapFocusLayout, type GeoMapGeo, type GeoMapLayout, type GeoMapPointMark, type GeoMapPointsLayer, type GeoMapProjection, type GeoMapSpec, type GeoMapSpecWithoutData, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphAnimationConfig, type GraphAnimationSpec, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphInteractionConfig, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_MINIMAL_MAX, HEIGHT_NO_GRID_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type HistogramEncoding, type ImageColumnConfig, type ImageTableCell, type JoinAggregateTransform, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendChannel, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, MAX_SR_TABLE_ROWS, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NeutralRamp, type NodeOverride, type NumberFormatter, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type ParliamentEncoding, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type RangeEncoding, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnimationPhase, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedChromeRule, type ResolvedColumn, type ResolvedFillPattern, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedSeriesSearch, type ResolvedTheme, type ResolvedThemeColors, type ResolvedYouDrawIt, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, SUPPORTED_SCHEME_NAMES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleInvert, type ScaleType, type SequentialPalette, type SeriesSearchConfig, type SeriesStrategy, type SeriesStyle, type SizeLegendCircle, type SizeLegendLayout, type SortByField, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TICK_LINE_HEIGHT_FACTOR, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableDensity, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TableTotalRow, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeRule, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TokenValue, type TooltipContent, type TooltipField, type Transform, type UpdatePhaseConfig, type ValueDef, type VizSpec, type WaffleEncoding, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_ROTATED_EXTENT_CAP, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, type YouDrawItConfig, type YouDrawItSample, type YouDrawItYInvert, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, broadsheet, buildCompactStepFormatter, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeFieldFormatContext, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, cssTokenDefault, dataTable, deepMergeSpec, defaultNumberFormatter, deriveNeutralRamp, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, footnoteBandHeight, formatCurrency, formatDate, formatNumber, formatOrdinal, formatPercent, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isAxislessMark, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGeoMapSpec, isGradientDef, isGraphSpec, isLayerSpec, isOpaqueColor, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, isValueDef, isYearContext, lineChart, maxRotatedLabelWidth, meetsAA, overlapArea, pickLabelColor, pieChart, resolveChromeEconomy, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveNumberFormatter, resolveSchemeName, resolveTheme, scatterChart, simulateColorBlindness, terminal, textAscent, tileMap, truncateRotatedLabel, truncateToWidth, wire, wrapText };
+export { type A11yConfig, type A11yMetadata, ACHROMATIC_RAMP, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationPreset, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationFootnote, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BeeswarmEncoding, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_EXTENDED_PALETTE, CATEGORICAL_FILL_PALETTE, CATEGORICAL_FILL_PALETTE_DARK, CATEGORICAL_PALETTE, CATEGORICAL_PALETTE_DARK, COMPACT_MAX_X_TICKS, COMPACT_WIDTH, CSS_TOKENS, CSS_TOKEN_ROOT_SELECTORS, type CalculateExpression, type CalculateTransform, type CalendarEncoding, type CategoricalLegendLayout, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type Chrome, type ChromeDefaults, type ChromeEconomy, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type CompileWarning, type CompositionRecommendation, type Condition, type ConditionalValueDef, type ConnectorConfig, type ConnectorType, type ContinuousLegendBin, type ContinuousLegendLayout, type ContinuousLegendTick, type CssTokenDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DatasetBinding, type DateGranularity, type DeltaColumnConfig, type DeltaTableCell, type DensityEncoding, type DensityTransform, type DesignDiagnostic, type DesignQuestion, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelContent, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, FLUID_SPRING, FOOTNOTE_LINE_HEIGHT, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldFormatContext, type FieldMetadata, type FieldPredicate, type FieldRef, type FieldType, type FillPatternType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GeoMapBorders, type GeoMapEncoding, type GeoMapFeatureMark, type GeoMapFocus, type GeoMapFocusLayout, type GeoMapGeo, type GeoMapLayout, type GeoMapPointMark, type GeoMapPointsLayer, type GeoMapProjection, type GeoMapSpec, type GeoMapSpecWithoutData, type GeoMapZoomConfig, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphAnimationConfig, type GraphAnimationSpec, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphInteractionConfig, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_MINIMAL_MAX, HEIGHT_NO_GRID_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type HistogramEncoding, type ImageColumnConfig, type ImageTableCell, type JoinAggregateTransform, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendChannel, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, MAX_SPRING_DURATION, MAX_SR_TABLE_ROWS, MOTION_REST_THRESHOLD, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, type MotionPhase, type MotionSample, NARROW_VIEWPORT_MAX, type NeutralRamp, type NodeOverride, type NumberFormatter, OFFSET_STRATEGIES, type ObservationIdentity, type OffsetStrategy, type PaginationState, type ParliamentEncoding, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type RangeEncoding, type ReaderObservation, type ReaderSelection, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnimationPhase, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedChromeRule, type ResolvedColumn, type ResolvedFillPattern, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedSeriesSearch, type ResolvedTheme, type ResolvedThemeColors, type ResolvedYouDrawIt, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, SUPPORTED_SCHEME_NAMES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleInvert, type ScaleType, type SequentialPalette, type SeriesSearchConfig, type SeriesStrategy, type SeriesStyle, type SizeLegendCircle, type SizeLegendLayout, type SortByField, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type SpecPatch, type SpringConfig, type StoredVizSpec, TICK_LABEL_OFFSET, TICK_LINE_HEIGHT_FACTOR, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableDensity, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TableTotalRow, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeRule, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TokenValue, type TooltipContent, type TooltipField, type Transform, type UpdatePhaseConfig, type ValueDef, type VizSpec, type WaffleEncoding, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_ROTATED_EXTENT_CAP, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, type YouDrawItConfig, type YouDrawItSample, type YouDrawItYInvert, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, broadsheet, buildCompactStepFormatter, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, clarity, columnChart, computeChrome, computeFieldFormatContext, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, cssTokenDefault, dataTable, deepMergeSpec, defaultNumberFormatter, deriveNeutralRamp, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, footnoteBandHeight, formatCurrency, formatDate, formatNumber, formatOrdinal, formatPercent, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isAxislessMark, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGeoMapSpec, isGradientDef, isGraphSpec, isLayerSpec, isOpaqueColor, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, isValueDef, isYearContext, legacyEditorial, lineChart, maxRotatedLabelWidth, meetsAA, motionCSS, overlapArea, pickLabelColor, pieChart, resolveChromeEconomy, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveNumberFormatter, resolveSchemeName, resolveTheme, sampleMotion, scatterChart, simulateColorBlindness, springDuration, terminal, textAscent, tileMap, truncateRotatedLabel, truncateToWidth, wire, wrapText };

package/dist/index.js

@@ -1771,6 +1771,23 @@ var terminal = {
   borderRadius: 4,
   seriesStrategy: "accent-neutral"
 };
+var clarity = {
+  colors: {
+    background: { light: "#ffffff", dark: "#09090b" },
+    axis: { light: "#52525b", dark: "#a1a1aa" }
+  },
+  fonts: { sizes: { title: 26, subtitle: 14, body: 13, small: 12, axisTick: 12 } },
+  chrome: {
+    eyebrow: { color: { light: "#0f766e", dark: "#5eead4" } },
+    source: { fontSize: 12 },
+    footer: { fontSize: 12 }
+  },
+  spacing: { chromeToChart: 16, chartToFooter: 12 }
+};
+var legacyEditorial = {
+  fonts: { sizes: { title: 26, subtitle: 14, body: 13, small: 11, axisTick: 11 } },
+  spacing: { padding: 20, chromeGap: 6, chromeToChart: 8, chartToFooter: 8 }
+};
 
 // src/theme/resolve.ts
 function deepMerge(target, source) {
@@ -3089,6 +3106,82 @@ function deepMergeSpec(target, source) {
   }
   return result;
 }
+
+// src/motion/sample.ts
+var MOTION_REST_THRESHOLD = 1e-3;
+var MAX_SPRING_DURATION = 1200;
+var FLUID_SPRING = {
+  stiffness: 320,
+  damping: 36,
+  mass: 1
+};
+function springState(timeMs, config) {
+  const stiffness = config.stiffness ?? FLUID_SPRING.stiffness;
+  const mass = config.mass ?? FLUID_SPRING.mass;
+  const rootStiffness = Math.sqrt(stiffness);
+  const rootMass = Math.sqrt(mass);
+  const omega = rootStiffness / rootMass;
+  const damping = config.damping ?? FLUID_SPRING.damping;
+  const zeta = Math.max(1, damping / rootStiffness / rootMass / 2);
+  const t = Math.max(0, timeMs) / 1e3;
+  let remaining;
+  let velocity;
+  if (zeta - 1 < 1e-4) {
+    const scaledTime = omega * t;
+    const decay = Math.exp(-scaledTime);
+    remaining = decay === 0 ? 0 : (1 + scaledTime) * decay;
+    velocity = decay === 0 ? 0 : omega * (scaledTime * decay);
+  } else {
+    const inverseZeta = 1 / zeta;
+    const q = damping / 2 * (1 + Math.sqrt(1 - inverseZeta * inverseZeta));
+    const slow = -stiffness / q;
+    const fast = -q / mass;
+    const ratio = slow / fast;
+    const slowDecay = Math.exp(slow * t);
+    const fastDecay = Math.exp(fast * t);
+    if (slowDecay === 0) {
+      remaining = 0;
+      velocity = 0;
+    } else {
+      remaining = (slowDecay - ratio * fastDecay) / (1 - ratio);
+      velocity = -slow * ((slowDecay - fastDecay) / (1 - ratio));
+    }
+  }
+  return {
+    position: Math.min(1, Math.max(0, 1 - remaining)),
+    velocity,
+    settled: remaining <= MOTION_REST_THRESHOLD && Math.abs(velocity) <= MOTION_REST_THRESHOLD
+  };
+}
+function springDuration(config) {
+  for (const name of ["stiffness", "damping", "mass"]) {
+    const value = config[name];
+    if (value === void 0) continue;
+    if (!Number.isFinite(value) || value <= 0)
+      throw new Error(`spring.${name} must be finite and positive`);
+  }
+  for (let ms = 1; ms < MAX_SPRING_DURATION; ms++) {
+    if (springState(ms, config).settled) return ms;
+  }
+  return MAX_SPRING_DURATION;
+}
+function sampleMotion(phase, elapsedMs) {
+  if (phase.duration <= 0 || elapsedMs >= phase.duration) {
+    return { position: 1, velocity: 0, settled: true };
+  }
+  if (elapsedMs <= 0) return { position: 0, velocity: 0, settled: false };
+  if (phase.spring) return springState(elapsedMs, phase.spring);
+  const t = elapsedMs / phase.duration;
+  const power = phase.ease === "snappy" ? 5 : 3;
+  return {
+    position: 1 - (1 - t) ** power,
+    velocity: power * (1 - t) ** (power - 1) * 1e3 / phase.duration,
+    settled: false
+  };
+}
+function motionCSS(phase) {
+  return `linear(${Array.from({ length: 101 }, (_, i) => sampleMotion(phase, i * phase.duration / 100).position.toFixed(6)).join(",")})`;
+}
 export {
   ACHROMATIC_RAMP,
   AXIS_TITLE_GAP,
@@ -3112,6 +3205,7 @@ export {
   DEFAULT_THEME,
   DIVERGING_PALETTES,
   EXTENDED_OFFSET_STRATEGIES,
+  FLUID_SPRING,
   FOOTNOTE_LINE_HEIGHT,
   GRAPH_ENCODING_RULES,
   HEIGHT_CRAMPED_MAX,
@@ -3130,7 +3224,9 @@ export {
   MAX_LEFT_LABEL_FRACTION_DEFAULT,
   MAX_LEFT_LABEL_FRACTION_MEDIUM,
   MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  MAX_SPRING_DURATION,
   MAX_SR_TABLE_ROWS,
+  MOTION_REST_THRESHOLD,
   NARROW_VIEWPORT_MAX,
   OFFSET_STRATEGIES,
   SEQUENTIAL_PALETTES,
@@ -3155,6 +3251,7 @@ export {
   buildD3Formatter,
   buildTemporalFormatter,
   checkPaletteDistinguishability,
+  clarity,
   columnChart,
   computeChrome,
   computeFieldFormatContext,
@@ -3208,9 +3305,11 @@ export {
   isTileMapSpec,
   isValueDef,
   isYearContext,
+  legacyEditorial,
   lineChart,
   maxRotatedLabelWidth,
   meetsAA,
+  motionCSS,
   overlapArea,
   pickLabelColor,
   pieChart,
@@ -3222,8 +3321,10 @@ export {
   resolveNumberFormatter,
   resolveSchemeName,
   resolveTheme,
+  sampleMotion,
   scatterChart,
   simulateColorBlindness,
+  springDuration,
   terminal,
   textAscent,
   tileMap,