xlsxrb 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7edcf69207f83781642d4628e25802bd9f25e6db4caac46c4419cc803c225d4c
-  data.tar.gz: 6af71208f72dd6f2b94f4127faca05bce3046cd40c5a1ca9c605935eac754bad
+  metadata.gz: '021999337251e5676fd32d18d0f9f4f6bfd1379a7ee0d7caf8e1a4dba0ba4188'
+  data.tar.gz: e0985f7acd53f4d4945f2ff05d06d6e59595e683297f2d4701040947536169cd
 SHA512:
-  metadata.gz: b52768fc57d885db35b14c793e451c99c60045d56e5dad8ff549108fd1b25c825b8ad49dfb98d70e8f17a4512542129aeec0d793f3ed1d148b5cbcd228493523
-  data.tar.gz: d701b2f511498b462377ab7dcfcbe3288f331bd5e3df2c1c25c9a326abee7e5b1c6b583973f9afb5359a8affd158a33350aee186c4949055ea4d711e5db1a5fc
+  metadata.gz: 1c5689e894d657a94af63b2805b2cf24010bfc1de01b5794661b34c30d7252040da2a506b188f1cf9f3849878cd07b3187f7755bc1daa653161faf69c88d2be0
+  data.tar.gz: cefcef0cad4c356681ef2e3634dcd785a88dfde02beaee0b517411d7c79b4088a58647a8f5c89323ced13dbd7fbc4157e76caf6a50b32b40539e3ae6a68a8cb5

data/CHANGELOG.md

@@ -1,5 +1,69 @@
 ## [Unreleased]
 
+## [0.1.17] - 2026-11-01
+
+### Added
+- Support threaded comments (`<ThreadedComments>`) and workbook person lists (`<personList>`) across `WorksheetBuilder`, `StreamWriter`, `WorksheetProxy`, `Ooxml::Writer`, `WorkbookWriter`, `DrawingXml`, `Elements::Worksheet`, `Elements::Cell`, `StreamSheet`, and `Ooxml::Reader`, serialize `xl/threadedComments/threadedComment{N}.xml` and `xl/persons/person.xml` conforming to the OpenXML threaded comments specification, support root comments and replies with `parent_id`, timestamps, and resolution states (`done`), register relationship types and content types, and provide query accessors across worksheets and cells.
+- Support combo charts and secondary value axes across `ChartBuilder`, `DrawingXml`, `Ooxml::Writer`, and `DrawingListeners`, allow mixed chart types (e.g. bar and line) inside a single plot area with primary and secondary value axes (`secondary_value_axis:`, `secondary_axis:`), support per-series axis binding via `SeriesBuilder#secondary_axis` and `SeriesBuilder#axis`, serialize distinct `<c:valAx>` elements with independent scaling, orientation, units, and gridlines conforming to ECMA-376 Part 4 §21.2 schema sequence, and expose secondary value axis configurations in `Ooxml::Reader`.
+- Support shared formula (`<f t="shared">`) serialization and reader expansion across `Xlsxrb.shared_formula`, `Xlsxrb.formula(..., shared_index:, si:)`, `WorksheetWriter`, `FeaturesXml`, `WorksheetParser`, and `WorksheetListener`, serialize master (`ref`, `si`) and follower (`si`) elements conforming to ECMA-376 Part 4 §18.3.1.40, and add `Xlsxrb::Utils.expand_formula` to expand relative cell references across shared formula ranges during SAX and streaming parsing.
+- Support table calculated columns (`calculatedColumnFormula`) and custom totals row formulas (`totalsRowFormula`) across `TableBuilder`, `DslHelpers.normalize_table_options`, `WorkbookWriter`, `Writer`, and `FeatureListeners`, add `TableBuilder#calculated_column` helper, support `formula:`, `data_formula:`, `totals_row_formula:`, `total_row_formula:`, and `total_formula:` aliases, automatically infer `totalsRowFunction="custom"` when a totals formula is provided without an explicit function, and expose `calculated_column_formula` and `data_formula` in reader output.
+- Support font text decoration attributes, including underline styles (`:single`, `:double`, `:single_accounting`, `:double_accounting`, `:none`) and vertical alignment (`:superscript`, `:subscript`, `:baseline`), with dedicated builder helpers (`superscript`, `subscript`, `vert_align`, `underline`) and option mappings across `StyleBuilder`, `WorkbookWriter`, `StylesXml`, `FeaturesXml`, `WorksheetWriter`, and `Ooxml::Reader`.
+- Support row and column grouping DSL (`group_rows`, `group_columns`, `group_row`, `group_column`, `group_cols`, `group_col`) and outline view properties (`outline_properties`, `outline_pr`) across `WorksheetBuilder`, `StreamWriter`, `WorksheetProxy`, `Elements::Worksheet`, `StreamSheet`, and `Ooxml::Reader`, emit schema-compliant `<outlinePr applyStyles="..." summaryBelow="..." summaryRight="..." showOutlineSymbols="..."/>` in `WorksheetWriter`, and emit `collapsed="1"` on `<col>` elements.
+- Enhance conditional formatting with statistical and relative rules (`above_average`, `top10`, `duplicate_values`, `unique_values`, `contains_blanks`, `not_contains_blanks`, `contains_errors`, `not_contains_errors`, `time_period`), add builder accessors (`above_average`, `equal_average`, `std_dev`, `rank`, `percent`, `bottom`, `text`, `time_period`) to `ConditionalFormatBuilder`, map symbol time periods (`:today`, `:last_7_days`, `:this_month`, etc.) to ECMA-376 `ST_TimePeriod` values, and automatically infer rule type from options.
+- Add `ConditionalFormatBuilder` supporting block configuration for conditional formatting across `WorksheetBuilder`, `StreamWriter`, `WorksheetProxy`, and `Ooxml::Writer`.
+- Add coordinate targeting (`columns:`, `rows:`, `col:`, `row:`, `except_rows:`) to `conditional_format` and `ConditionalFormatBuilder`, symmetrically resolving to `sqref`.
+- Enhance `color_scale` conditional formatting with automatic cfvo generation for 2-color (`min`/`max`) and 3-color (`min`/50%/`max`) scales, and auto-normalize 6-digit RGB hex colors to 8-digit ARGB.
+- Enhance `icon_set` conditional formatting with automatic cfvo percent distribution for 3, 4, and 5 icon sets, and support symbol icon set styles (`:three_arrows`, `:four_rating`, `:five_quarters`, etc.).
+- Enhance `table` and `TableBuilder` with `auto_filter:` option, boolean `total_row` / `totals_row` helpers, symbol column names, and symbol `totals_row_function` mappings (`:sum`, `:average`, `:count`, `:min`, `:max`, `:count_nums`, `:std_dev`, `:var`, `:custom`).
+- Add worksheet name sanitization utility via `Xlsxrb.sanitize_sheet_name` (aliased as `Xlsxrb.sheet_name` and `DslHelpers.sanitize_sheet_name`), sanitizing forbidden characters (`\`, `/`, `?`, `*`, `[`, `]`, `:`, control characters), replacing leading/trailing apostrophes, appending `replace_char` to the reserved `History` sheet name, and truncating names to 31 characters.
+- Add `sheet_names` to `StreamWriter`, `WorksheetProxy`, and `WorkbookBuilder` returning an array of worksheet names currently registered in the workbook.
+- Support `sheet.defined_name` symmetrically across `WorksheetBuilder`, `StreamWriter`, and `WorksheetProxy`, automatically quoting sheet names with single quote escaping and generating absolute `$` coordinate references.
+- Support `fill: { color: ... }` and `fill_color:` in conditional formatting rules and `extract_dxf_from_rule!`.
+- Support `size:` alongside `sz:` in conditional formatting differential formatting (`dxf`) fonts.
+- Support `base_font:` in `Xlsxrb.rich_text(*runs, base_font: ...)` to merge base font attributes across text runs.
+- Support `size:` alongside `sz:` in `RichTextRun`, inline rich text, and shared strings XML fonts.
+- Add coordinate-based targeting (`columns:`, `rows:`, `except_rows:`, `col:`, `row:`) to `validate_data` and `DataValidationBuilder` with interval run compression (`compress_runs`), complement calculation (`complement_runs`), and automatic chunking into multiple `<dataValidation>` entries when reference counts exceed 32,767 (`Xlsxrb::MAX_REFS_PER_VALIDATION`).
+- Expose spreadsheet dimension limits `Xlsxrb::MAX_ROW = 1_048_576`, `Xlsxrb::MAX_COL = 16_384`, and `Xlsxrb::MAX_REFS_PER_VALIDATION = 32_767`.
+- Support direct array in `validate_data(..., in: [...])` converting to `type: "list"` with quoted CSV `formula1`.
+- Automatically infer `show_input_message: true` when `prompt:` or `prompt_title:` is provided, infer `show_error_message: true` when `error:` or `error_title:` is provided, and convert multiline prompts and errors (`\r\n`, `\n`) to OOXML `ST_Xstring` format (`_x000a_`).
+- Support explicit `:default` / `:none` cell style identifier to emit `s="0"` and prevent unintended column style inheritance.
+- Merge duplicate `sheet.column` definitions on the same column index and sort by column index in in-memory and streaming modes.
+- Inherit `sheet_format[:default_col_width]` when a column defines `style:` without explicit `width:`.
+- Support sheet visibility states (`state:` `:visible`, `:hidden`, `:very_hidden`, and `hidden: true`) across `StreamWriter#sheet`, `WorksheetProxy`, and `WorkbookBuilder#sheet`, propagate state into streaming workbook XML, reject invalid state values with `ArgumentError`, and enforce that at least one visible worksheet exists in `strict_excel_mode`.
+- Add active sheet and workbook view configuration (`active_sheet`, `first_sheet`, `show_sheet_tabs`, `tab_ratio`, and `sheet(..., active: true)`) across `WorkbookBuilder`, `StreamWriter`, and `WorksheetProxy`, resolve active tab indices safely to avoid hidden sheet selection, emit `activeTab`, `firstSheet`, `showSheetTabs`, and `tabRatio` on `<workbookView>`, guarantee single `tabSelected="1"` emission on the active sheet, and expose `active_tab`, `active_sheet`, `first_sheet`, `show_sheet_tabs?`, and `tab_ratio` on `Elements::Workbook`.
+- Enhance worksheet tab color configuration (`tab_color`) across `WorksheetBuilder`, `StreamWriter`, and `WorksheetProxy` with support for RGB hex strings, theme colors, tint, indexed colors, and auto color, emit full `<tabColor>` attributes in `WorksheetWriter` and `Ooxml::Writer`, and expose `tab_color` readers on `Elements::Worksheet` and `StreamSheet`.
+- Support worksheet error check warning suppression rules (`<ignoredErrors>`) via `ignore_error` and `add_ignored_error` across `WorksheetBuilder`, `StreamWriter`, and `WorksheetProxy`, emit schema-compliant `<ignoredErrors>` elements in `WorksheetWriter`, and expose `ignored_errors` readers on `Elements::Worksheet` and `StreamSheet` with full round-trip preservation.
+- Support worksheet phonetic (furigana) guide properties (`<phoneticPr>`) via `phonetic_properties` (and alias `phonetic_pr`) across `WorksheetBuilder`, `StreamWriter`, and `WorksheetProxy`, emit schema-compliant `<phoneticPr>` elements in `WorksheetWriter` and `WorkbookWriter` in Part 4 schema sequence position, and expose `phonetic_properties` query readers on `Elements::Worksheet` and `StreamSheet` with full round-trip preservation.
+- Support workbook and worksheet code names (`code_name`), page setup fit-to-page linkage (`fit_to_page`, `fit_to_page?`), and worksheet calculation properties (`sheet_calc_pr`, `full_calc_on_load?`) across `WorkbookBuilder`, `WorksheetBuilder`, `StreamWriter`, and `WorksheetProxy`, emit schema-compliant `codeName` on `<workbookPr>` and `<sheetPr>`, emit `<pageSetUpPr fitToPage="1"/>` and `<sheetCalcPr fullCalcOnLoad="1"/>` in `WorksheetWriter` conforming to ECMA-376 Part 4 schema sequence, and expose query methods and properties on `Elements::Workbook`, `Elements::Worksheet`, and `StreamSheet` with full round-trip fidelity.
+- Support worksheet background image (`<picture r:id="..."/>`) via `background_image` (with aliases `background_picture`, `picture`, `background_image=`, `background_picture=`, `picture=`) across `WorksheetBuilder`, `StreamWriter`, and `WorksheetProxy`, serialize relationship in `xl/worksheets/_rels/sheet{N}.xml.rels` and binary media in `xl/media/sheet{N}_bg.{ext}`, register image extension in `[Content_Types].xml`, emit schema-compliant `<picture>` element in `WorksheetWriter` conforming to ECMA-376 Part 4 schema sequence, and expose `background_image` query readers on `Elements::Worksheet` and `StreamSheet` with full round-trip fidelity.
+- Add visual regression test example, Visual Gallery section, and WebAssembly Live Playground preset for worksheet views and advanced properties (`sheet_properties`).
+- Support hierarchical differential format Hash (`dxf: { font: ..., fill: ... }`) in `conditional_format` and `add_conditional_format` across `StreamWriter`, `WorksheetProxy`, `WorksheetBuilder`, and `Ooxml::Writer` with automatic deduplication, emit `<b val="0"/>`, `<i val="0"/>`, `<strike val="0"/>` on boolean `false` font properties, and support automatic/theme/tint font and background colors and `pattern: "none"` pattern fills.
+- Add `skip_rows` (and alias `skip_row`) to `StreamWriter`, `WorksheetProxy`, and `WorksheetBuilder` to advance the row cursor without writing empty `<row>` XML elements.
+- Support configurable workbook-wide default font (`default_font: { name:, size: }`, `default_font(name, size, **opts)`, `set_default_font`) across `StreamWriter`, `WorksheetProxy`, `WorkbookBuilder`, `Xlsxrb.write`, and `Xlsxrb.build`, serializing name, size, family, charset, and scheme onto the base font (font 0).
+- Support inline strings option (`shared_strings: false`) across `StreamWriter` and `Xlsxrb.write`, writing cells directly as `<c t="inlineStr"><is><t>...</t></is></c>` and omitting `xl/sharedStrings.xml` and package relationships to maintain flat $O(1)$ constant memory during streaming write.
+- Support configurable ZIP deflate compression level (`compression_level: 0..9`) across `StreamWriter`, `Ooxml::ZipWriter`, `Ooxml::WorkbookWriter`, and `Xlsxrb.write`, allowing performance tuning between compression speed (e.g. level 4 for 20-40% faster writes) and archive size.
+
+### Changed
+- Unify differential format extraction across `WorkbookWriter` and `StreamWriter` into centralized `DslHelpers.extract_dxf_from_rule!`.
+- Synchronize mutation testing metrics in `README.md`, `docs/MUTATION_TESTING.md`, and `docs/QUALITY_ASSURANCE.md` to reflect 51 pure functional subjects and 2,549 mutations at 100.00% kill rate.
+- Optimize `bin/pre-push` and test suite execution time:
+  - Scope mutation testing (`rake mutant:pure`) to subjects and test files matching changed files via `MUTANT_FILES` (running only affected pure logic subjects in ~2-20s rather than all 51 subjects), falling back to full coverage when `Rakefile` or `.mutant.yml` changes or when `--force` is passed, and suppressing parser future-frozen string warnings during mutation runs.
+  - Eliminate duplicate `rake sig` invocation in `bin/pre-push` (already invoked as a prerequisite of `rake typecheck`) and run unit and contract tests in a single `rake test` process rather than two separate test processes.
+  - Decouple serial RBS runtime type validation (`test:rbs`) from default local `bin/pre-push --all` (saving ~160s locally where static Steep type checking already ensures zero errors), while preserving automated runtime type validation on CI and allowing manual execution with `bin/pre-push --all --rbs` or `RUN_RBS=1`.
+  - Condition SimpleCov coverage profiling on `ENV["COVERAGE"] == "1"` or `ENV["CI"] == "true"`, eliminating 5-10s of instrumentation overhead during local test runs.
+  - Replace anonymous keyword argument forwarding (`**`) in `StreamWriter` and `WorksheetBuilder` with explicit `**opts` to prevent Steep 2.1.0 internal `RuntimeError` crashes during type synthesis.
+  - Update `bin/setup` to install `.git/hooks/pre-push` as a wrapper forwarding directly to `bin/pre-push --all`, ensuring `git push` runs extended diff-scoped mutation verification while staying synchronized with `bin/pre-push`.
+
+### Fixed
+- Guard `Ooxml::Writer#generate_table_xml` against `TypeError` when `tbl[:style]` is provided as a string, and resolve table style attributes (`show_first_column`, `show_last_column`, `show_row_stripes`, `show_column_stripes`) directly from table definition root.
+- Omit `<autoFilter>` tag from table XML when `auto_filter: false` is explicitly specified across `Ooxml::Writer` and `WorkbookWriter`.
+- Enforce strict Excel worksheet name rules in `StreamWriter#sheet`, `WorkbookBuilder#sheet`, and `Elements::Worksheet.valid_name?` / `validate`, rejecting colons (`:`), leading/trailing apostrophes (`'`), and the case-insensitive reserved name `History`, updating validation error messages to reference Excel constraints.
+- Guard against non-finite Float values (`Float::INFINITY`, `Float::NAN`, and non-finite cached formula values) in `StreamWriter#row` and `WorksheetWriter#write_row_values`, raising `ArgumentError` to prevent corrupt XML output.
+- Support `xsd:boolean` representations (`"true"`, `"false"`, `"1"`, `"0"`) across `StylesParser`, `StylesListener`, and column definitions in `WorksheetParser`.
+- Safely handle `nil` shared strings table index (`sst_index: nil`) across unstyled fast path and general cell paths in `WorksheetWriter#write_row_values`, writing string values as inline strings (`t="inlineStr"`) without error.
+- Include `test/ooxml/**/*_test.rb` in Rake test tasks and update custom number format assertions to use `Elements::Styles#num_fmt`.
+- Preserve formatted text runs (`<r><rPr>...</rPr><t>...</t></r>`) in inline strings (`<c t="inlineStr">`) for `Elements::RichText` cells across unstyled fast path and general row paths in `WorksheetWriter#write_row_values` when `shared_strings: false` is used.
+
 ## [0.1.16] - 2026-10-24
 
 ### Changed

data/README.md

@@ -40,7 +40,7 @@ Maintaining a gem that supports both reading and writing across streaming and in
 
 ### Autonomous Quality Assurance
 
-To maintain its multi-layered QA suite (Steep static typing, 100% mutation kill rate across 43 subjects, ECMA-376 XSD validation, and $O(1)$ streaming memory) without high manual maintenance overhead, xlsxrb defines remediation workflows for AI coding agents ([AGENTS.md](AGENTS.md), [docs/QA_AGENTS.md](docs/QA_AGENTS.md)).
+To maintain its multi-layered QA suite (Steep static typing, 100% mutation kill rate across 51 subjects, ECMA-376 XSD validation, and $O(1)$ streaming memory) without high manual maintenance overhead, xlsxrb defines remediation workflows for AI coding agents ([AGENTS.md](AGENTS.md), [docs/QA_AGENTS.md](docs/QA_AGENTS.md)).
 
 ## Installation
 
@@ -192,7 +192,7 @@ Verified by a multi-layered QA architecture:
 * Microsoft Open XML SDK Validation: Validates generated OOXML structures against Microsoft's official SDK.
 * Visual Regression Testing (VRT): Headless LibreOffice Calc pixel-by-pixel rendering checks.
 * Contract & Round-Trip Tests: Verifies parity between Streaming and In-Memory APIs and round-trip read/write accuracy.
-* Mutation Testing (Mutant): 100% mutant kill rate (1,528/1,528 mutations across 43 subjects) on pure algorithms, predicates, and coordinates ([docs/MUTATION_TESTING.md](docs/MUTATION_TESTING.md)).
+* Mutation Testing (Mutant): 100% mutant kill rate (2,549/2,549 mutations across 51 subjects) on pure algorithms, predicates, and coordinates ([docs/MUTATION_TESTING.md](docs/MUTATION_TESTING.md)).
 * Security & DoS Protection: Formula injection mitigation and ZIP bomb protection.
 
 For full architectural details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md).

data/lib/xlsxrb/chart_builder.rb

@@ -184,6 +184,18 @@ module Xlsxrb
       @options[:value_axis] = kwargs.empty? ? args.first : kwargs
     end
 
+    # Configures the secondary value axis properties for combo charts.
+    #
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @return [Object]
+    # @api public
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
+    def secondary_value_axis(*args, **kwargs)
+      @options[:secondary_value_axis] = kwargs.empty? ? args.first : kwargs
+    end
+    alias secondary_axis secondary_value_axis
+
     # Configures whether to show the legend key in data labels.
     #
     # @param args [Array] Positional arguments.
@@ -322,12 +334,39 @@ module Xlsxrb
       #
       # @param args [Array] Positional arguments.
       # @param kwargs [Hash] Keyword arguments.
-      # @return [String]
+      # @return [Symbol, String, Hash, nil]
       # @api public
-      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
+      #: (*(String | Symbol) args, **String | Numeric | bool | nil kwargs) -> (String | Symbol | Hash[Symbol, untyped] | nil)
       def type(*args, **kwargs)
         @options[:type] = kwargs.empty? ? args.first : kwargs
       end
+
+      # Configures whether this series uses the secondary value axis.
+      #
+      # @param args [Array] Positional arguments.
+      # @param kwargs [Hash] Keyword arguments.
+      # @return [Boolean, Hash]
+      # @api public
+      #: (*bool args, **bool kwargs) -> (bool | Hash[Symbol, bool])
+      def secondary_axis(*args, **kwargs)
+        @options[:secondary_axis] = if kwargs.empty?
+                                      args.empty? || args.first
+                                    else
+                                      kwargs
+                                    end
+      end
+
+      # Configures the axis (:primary or :secondary) for this series.
+      #
+      # @param value [Symbol, String]
+      # @return [Symbol, String]
+      # @api public
+      #: (Symbol | String value) -> (Symbol | String)
+      def axis(value)
+        @options[:axis] = value
+        @options[:secondary_axis] = (value.to_s == "secondary")
+        value
+      end
     end
   end
 end