Phase 5: merged cells (#125)

* Add sheet tab state with cross-sheet validation

xl_sheet() gains active, selected, visible and first_tab, reaching
worksheet_activate, worksheet_select, worksheet_hide and
worksheet_set_first_sheet.

These are the first worksheet settings whose rules span the whole workbook, so
unlike everything else in the sheet plan they cannot be checked one sheet at a
time. Excel requires that a hidden sheet is neither active nor selected, that
at most one sheet is active, that the first sheet is not hidden unless another
is made active, and that at least one sheet stays visible. libxlsxwriter
enforces none of them -- hide, activate and select all return void and simply
set a flag -- so a bad combination would produce a workbook Excel cannot open,
with no diagnostic.

.resolve_sheet_visibility() checks all four rules in write_xlsx(), where every
sheet is in scope, and names the sheet at fault. Plain data frames carry no tab
settings and are treated as unset throughout.

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

* Add hide_zero, right_to_left, selection and top_left

xl_sheet() gains four more view settings, reaching worksheet_hide_zero,
worksheet_right_to_left, worksheet_set_selection and
worksheet_set_top_left_cell. selection and top_left go through the shared range
resolver, so they take an Excel reference or a list(rows =, cols =) spec like
every other range argument.

Excel encodes which cell of a selection is active by the order its corners are
given, so worksheet_set_selection(6, 6, 3, 3) means "G7 to D4". writexl does
not expose that: the shared resolver rejects an inverted range, which is right
for every other caller, and one strict range parser is worth more than a niche
capability. The active cell is therefore always the range's top-left corner,
which is documented and covered by a test that pins the error.

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

* Add split panes, converting from a cell reference

worksheet_split_panes() does not take a row and a column. Both arguments are
distances, in the units Excel uses for row height and column width, and the two
units differ from each other -- 15 means one default row, 8.43 one default
column. Passing 1 for "one row" would put the split a fifteenth of the way down
the first row, silently.

xl_sheet(split =) therefore takes a cell reference, as freeze does, and
converts: the distance above the split is the summed height of the rows before
it, the distance to its left the summed width of the columns before it. The
sums use the sheet's real geometry -- header row height, xl_row_spec() heights,
xl_col_spec() widths and auto_colwidth results -- so a split lands where it was
asked for on a sheet whose rows or columns have been resized, rather than only
on a default one. Tests pin that sensitivity in both directions.

list(vertical =, horizontal =) still accepts the raw units. split and freeze
together is an error, since Excel supports one or the other.

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

* Document sheet view and navigation in the vignette and NEWS

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

* Add merged cells

xl_merge() merges a rectangle of cells into one; xl_sheet(merge =) takes one or
a list of them.

worksheet_merge_range() does more than record the merge: it writes the top-left
cell's text itself and blanks the rest of the range with the same format. So a
merge carries its own text rather than reusing whatever the data frame put
there, and it also settles when merges run. They are applied after the sheet's
rows, which makes a merge over filled cells keep only the merged value --
exactly what merging does in Excel. Applying them first would instead have the
row loop overwrite the merge's own blanks.

Writing back over emitted rows is not possible while libxlsxwriter streams rows
to disk, so any merge turns constant memory off. This is the second real
trigger for the resolver added in Phase 0.

Excel has no single-cell merge and libxlsxwriter returns a bare
parameter-validation error for one, so that case is caught in R where the
message can name the merge.

Note this contradicts the roadmap's stated reason for needing the memory flip:
worksheet_merge_range() has no optimize guard and streams correctly on its own.
The flip is needed because of when writexl applies merges, not because merging
cannot stream.

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

---------

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

Author: billdenney

NAMESPACE

@@ -9,6 +9,7 @@ S3method(length,xl_cell_general)
 S3method(print,xl_cell_general)
 S3method(print,xl_comment)
 S3method(print,xl_format)
+S3method(print,xl_merge)
 S3method(print,xl_page_setup)
 S3method(print,xl_properties)
 S3method(print,xl_rich_run)
@@ -33,6 +34,7 @@ export(xl_format)
 export(xl_formula)
 export(xl_hyperlink)
 export(xl_hyperlink_cell)
+export(xl_merge)
 export(xl_num_format)
 export(xl_page_setup)
 export(xl_properties)

NEWS.md

@@ -36,6 +36,10 @@
   sheet, no hidden-and-active sheet, at least one visible sheet) are checked
   before writing, naming the sheet at fault.
 
+* **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.
+
 * `xl_properties(hyperlink_format = NULL)` writes hyperlinks with no styling at
   all, which was previously impossible.
 

R/write_xlsx.R

@@ -68,7 +68,7 @@ write_xlsx <- function(x, path = tempfile(fileext = ".xlsx"), col_names = TRUE,
                 header_offset = header_offset)
   sheets <- Map(function(el, df) .resolve_sheet_plan(el, df, reg, header_offset, props),
                 elems, dfs)
-  cm <- .resolve_constant_memory(dfs, props)
+  cm <- .resolve_constant_memory(dfs, props, sheets)
   ret <- .Call(C_write_data_frame_list, dfs, path, col_names, format_headers,
                use_zip64, reg$table, sheets, header_id,
                .properties_payload(props, cm$on))

R/xl_merge.R

@@ -0,0 +1,96 @@
+# =============================================================================
+# Merged cells
+# =============================================================================
+#
+# worksheet_merge_range() does more than record a merge: it writes the top-left
+# cell's text itself and blanks the rest of the range with the same format.  A
+# merge therefore carries its own content, which is why xl_merge() takes `text`
+# rather than reusing whatever the data frame put there.
+#
+# That also settles when merges are applied.  They run *after* the sheet's rows
+# have been written, so a merge over cells the data frame filled discards all
+# but the top-left value -- which is exactly what merging does in Excel.
+# Applying them before the rows would instead have the row loop overwrite the
+# merge's own blanks.
+#
+# Writing to already-written rows is not possible while libxlsxwriter is
+# streaming rows to disk, so any merge turns constant memory off; see
+# .resolve_constant_memory().
+# -----------------------------------------------------------------------------
+
+#' Merge a range of cells
+#'
+#' @description
+#' `xl_merge()` merges a rectangle of cells into one, as Excel's "Merge and
+#' Centre" does.  Pass one or a list of them as `xl_sheet(merge = )`.
+#'
+#' A merged range holds a single value, so `xl_merge()` carries its own `text`
+#' rather than taking it from the data frame.  Merging over cells the data frame
+#' filled keeps only the merged text, exactly as merging in Excel discards
+#' everything but the top-left value.
+#'
+#' @param range The cells to merge: an Excel range string such as `"A1:C1"`, or
+#'   a `list(rows = , cols = )` spec.  It must cover more than one cell ---
+#'   Excel has no single-cell merge.
+#' @param text The text shown in the merged cell.  `NULL` leaves it empty.
+#' @param format An optional [xl_format] applied to the whole merged range.
+#'   Merged cells usually want `xl_align(horizontal = "center")`.
+#' @return An `xl_merge` object.
+#' @family writexl
+#' @seealso [xl_sheet], [xl_format]
+#' @export
+#' @examples
+#' xl_merge("A1:C1", "Quarterly results",
+#'          format = xl_align(horizontal = "center") + xl_font(bold = TRUE))
+#'
+#' df <- data.frame(a = 1:3, b = 4:6)
+#' sheet <- xl_sheet(df, merge = xl_merge("A5:B5", "Total",
+#'                                        format = xl_font(bold = TRUE)))
+#' tmp <- write_xlsx(list(Data = sheet))
+xl_merge <- function(range, text = NULL, format = NULL) {
+  if (missing(range) || is.null(range))
+    stop("`range` must name the cells to merge", call. = FALSE)
+  if (!is.null(text) &&
+      (!is.character(text) || length(text) != 1L || is.na(text)))
+    stop("`text` must be a single non-NA string, or NULL", call. = FALSE)
+  if (!is.null(format) && !is_xl_format(format))
+    stop("`format` must be an xl_format object", call. = FALSE)
+  structure(list(range = range, text = text, format = format),
+            class = "xl_merge")
+}
+
+#' @export
+print.xl_merge <- function(x, ...) {
+  cat(sprintf("<xl_merge: %s%s>\n",
+              if (is.character(x$range)) x$range else "<spec>",
+              if (is.null(x$text)) "" else sprintf(" %s",
+                                                   encodeString(x$text, quote = '"'))))
+  invisible(x)
+}
+
+# Resolve a sheet's merges to the payloads C applies, registering each format.
+.resolve_merges <- function(el, df, reg, header_offset, props) {
+  if (!inherits(el, "xl_sheet") || is.null(el$merge)) return(list())
+  ms <- if (inherits(el$merge, "xl_merge")) list(el$merge) else el$merge
+  if (!is.list(ms))
+    stop("`merge` must be an xl_merge object or a list of them", call. = FALSE)
+  lapply(seq_along(ms), function(i) {
+    m <- ms[[i]]
+    if (!inherits(m, "xl_merge"))
+      stop(sprintf("`merge[[%d]]` must be an xl_merge object", i), call. = FALSE)
+    arg <- sprintf("merge[[%d]] range", i)
+    q <- .xl_resolve_range(m$range, arg = arg, df = df,
+                           header_offset = header_offset, allow_cell = FALSE)
+    # libxlsxwriter refuses a single-cell merge, and so does Excel; catch it
+    # here so the message names the merge rather than coming back as a bare
+    # parameter-validation error
+    if (q[1L] == q[3L] && q[2L] == q[4L])
+      stop(sprintf("`%s` covers a single cell; a merge needs more than one",
+                   arg), call. = FALSE)
+    list(kind = "merge", range = as.integer(q),
+         text = if (is.null(m$text)) NA_character_ else m$text,
+         format_id = .register_format(reg,
+                                      merge_xl_format(props$default_format,
+                                                      m$format)))
+  })
+}

R/xl_sheet.R

@@ -162,6 +162,11 @@ xl_row_spec <- function(rows, height = NA, hidden = NA, level = NA,
 #'   the shared range parser, which rejects an inverted range.
 #' @param top_left The cell scrolled to the top-left of the window when the
 #'   sheet opens, as an Excel reference such as `"A5"`.
+#' @param merge One [xl_merge()], or a list of them, merging rectangles of cells
+#'   into single cells.  Merges are applied after the sheet's rows are written,
+#'   so a merge over cells the data frame filled keeps only the merged text ---
+#'   as merging in Excel does.  Any merge turns off the memory-efficient
+#'   row-streaming mode, since it writes back over rows already emitted.
 #' @param split Split the sheet into scrollable panes with a visible, movable
 #'   divider, given as the cell reference the split sits above and to the left
 #'   of --- `"B3"` splits above row 3 and left of column B.  Mutually exclusive
@@ -200,7 +205,8 @@ xl_sheet <- function(data, cols = NULL, rows = NULL, freeze = NULL,
                      comment_author = NA, show_comments = FALSE,
                      page = NULL, active = NA, selected = NA, visible = NA,
                      first_tab = NA, hide_zero = NA, right_to_left = NA,
-                     selection = NULL, top_left = NULL, split = NULL) {
+                     selection = NULL, top_left = NULL, split = NULL,
+                     merge = 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))
@@ -236,7 +242,8 @@ xl_sheet <- function(data, cols = NULL, rows = NULL, freeze = NULL,
       right_to_left  = .val_flag(right_to_left, "right_to_left"),
       selection      = selection,
       top_left       = top_left,
-      split          = split
+      split          = split,
+      merge          = merge
     ),
     class = "xl_sheet"
   )
@@ -500,6 +507,8 @@ print.xl_sheet <- function(x, ...) {
                                  col_width)
   }
 
+  merges <- .resolve_merges(el, df, reg, header_offset, props)
+
   col_format_id <- vapply(col_fmt, function(f) .register_format(reg, f), integer(1))
 
   list(
@@ -515,6 +524,7 @@ print.xl_sheet <- function(x, ...) {
     comment_author = as.character(comment_author),
     show_comments = as.integer(show_comments),
     page = page_payload,
-    view = if (length(view)) view else NULL
+    view = if (length(view)) view else NULL,
+    merges = if (length(merges)) merges else NULL
   )
 }

R/xl_workbook.R

@@ -188,18 +188,26 @@ print.xl_workbook <- function(x, ...) {
 # Resolve the constant-memory flag for a workbook, from the sheets it is about
 # to write.  Returns the C-side integer flag plus the reasons (if any) the mode
 # had to be turned off.
-.resolve_constant_memory <- function(dfs, props) {
+.resolve_constant_memory <- function(dfs, props, sheets = NULL) {
   reasons <- character(0)
   # A multi-cell array formula range is padded by libxlsxwriter, and it skips
   # that padding entirely when row streaming is on -- silently, returning
   # success -- so the range would be left half-written.  Collected per sheet by
   # .resolve_sheet_formats().
   n_array <- sum(vapply(dfs, function(df)
     length(attr(df, "writexl_array_multicell")), integer(1)))
+  n_merge <- if (is.null(sheets)) 0L else
+    sum(vapply(sheets, function(s) length(s$merges), integer(1)))
   if (n_array > 0L)
     reasons <- c(reasons, sprintf(
       paste0("%d multi-cell array formula range(s): libxlsxwriter only pads an ",
              "array range when row streaming is off"), n_array))
+  # Merges are applied after the sheet's rows so that Excel's own semantics
+  # hold, which means writing back over rows already flushed to disk.
+  if (n_merge > 0L)
+    reasons <- c(reasons, sprintf(
+      paste0("%d merged range(s): merges are applied after the rows are ",
+             "written, which row streaming does not allow"), n_merge))
   list(on = as.integer(!length(reasons)), reasons = reasons)
 }