x/yord type-level args and various other categorical var improvements

[grantmcdermott]

Closes #693
Closes #692
Closes #691 (and towards #441; only layering on top of the dodged/group violin case remains AFAICT)
Closes #690
Closes #689
Closes #645

(Follow-up to #688, #683)

This PR started life as a way to introduce the (type-level) args xord/yord as motivated in #693. In short, these provide convenience alternatives (keyword/function-based) to the literal x/ylevels args for reordering categorical variables. They are also consistent with the byord argument that I introduced for stacked area plots in #683.

However, in so doing, I ended up refactoring and consolidating quite a few issues related to how we order+label categorical variables. I also identified and squished a couple of bugs along the way.

All told, I'm confident that this refactoring provides a more consistent API and experience, as well as more fine-grained control for categorical variables... whether that be along the x, y, or by.

Some quick examples:

pkgload::load_all("~/Documents/Projects/tinyplot/")
#> ℹ Loading tinyplot
#693 (with application targeting #645)
plt(extra ~ ID, data = sleep, type = type_barplot(xord = "descending"))

#692 and #690
dict = c(setosa = "SET", versicolor = "vErSiCoLoR", virginica = "Hello!")
plt(Species ~ Sepal.Length, data = iris, type = "spineplot", yaxl = dict)

#691
plt(demand ~ Time, data = BOD, type = "barplot")
plt_add(type = "text", pos = 3, xpd = NA)

#441
plt(len ~ dose, data = ToothGrowth, type = "violin")
plt_add(type = type_summary(median, type = "p"))

^{Created on 2026-08-29 with reprex v2.1.1}

[Copilot]

🟡 Changes recommended

Exported constructor argument reordering breaks positional callers, and several new validation and facet-dictionary paths are incorrect.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds consistent ordering and relabelling controls for categorical variables while fixing related axis formatting and layer alignment issues.

Changes:

• Introduces type-level xord/yord ordering.
• Adds dictionary-based label replacement and deprecates type-specific axis labels.
• Fixes categorical layer alignment, precision formatting, and flipped legends.

File summaries

File	Description
R/type_barplot.R	Adds ordering, deprecation, and examples.
R/type_text.R	Documents dictionary labellers.
R/type_spineplot.R	Adds ordering and axis labelling.
R/type_ridge.R	Adds ridge ordering and labels.
R/type_ribbon.R	Updates stacking-order documentation.
R/type_points.R	Adds categorical x ordering.
R/type_pointrange.R	Migrates default ordering to xord.
R/type_lines.R	Adds categorical x ordering.
R/type_errorbar.R	Exposes the new ordering API.
R/tpar.R	Documents facet dictionaries.
R/tinyplot.R	Updates labels and flipped legends.
R/tinyplot.matrix.R	Expands matrix examples.
R/tinylabel.R	Implements dictionary labels and precision fixes.
R/sanitize_xlevels.R	Validates literal level selections.
R/sanitize_ord.R	Implements derived ordering.
R/ordering_args.R	Adds shared ordering guards.
R/legend.R	Documents dictionary labellers.
R/align_layer.R	Aligns categorical added layers.
NEWS.md	Announces categorical improvements.
man/type_text.Rd	Updates text-type documentation.
man/type_spineplot.Rd	Documents spine ordering.
man/type_ridge.Rd	Documents ridge ordering.
man/type_ribbon.Rd	Updates stacking documentation.
man/type_points.Rd	Documents point ordering.
man/type_lines.Rd	Documents line ordering.
man/type_errorbar.Rd	Documents error-bar ordering.
man/type_barplot.Rd	Documents bar ordering and examples.
man/tpar.Rd	Documents facet dictionaries.
man/tinyplot.Rd	Documents dictionary axis labels.
man/tinyplot.matrix.Rd	Adds matrix barplot examples.
man/tinylabel.Rd	Documents dictionary relabelling.
man/tinyAxis.Rd	Documents axis dictionaries.
man/draw_legend.Rd	Updates legend labeller forms.
man/build_legend_env.Rd	Updates legend environment docs.
man/build_legend_args.Rd	Updates legend argument docs.
inst/tinytest/test-type_spineplot.R	Tests spine ordering and labels.
inst/tinytest/test-type_ridge.R	Tests ridge ordering and labels.
inst/tinytest/test-type_points.R	Tests point ordering.
inst/tinytest/test-type_pointrange.R	Tests default-order warnings.
inst/tinytest/test-type_lines.R	Tests line ordering.
inst/tinytest/test-type_barplot.R	Tests bar ordering and labels.
inst/tinytest/test-type_area.R	Tests stack ordering and flipping.
inst/tinytest/test-tinyplot_add.R	Tests numeric category alignment.
inst/tinytest/test-tinylabel.R	Tests dictionaries and precision.
inst/tinytest/_tinysnapshot/tinyplot_add_numeric_x_barplot.svg	Captures aligned bar labels.
inst/tinytest/_tinysnapshot/tinylabel_center_percent.svg	Captures corrected percentages.
inst/tinytest/_tinysnapshot/spineplot_yord_rev.svg	Captures reversed spine y order.
inst/tinytest/_tinysnapshot/spineplot_xord_desc.svg	Captures frequency ordering.
inst/tinytest/_tinysnapshot/spineplot_xaxl_toupper.svg	Captures spine relabelling.
inst/tinytest/_tinysnapshot/points_xord_rev.svg	Captures reversed point categories.
inst/tinytest/_tinysnapshot/points_xord_desc.svg	Captures ranked point categories.
inst/tinytest/_tinysnapshot/lines_xord_rev.svg	Captures reversed line categories.
inst/tinytest/_tinysnapshot/barplot_xord_rev.svg	Captures reversed bars.
inst/tinytest/_tinysnapshot/barplot_xord_desc.svg	Captures descending bars.
inst/tinytest/_tinysnapshot/barplot_xord_asis.svg	Captures appearance ordering.
inst/tinytest/_tinysnapshot/barplot_xord_ascending.svg	Captures ascending bars.
inst/tinytest/_tinysnapshot/barplot_xord_aggregated_sum.svg	Captures sum-based ordering.
inst/tinytest/_tinysnapshot/barplot_xord_aggregated_mean.svg	Captures mean-based ordering.
inst/tinytest/_tinysnapshot/barplot_xaxl_dict.svg	Captures dictionary labels.
inst/tinytest/_tinysnapshot/area_stack_flip.svg	Updates flipped stack legend.
inst/tinytest/_tinysnapshot/area_stack_byord_desc.svg	Captures descending stacks.
inst/tinytest/_tinysnapshot/area_stack_byord_asc.svg	Captures ascending stacks.
altdoc/pkgdown.yml	Refreshes generated-site metadata.

Review details

Suppressed comments (1)

R/type_barplot.R:156

• Correct the spelling of “already.”

#' # Fancy frequency table (y = frequency aleady computed)

• Files reviewed: 45/71 changed files
• Comments generated: 13
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.