Phase 7: conditional formatting (#129)

* Add conditional formatting: the simple cell rules

xl_cond_cell() covers the rules that pair a condition with a format --
comparisons, text matches, time periods, above/below average, top/bottom N,
duplicates, uniques, blanks, errors and arbitrary formulas -- reaching
worksheet_conditional_format_range(). xl_sheet(conditional =) takes one or a
list of them through the Phase 0 overlay stage.

The 34 criteria are partitioned by rule type and libxlsxwriter checks none of
the pairing, so a text criteria on a cell rule produces a file Excel accepts and
then silently ignores. .CONDITIONAL_CRITERIA_FOR maps each type to what it
accepts, and a mismatch is an error naming both the criteria and the type and
listing what would be valid there. Where the two are redundant the type is
inferred from the criteria instead.

The format is an ordinary xl_format, so it goes through the existing registry
unchanged -- but conditional formats are emitted as differential formats. That
was worth verifying rather than assuming: a rule's fill lands in <dxfs> in
styles.xml and the rule references it by dxfId, which a test now pins.

The API consistency gate added in the previous review caught this before it
shipped: xl_cond_cell() had criteria before type while xl_validation() has type
before criteria, and the two share six arguments. Reordered to match, since in
both functions the type is what determines which criteria are legal.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Add colour scales, data bars and icon sets

xl_cond_scale() writes two- and three-colour scales, xl_cond_bar() in-cell data
bars with control over the negative and border colours, axis and direction, and
xl_cond_icons() one of Excel's seventeen built-in icon sets. Each is a separate
constructor because the clusters share almost no fields; all four flow through
one overlay kind.

Corrects the conditional type table. Three of libxlsxwriter's type constants --
2_COLOR_SCALE, 3_COLOR_SCALE and DATA_BAR -- carry no TYPE_ in their names, so
an earlier reading of the header missed them and put icon_sets at 14 rather
than 17. That is the index of a two-colour scale, so every icon set would have
silently written a scale instead. The commit before this one only used indices
0 to 13 and was unaffected.

The corrected mapping is pinned by enumerating all seventeen styles against the
names Excel stores, which is the test that would have caught the original
error: 5_quarters must give 5Quarters, 4_ratings must give 4Rating, and so on.
A further test asserts the map still has seventeen entries, so a style added by
a libxlsxwriter update fails here rather than being quietly unreachable.

Icon sets embed nothing: Excel draws them itself, and a test asserts no xl/media
part appears.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: billdenney

NAMESPACE

@@ -8,6 +8,7 @@ S3method(format,xl_rich_string)
 S3method(length,xl_cell_general)
 S3method(print,xl_cell_general)
 S3method(print,xl_comment)
+S3method(print,xl_conditional)
 S3method(print,xl_format)
 S3method(print,xl_merge)
 S3method(print,xl_page_setup)
@@ -30,6 +31,10 @@ export(xl_cell_general)
 export(xl_col_spec)
 export(xl_color)
 export(xl_comment)
+export(xl_cond_bar)
+export(xl_cond_cell)
+export(xl_cond_icons)
+export(xl_cond_scale)
 export(xl_fill)
 export(xl_font)
 export(xl_format)

NEWS.md

@@ -40,6 +40,11 @@
   lists, numeric, date, time and text-length bounds, and custom formulas, with
   the input and error messages Excel shows (#43).
 
+* **Conditional formatting** via `xl_sheet(conditional = ...)`, in four
+  flavours: `xl_cond_cell()` for a rule paired with a format, `xl_cond_scale()`
+  for two- and three-colour scales, `xl_cond_bar()` for data bars and
+  `xl_cond_icons()` for Excel's built-in icon sets.
+
 * **Merged cells** via `xl_sheet(merge = xl_merge(...))`. A merged range holds
   one value, so `xl_merge()` carries its own text; merging over cells the data
   frame filled keeps only the merged text, as it does in Excel.

R/xl_conditional.R

@@ -155,6 +155,9 @@ xl_row_spec <- function(rows, height = NA, hidden = NA, level = NA,
 #' @param validation One [xl_validation()], or a list of them, restricting what
 #'   may be typed into a range --- a dropdown, a numeric or date bound, a text
 #'   length limit or a custom formula.
+#' @param conditional One conditional format ([xl_cond_cell()],
+#'   [xl_cond_scale()], [xl_cond_bar()], [xl_cond_icons()]), or a list of them,
+#'   formatting cells according to their contents.
 #' @return An `xl_sheet` object.
 #' @family writexl
 #' @seealso [xl_col_spec], [xl_row_spec], [write_xlsx]
@@ -174,7 +177,7 @@ xl_sheet <- function(data, cols = NULL, rows = NULL, freeze = NULL,
                      autofilter = FALSE, protect = FALSE,
                      comment_author = NA, show_comments = FALSE,
                      page = NULL, view = NULL, merge = NULL,
-                     validation = NULL) {
+                     validation = NULL, conditional = NULL) {
   if (!is.data.frame(data))
     stop("`data` must be a data frame", call. = FALSE)
   if (!is.logical(auto_colwidth) || length(auto_colwidth) != 1L || is.na(auto_colwidth))
@@ -204,7 +207,8 @@ xl_sheet <- function(data, cols = NULL, rows = NULL, freeze = NULL,
       page           = page,
       view           = view,
       merge          = merge,
-      validation     = validation
+      validation     = validation,
+      conditional    = conditional
     ),
     class = "xl_sheet"
   )
@@ -472,7 +476,8 @@ print.xl_sheet <- function(x, ...) {
   }
 
   merges <- .resolve_merges(el, df, reg, header_offset, props)
-  overlay <- c(overlay, .resolve_validations(el, df, header_offset))
+  overlay <- c(overlay, .resolve_validations(el, df, header_offset),
+              .resolve_conditionals(el, df, reg, header_offset, props))
 
   col_format_id <- vapply(col_fmt, function(f) .register_format(reg, f), integer(1))