Skip to content
HDCharts

Entry Seam and Chart Policy

Indexed ChartData enters through ChartEntry in charts-core. A chart declares a ChartSpec with its validation policy, conversion, and style clamping. Charts with other data models own these operations in their chart entry and reuse shared helpers where the inputs fit.

Input flow

Loading diagram…

ChartEntry returns after displaying errors, so invalid input never reaches conversion or content. The chart resolves selection against public data before conversion.

Validation is remembered against the data, spec, a value-based snapshot of the validation inputs, density, and any additional errors. Equivalent validation values reuse the result even when a caller creates a new style instance. Conversion is remembered against the spec, data, and title; clamping against the spec, full style, and density.

See Pipeline and Stage Ownership for layout and drawing responsibilities.

ChartSpec

A spec keeps the chart's input decisions together:

MemberResponsibility
policySelects checks and maps the style to their inputs
convertProduces ChartRenderData; the default wraps the caller's data and title
clampDelegates to the chart style's clamp(density) extension

Override conversion when the renderer needs a different data shape. Stacked bar, for example, transposes series into bars. Style-clamping rules stay with the style blocks.

LineChartEntry.kt shows a spec and entry shared by LineChart and LiveLineChart. Their content differs, so the entry accepts a content lambda.

ChartPolicy

ChartPolicy<S> declares the checks for indexed series and supplies their style inputs.

FieldResponsibility
SeriesRule.SingleRequires one series and matches explicit colors to its values
SeriesRule.MultipleValidates aligned series; declares minimum values, negative-value rules, stacking, and expected colors
colorCountReads the explicit palette size; zero skips color matching
rangeSupplies range bounds for validation; null means this capability does not apply
axesSupplies both X- and Y-label validation settings; null means this capability does not apply

RangeInputs(min = null, max = null) declares an automatic range. That differs from a null range mapper, which declares no range validation.

SeriesRule.Multiple.expectedColors derives the expected palette size from data. Returning null skips matching for that dataset. Radar uses this to check colors only when it has multiple series.

The shared policy checks data shape, range, then axis labels. Validation Errors describes those checks and their messages.

Current indexed-policy expectations live in ChartPolicyConformanceTest. The test lists its cases explicitly, so adding a spec also requires adding its test case.

Other data models

A chart with different input semantics owns validation in its entry. Scatter checks independent X/Y points, Heatmap checks a labeled matrix with optional missing cells, and Waterfall checks ordered changes and running totals. Use their entry files as examples when a new model needs its own contract.

Reuse ChartErrors, axis-label validation, range validation, and the selection lifecycle where applicable. Pass validated data directly to content when conversion adds no value. Remember validation against every input it reads, including relevant style values and density.

An indexed chart can also supply additionalErrors to ChartEntry for checks outside the shared policy, such as Segmented Ring Gauge's capacity and total checks.

Adding a chart or changing a rule

  • Declare its policy, conversion, and clamping in the chart entry. Indexed policies use ChartSpec.
  • Update ChartPolicyConformanceTest for an indexed policy and the chart's tests for its own input rules. The umbrella owns the shared conformance test because it depends on the chart modules.
  • Put shared checks in the existing validation helpers; keep model-specific checks with the chart.
  • Test that invalid input renders errors and valid input reaches content with a drawable style.
  • Update Validation Errors when introducing a new kind of validation.

Tests

BehaviorTests
Policy mappers enable their checksChartPolicyTest in charts-core
Invalid input stops before content; clamping uses current densityChartEntryTest in charts-core
Indexed policies match expected rulesChartPolicyConformanceTest in charts
Model-specific validation and displayed errorsEach chart's tests