# ggaction
ggaction is a JavaScript chart-authoring library built around immutable,
hierarchical actions. Use this file as a routing index. The linked selective
HTML routes are canonical; the generated full-text bundle is available at
./llms-full.txt.

## Start

- Documentation overview: ./
- npm installation and first runnable chart: ./getting-started/
- Chart recipes: ./recipes/
- Complete public action reference: ./reference/actions/
- Supported features and limitations: ./supported-features/
- Inference and layout troubleshooting: ./troubleshooting/

## Public API layers

- Basic scatter, line, bar, histogram, and heatmap charts: ./api/basic-charts/
- Chart authoring: ./reference/actions/charts-data/
- Advanced chart actions: ./reference/actions/advanced/
- Extension action authoring: ./extension/action-authoring/
- Primitive extension API: ./extension/primitives/
- Browser and PNG rendering: ./api/rendering/
- Data and scales: ./api/data/ | ./api/scales/
- Legends and series encodings: ./api/legends/ | ./api/series-encodings/
- Mark appearance, selection, and highlighting: ./api/appearance/
- Vertical and horizontal statistical and explicit error bands: ./api/error-bands/
- Vertical/horizontal Tukey and min–max box plots: ./api/box-plots/
- Vertical/horizontal categorical gradient plots: ./api/gradient-plots/

Only methods declared on the public ChartProgram TypeScript type are supported
direct-call actions. Additional wrapped names may appear in action traces but
are internal operations.

## Chart recipes and tutorials

- Scatterplot: ./recipes/scatterplot/ | ./tutorials/scatterplot/
- Polar point chart: ./tutorials/polar-points/ | ./api/position-encodings/#polar-positions
- Line chart: ./recipes/line-chart/ | ./tutorials/line-chart/
- Histogram: ./recipes/histogram/ | ./tutorials/histogram/
- Bar chart: ./recipes/bar-chart/ | ./tutorials/grouped-bar/
- Heatmap: ./recipes/heatmap/ | ./api/basic-charts/#createheatmap
- Regression scatterplot: ./recipes/regression-scatterplot/ | ./tutorials/regression-scatterplot/
- Density area: ./recipes/density-area/ | ./tutorials/density-area/
- Error bar: ./recipes/error-bar/ | ./tutorials/error-bar/
- Mark selection and highlighting: ./tutorials/mark-selection/ | ./api/appearance/selection-and-highlighting/

## Core concepts

- Immutable ChartProgram: ./concepts/chart-program/
- Semantic and graphical state: ./concepts/semantic-and-graphics/
- Hierarchical action traces: ./concepts/actions-and-trace/

## Essential invariants

- Every action accepts one option object and returns a new ChartProgram.
- Existing programs and caller-owned inputs are never mutated.
- semanticSpec records chart meaning.
- graphicSpec stores fully materialized backend-neutral graphics.
- There is no automatic semantic-to-graphic compiler.
- Domain actions explicitly invoke graphical materialization.
- Renderers read graphicSpec only.
- Omitted values are resolved as explicit option, unique inference, documented
  default, then an error when no safe choice exists.
- The first unnamed source dataset is stored as `"data"`; the first unnamed
  point, line, bar, or area mark uses its type name. Repeated roles require an
  explicit ID rather than receiving an automatic numeric suffix.

## Current scope

The development build supports Cartesian scatterplots with linear, log, power,
square-root, and symmetric-log point-position scales, temporal mean line
charts, stacked histograms, ordinal grouped bars, grouped linear, polynomial,
or LOESS regression scatterplots with optional mean/prediction bands, grouped density areas,
vertical or horizontal statistical/explicit error bars with encoded-layer
inference, optional caps, and constant rule appearance, and vertical or
horizontal grouped statistical/explicit error bands.
Polar point charts support clockwise degree theta, quantitative radial position, theta/radius axes and grids, ordinary point appearance, filtering, selection, Canvas resizing, and PNG output.
The box-plot aggregate supports vertical or horizontal categorical and
quantitative pairings with Tukey or min-max whiskers, immutable summary/outlier data, and
1.5px median and whisker defaults. The gradient-plot aggregate supports the same
x/y family, immutable sampled profiles, optional center rules, category-strip
selection/highlighting, source-first filtering, and Cartesian facet replay.
Cartesian guides support bottom/top x axes, left/right y axes, and closed
numeric or UTC label-format tokens. Existing horizontal and vertical grids can
be edited independently without changing their scale or coordinate binding.
Categorical, composite point/size, gradient, and opacity legends have stable
layout/appearance edits. Categorical legends support all four edges; combined
point/size legends remain side-positioned.
Chart titles support four edges, deterministic word/character wrapping, and stable partial edits including subtitle removal.
`selectMarks` creates reusable selections over point, bar-item/bar-stack,
line/area series, and rule items. Its explicit value sources distinguish data
fields, pre-scale semantic channels, and concrete graphic properties.
`highlightMarks` applies mark-specific concrete emphasis, optional complement
dimming, and front order to point, bar, line/area-series, and rule items.
It is an ESM-only npm package for Node 20 or later with Browser Canvas, Node PNG, and TypeScript entries for `ggaction`, `ggaction/extension`, and `ggaction/png`.

Program composition supports concat, nested Cartesian/Polar snapshots, editing, replacement, and Cartesian facets. Polar facets, SVG, animation, and automatic compilation are unsupported.