# gradbars v0.0.3

Prepared on 2026-10-03. This is release text for review; it does not create a GitHub release or tag.

## Highlights

This version extends cell-level comparisons and compositions with `\graddumbbell`,
signed `\gradstack`, and `\gradspark`. Target and interval quality rules preserve raw
geometry. Four group palettes and named category mappings keep color and texture
consistent across reordered tables and shared legends.

## Examples

```latex
\graddumbbell[compare label=delta]{58}{76}
\gradstack[min=-60,stack totals=separate]{60,-25,20,-15}
\gradspark[spark range=fixed,max=100]{25,45,NA,60,80}
\gradbar[better=interval,quality range={40,60},thresholds={0,10}]{68}
\gradbarscategory{Compute}{gradbarsBlue}{diagonal}
```

## Compatibility and semantics

- Existing v0.0.2 commands remain available; positive-only stacks retain their prior geometry and percentages.
- Negative stack segments now work with an explicit negative `min`. Positive and negative totals are checked independently against the range. The net label is not the visual extent.
- Signed segment percentages use absolute contribution / total absolute contribution. They do not use a potentially zero net balance.
- `better=target|interval` interprets thresholds as distances, with inclusive upper boundaries. Existing `higher|lower` behavior is unchanged.
- Sparklines use equally spaced observations. Missing values break connections; automatic row ranges should not be used for cross-row magnitude comparisons.
- `palette=mono` uses gray category colors but preserves registered category patterns.

## Documentation

The Chinese manual now has six parts and 56 numbered examples, including three new
complete tables: before/after evaluation, a monochrome contribution ledger and a monthly
trend summary. Source and result stay in one document. Both READMEs and the API reference are updated.

## Release artifacts

Publish `gradbars.sty`, the documentation sources and the generated
`gradbars-manual-v0.0.3.pdf` after running the documented build. Both Chinese and English PDFs are included and can be rebuilt with
`python scripts/build_manual.py`.
The package is tested with pdfLaTeX, XeLaTeX and LuaLaTeX. The Chinese manual uses XeLaTeX; the English manual uses pdfLaTeX. Text files use LF line endings. License: MIT.