xlsxrb 0.1.12 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a818d0e9e58b9ada1a11c90db9f9baa55fc76b3a7e62303d33a61f2e6f9896
-  data.tar.gz: c7b5f4af516d9911a1ee37ef5413939e8425bc270304900132e0962fad18905d
+  metadata.gz: 476e6f6e689eb65fecbbda4b81592c124b50f16fff0bbc9fec027a1f55ed4454
+  data.tar.gz: 8364dc6bff9b5f9601dc4cb375ef27b0456b7f88e721b2b52d1db7ba342c7de5
 SHA512:
-  metadata.gz: 9deec47109a21a62aafb4a93efcee64f61f5ffb4566fd009cd1d5fdb9557e1193a53155d60ff7e4cc565317d49fb4ce8b3b89542234dff6a900981cd9220d14a
-  data.tar.gz: b536ef03e3ae01c49ff8e00c693d86fb72a9248cae1ccf93802962127d9b86ef676b5b17ca4b896613961bab8869139644e439542b1bca5adb6a7452d971f124
+  metadata.gz: 31f365a17ad3f5976033ddc7a9220c5606c6d8f6acfca356ef1b3404cd1ed6d1f86d2c86d57a5e27daf15a46bea3d1c193f4fb60662b2eccbc7078fe41777bbb
+  data.tar.gz: 67fe19a961f2bb204d19e5b9a49ade2c01e48de7d6a09ac1c87f7c591b570c0ba64494b43ce59d3ea492a70e18cf967d775af4fb55623287ab6b7b648bb0843c

data/CHANGELOG.md

@@ -1,20 +1,94 @@
+## [Unreleased]
+
+## [0.1.14] - 2026-10-10
+
+### Added
+- Non-self-closing `<sheet>` and `<xf>` tag compatibility: Verify and support spreadsheet XML where `<sheet>...</sheet>` in `workbook.xml` or `<xf>...</xf>` in `styles.xml` are serialized with explicit closing tags rather than self-closing syntax.
+- Namespace prefix resilience for relationship and embed attributes: Match relationship and embed attributes by local name or any namespace prefix (`r:id`, `d3p1:id`, `rel:id`, `id`, `r:embed`, `embed`) across `WorkbookListener`, `HyperlinksListener`, `DrawingListener`, and `WorksheetParser`, ensuring reliable sheet, hyperlink, and media resolution for non-standard XML generators.
+- UTF-16LE, UTF-16BE, and UTF-8 BOM encoding normalization in `ZipReader`: Automatically detect and transcode Byte Order Mark (BOM) encoded XML streams (`\xFF\xFE`, `\xFE\xFF`, and `\xEF\xBB\xBF`) to UTF-8 in `ZipReader#read_entry` and `EntryStreamIO`, enabling seamless parsing of workbooks generated on Windows Phone and legacy platforms.
+- XML 1.0 line ending normalization (`\r\n` and `\r` to `\n`): Normalize line breaks in shared strings, inline strings, and cell text values per W3C XML 1.0 §2.11 across `SharedStringsParser` and `WorksheetParser`.
+- Whitespace and newline tolerance in cell regex scanning: Allow whitespace and newline sequences between `<c>` child tags (`<f>`, `<v>`, `<is>`) and strip whitespace on extracted values in `WorksheetParser`, ensuring reliable parsing of pretty-printed or formatted worksheet XML.
+- Sequential row index fallback for omitted `r` attributes: Track previous row index and fall back to sequential 1-based indexing when `<row>` elements omit the `r` attribute per ECMA-376 Part 1 §18.3.1.73 across direct string scanning, chunked stream scanning, and event scanning in `WorksheetParser`.
+- Case-insensitive part name lookup in `ZipReader`: Fall back to case-insensitive lookup for package part entries per ECMA-376 Part 2 §8.1.1, allowing workbooks with case-varying part names (such as lower-case `xl/sharedstrings.xml` or `xl/styles.xml`) to resolve transparently.
+- Windows backslash path separator normalization in `ZipReader`: Normalize Windows backslash separators (`\`) in ZIP central directory and local headers to standard forward slashes (`/`), enabling transparent extraction and catalog lookup for XLSX archives generated on Windows.
+- First-class sparkline groups on worksheet and `add_sparkline` helper: Expose `sparkline_groups` reader and keyword argument on `Elements::Worksheet`, propagate `ws.sparkline_groups` during `Xlsxrb.write` DOM serialization, and add `add_sparkline(location:, range:, type:, **opts)` helper to `WorksheetBuilder`, `StreamWriter`, and `StreamWriter::SheetContext` supporting `:win_loss` mapping to `"stacked"`.
+- High-level print area and print titles DSL: Add `print_area`, `print_titles`, `repeat_rows`, and `repeat_columns` to `WorksheetBuilder`, `StreamWriter::SheetContext`, and `StreamWriter`, expose `print_area` and `print_titles` on `Elements::Worksheet`, and auto-generate `_xlnm.Print_Area` and `_xlnm.Print_Titles` defined names in `WorkbookBuilder#build` and `Xlsxrb.write` DOM export.
+- ECMA-376 indexed color palette and `Xlsxrb::Colors`: Add `Xlsxrb::Colors` providing `INDEXED_COLORS` (indices 0..63 per ECMA-376 Part 4 §18.8.27), `palette_color`, and `to_hex` utilities, expose `Xlsxrb.palette_color` and `Xlsxrb.to_hex_color` facade methods, and resolve integer palette indices 0..63 automatically in `StyleBuilder.resolve_color`.
+- Flexible rich text run input in `Xlsxrb.rich_text`: Support `[text, font_hash]` pair arrays, alternating varargs of plain strings and format hashes or objects responding to `to_font_hash`, and mixed `Elements::RichTextRun` instances.
+- First-class `Elements::Hyperlink`, `Xlsxrb.hyperlink`, and `Cell#tooltip`: Add `Elements::Hyperlink` data class and `Xlsxrb.hyperlink` factory helper with `tooltip:` support, expose `Cell#tooltip` and `:tooltip`, `:url` symbol key access on `Elements::Cell`, and support `Elements::Hyperlink` instances in `WorksheetBuilder#hyperlink`, `StreamWriter#hyperlink`, and `Ooxml::Writer#hyperlink`.
+- Array and dynamic array formula serialization and `Xlsxrb.array_formula`: Add `Xlsxrb.array_formula(expression, ref, cached_value:)` factory method, extend `Xlsxrb.formula` with optional `type:` and `ref:` keywords, and serialize `<f t="array" ref="...">` and shared formula attributes across all `WorksheetWriter` serialization paths.
+- First-class `style_index:` keyword on `Elements::Column`: Add `style_index:` keyword argument directly to `Elements::Column.new`, storing it in `Data.define` attributes and populating it from `rc[:style_index]` during worksheet parsing and DSL column definitions.
+- In-memory streaming write and row append chaining: Support `Xlsxrb.write` with omitted target in block mode to return an in-memory binary String, support self-returning `<<` row appending for chaining across `StreamWriter`, `SheetContext`, and `WorksheetBuilder`, and add `add_row` aliases.
+- Unified color and border style normalizers in `StyleBuilder`: Add `StyleBuilder.normalize_color` (supporting 140+ CSS named colors, `#RGB`, `#RRGGBB`, `#AARRGGBB` hex strings, numeric RGB integers, and optional alpha channel) and `StyleBuilder.normalize_border_style` (supporting border style symbols, aliases, strings, and 0..13 numeric border indices).
+- Public date and time serial conversion utilities: Expose `date_to_serial`, `serial_to_date`, `datetime_to_serial`, and `serial_to_time` (aliased `serial_to_datetime`) on `Xlsxrb` and `Xlsxrb::Utils` for converting Ruby `Date` and `Time` instances to and from Excel 1900 and 1904 serial numbers.
+- Cascade style inheritance and column styles: Support cascade style inheritance (Cell Style > Row Style > Column Style) in `WorksheetWriter`, and add `style:` parameter to `StreamWriter#column` and `WorksheetBuilder#column`.
+- Embedded drawing and image extraction: Add `Elements::Image` representing anchored embedded images, expose `images`, `images_at`, and `with_images` across `StreamSheet` and `Elements::Worksheet`, and expose `images` and `images_at` across `Elements::Workbook`.
+- Configurable sparse vs padded row and cell iteration: Add `pad_empty_rows` and `pad_empty_cells` options to `Xlsxrb.read`, `Xlsxrb.build_worksheet`, `StreamSheet`, `WorksheetParser.each_row`, and `Elements::Worksheet` to pad skipped rows or missing cells up to the maximum column, and add `StreamRow#to_h` and `Elements::Row#cells_hash` for coordinate-keyed row maps.
+- Row XML metadata accessors and serialization: Expose row XML metadata (`collapsed`, `collapsed?`, `hidden?`, `custom_height?`, `attributes`) on `StreamRow` and `Elements::Row`, support `collapsed:` in `StreamWriter#row` and `WorksheetBuilder#row`, and serialize `collapsed="1"` in `WorksheetWriter`.
+- Format classification helpers: Add `Elements::Styles#format_code_for` and `#classification_for` aliases, allow `NumberFormatter` format predicates (`date_format?`, `time_format?`, etc.) to resolve built-in formats by `num_fmt_id`, and expose `format_type`, `date_format?`, and `time_format?` on `Elements::Cell`.
+- Date1904 accessor: Expose `Ooxml::Reader#date1904?` and add `date1904:` keyword argument to `Elements::Workbook#initialize`.
+- Coordinate utilities module: Add `Xlsxrb::Utils` exposing public coordinate helpers (`ref_to_row_col`, `row_col_to_ref`, `col_name_to_index`, `col_index_to_name`, `split_coordinate`).
+- Configurable trailing empty row trimming: Add `trim_empty_rows` option across `Xlsxrb.read`, `Xlsxrb.build_worksheet`, `WorksheetParser.each_row`, `StreamSheet#initialize`, `StreamSheet#each_row`, `StreamSheet#each_row_values`, `StreamSheet#each`, `Elements::Worksheet#initialize`, `Elements::Worksheet#each_row`, and `Elements::Worksheet#each_row_values` to omit trailing empty rows, and add `empty?` predicate to `StreamRow` and `Elements::Row`.
+- Direct typed values streaming iterator: Add `StreamSheet#each_row_values` and `Elements::Worksheet#each_row_values` to stream row values directly as Arrays without allocating `Elements::Cell` objects, and add `type_cast: true` support across `StreamSheet#each_row_values`, `Elements::Worksheet#each_row_values`, `StreamRow#values`, and `Elements::Row#values` to coerce date/time serial numbers into `Date` and `Time` instances.
+- Precomputed number format classifications in Styles: Add `Xlsxrb::Elements::Styles` (subclass of `Hash`) with precomputed $O(1)$ format classification lookups (`number_format`, `format_type`, `date_format?`, `datetime_format?`, `time_format?`, `date_only_format?`), update `StylesParser.parse` to return `Elements::Styles`, and add classification helper methods to `Xlsxrb::NumberFormatter`.
+- Worksheet dimension and coordinate bounds: Expose `dimension`, `first_row`, `first_column` (aliased `first_col`), `last_row`, and `last_column` (aliased `last_col`) on `StreamSheet` and `Elements::Worksheet` (and `Elements::CoordinateAccess`), lazily extracting `<dimension ref="..."/>` in $O(1)$ memory without scanning the full sheet.
+- Date1904 propagation to streaming sheets and rows: Propagate the workbook's 1904 date system flag to `StreamSheet` and `StreamRow`, expose `date1904?` on `StreamSheet`, `StreamRow`, `Elements::Worksheet`, and `Elements::Cell`, and default `Cell#to_date` and `Cell#to_time` to the cell's `date1904` setting.
+- `Elements::RichTextRun`: Add `RichTextRun` data class representing formatted text runs within `RichText`, supporting hash-like bracket access and seamless integration with `Xlsxrb.rich_text`.
+- First-class conditional formatting and data validation on `Elements::Worksheet`: Expose `conditional_formatting` (and alias `conditional_formats`) and `data_validations` as first-class fields on `Elements::Worksheet`, populate them during round-trip parsing in `Xlsxrb.build_worksheet`, and serialize them in in-memory workbook serialization.
+- Date1904 calendar system arithmetic: Support the 1904 date system (1904-01-01 base epoch) across serial date conversions, `Cell#to_date`, `Cell#to_time`, `Elements::Workbook#date1904?`, `Ooxml::Reader`, `Ooxml::WorksheetWriter`, `Ooxml::WorkbookWriter`, and `StreamWriter`.
+- Row and column styles persistence: Expose `style_index` on `Row`, `Column`, and `StreamRow`, and persist row and column styles (`<row s="..." customFormat="1">` and `<col style="..."/>`) during serialization and round-trip parsing.
+- Styles metadata persistence: Support border colors, cell alignment, and protection attributes in stylesheet generation and round-trip parsing.
+- Dual format support for `num_fmts`: Support both `Hash` (`{ 164 => "format" }`) and `Array` (`[{ num_fmt_id: 164, format_code: "format" }]`) structures for custom number formats in `WorkbookWriter`.
+- Initial shared strings table seeding: Support pre-seeding `sst` in `Xlsxrb.write` when `workbook.shared_strings` is provided.
+- Sheet visibility state: Support worksheet visibility state (`state`, `hidden?`, `visible?`) across `StreamSheet`, `Elements::Worksheet`, `WorkbookParser`, `WorkbookBuilder`, and `WorkbookWriter`, preserving `:visible`, `:hidden`, and `:very_hidden` visibility in streaming read, in-memory representations, and XML serialization.
+- Workbook defined names: Parse `<definedNames>` in `WorkbookParser` and expose `defined_names` array and `defined_name(name, sheet: nil)` lookup on `Elements::Workbook`, supporting global and sheet-scoped named ranges and formula constants.
+- Cell formula query and expression methods: Expose `formula?` predicate and `formula_expression` string accessor on `Elements::Cell`, and normalize empty formula expressions to `nil` in streaming and DOM cell parsing.
+- Worksheet and cell hyperlinks: Parse and expose hyperlink metadata across `StreamSheet#hyperlinks`, `Elements::Worksheet#hyperlinks`, and `Elements::Cell#hyperlink`, `#link?`, and `#url`, supporting external targets and internal sheet references in streaming read, DOM models, and builders.
+- Worksheet and cell comments: Parse and expose comment and note metadata across `StreamSheet#comments`, `StreamSheet#comment`, `Elements::Worksheet#comments`, and `Elements::Cell#comment`, `#comment?`, and `#comment_text`, supporting comment annotations and coordinate lookups in streaming read, DOM models, and builders.
+- Number formatting engine and extended cell metadata: Add `Xlsxrb::NumberFormatter` supporting standard and custom OpenXML format codes (currencies, percentages, date/time, fixed-point padding, accounting patterns, scientific notation, and text), expose `formatted_value`, `raw_value`, and `format_code` on `Elements::Cell`, add `formatted_value` coordinate lookups on `Elements::Worksheet`, `StreamSheet`, and `Elements::Workbook`, and expose `raw_values`, `formatted_values`, and `formulas` metadata on `Elements::Row` and `StreamRow`.
+- Fallback serialization for DOM model attributes: Support serializing first-class `ws.state`, `ws.comments`, `ws.hyperlinks`, and `workbook.defined_names` in `Xlsxrb.write(workbook)` when not explicitly packaged inside `unmapped_data[:facade]` metadata.
+
+### Changed
+- Optimize chunked streaming read performance: Hoist `</sheetData>` tag lookup outside row iteration, eliminate byte delimiter array allocations, and terminate entry inflation early once worksheet rows are fully parsed, restoring streaming read throughput faster than in-memory read while preserving $O(1)$ memory consumption.
+
+### Fixed
+- Fallback cached value for formula cells: Emit `<v>0</v>` instead of omitting `<v>` when a formula cell does not specify a cached value, ensuring compatibility with OpenXML parsers (such as Roo and LibreOffice) that discard formula cells lacking `<v>` elements.
+- Shared formula cell parsing: Support self-closing formula tags (e.g. `<f t="shared" si="0"/>`) in `WorksheetParser` regex scanners, preventing cells containing shared formulas from being silently omitted.
+- Fixed missing `dcterms:created` and `dcterms:modified` serialization in `WorkbookWriter` core properties (`docProps/core.xml`).
+- Prevent `Encoding::CompatibilityError` in `Xlsxrb.read` and `Cfb::Reader.cfb?` when inspecting raw string buffers in UTF-8 encoding.
+
+## [0.1.13] - 2026-09-25
+
+### Added
+- Non-destructive template modification: Support modifying existing XLSX templates while preserving unmapped parts, media, charts, drawings, and VBA macros via `Xlsxrb.modify`.
+- StreamSheet structural metadata accessors: Expose `merged_cells`, `auto_filter`, `data_validations`, and `conditional_formats` on `StreamSheet`.
+- Pre-Push Smart Change Detection: Optimized `bin/pre-push --all` to automatically skip runtime RBS validation and pure logic mutation testing when unrelated files are modified, adding `--last` and `--force` controls.
+
+### Changed
+- True O(1) memory streaming read via chunked entry inflation in `ZipReader` and `WorksheetParser`, preventing unbounded memory retention on large worksheets.
+- Extracted pure DSL normalizers (`Xlsxrb::DslHelpers`) and fast XML unescape utilities (`Ooxml::XmlBuilder.unescape`).
+- Constrained `rexml` runtime dependency to `~> 3.0` and excluded documentation, build assets, and developer configurations from the gem package.
+
+### Removed
+- OpenTelemetry runtime dependency and tracer spans.
+
 ## [0.1.12] - 2026-09-20
 
 ### Added
-- **Mutation Testing Framework (`mutant`)**:
+- Mutation Testing Framework (`mutant`):
   - Full-scale integration of mutant test suite targeting the Functional Core (10 classes and modules, 38 subjects).
-  - Achieved **100.00% Kill Rate (1,091 / 1,091 mutations killed, 0 alive)** without exclusions.
+  - Achieved 100.00% Kill Rate (1,091 / 1,091 mutations killed, 0 alive) without exclusions.
   - Added dedicated root configuration [`.mutant.yml`](.mutant.yml) for streamlined CLI execution (`bundle exec mutant run -- '...'`).
   - Integrated `bundle exec rake mutant:pure` into GitHub Actions CI pipeline (`main.yml`), guaranteeing mutation-tested quality on every push and pull request.
-  - Added comprehensive architecture and testing guide in [`docs/MUTATION_TESTING.md`](docs/MUTATION_TESTING.md).
-- **Pre-Push Quality Verification Script (`bin/pre-push`)**: Added automated pre-push verification script running RuboCop, Steep type checking, RBS sync validation, Unit & Contract tests, RBS runtime type validation, and pure logic mutation testing, with automatic hook installation in `bin/setup`.
+  - Added architecture and testing guide in [`docs/MUTATION_TESTING.md`](docs/MUTATION_TESTING.md).
+- Pre-Push Quality Verification Script (`bin/pre-push`): Added automated pre-push verification script running RuboCop, Steep type checking, RBS sync validation, Unit & Contract tests, RBS runtime type validation, and pure logic mutation testing, with automatic hook installation in `bin/setup`.
 
 ### Changed
-- **Functional Core & Imperative Shell Architecture**:
+- Functional Core & Imperative Shell Architecture:
   - Purified core business logic and domain entities into deterministic, side-effect-free class methods and predicates:
     - Extracted coordinate and validation predicates: `Elements::Cell.valid_value?`, `Cell.valid_coordinates?`, `Cell.calculate_column_letter`, `Cell.calculate_column_index`.
     - Extracted domain validation predicates: `Elements::Row.valid_index?`, `Elements::Column.valid_index?`, `Elements::Worksheet.valid_name?`.
-    - Replaced date/time serial calculations in `Ooxml::Utils` with pure mathematical conversions (Julian Day math for `date_to_serial`, `divmod` arithmetic for `serial_to_datetime`, and rigorous 1900 leap year bug handling).
+    - Replaced date/time serial calculations in `Ooxml::Utils` with pure mathematical conversions (Julian Day math for `date_to_serial`, `divmod` arithmetic for `serial_to_datetime`, and 1900 leap year bug handling).
     - Extracted binary packing utilities in `Ooxml::ZipGenerator` (`le16`, `le32`, and bitfield arithmetic for `dos_datetime`).
     - Extracted pure XML character escaping logic in `Ooxml::XmlBuilder.escape`.
   - Modularized `Ooxml::Writer` into domain-specific mixin modules (`DrawingXml`, `FeaturesXml`, `StylesXml`).
@@ -22,12 +96,12 @@
   - Modularized reader SAX listeners into domain-specific parser components.
 
 ### Fixed
-- **Boundary Validation & Error Reporting**:
+- Boundary Validation & Error Reporting:
   - Strictly validate row number digits in `Elements::Cell.parse_ref` to reject malformed cell coordinate strings (e.g. `A0`, `A01`).
   - Harmonized supported value type checks and nil/empty handling across `Elements::Cell.validate`.
   - Corrected maximum row index boundary error messages in `Elements::Row.validate`.
   - Hardened cryptographic stream boundary checks and corrupted header handling in Standard and Agile encryption modes.
-- **RBS Runtime Type Validation**:
+- RBS Runtime Type Validation:
   - Expanded `Elements::Workbook#initialize`, `#sheet`, and `[]` type annotations to accept `StreamSheet` instances used by streaming readers.
   - Made update block parameter optional in `Elements::Workbook#update_sheet` to allow testing missing block validation.
   - Supported `Numeric` types (Float and Integer) in `ChartBuilder` and `SeriesBuilder` kwargs (`width`, etc.).
@@ -36,15 +110,15 @@
 ## [0.1.11] - 2026-08-19
 
 ### Performance
-- **Sub-Second Streaming Write (< 1.0s / 1,000,000 cells)**:
-  - Achieved sub-second streaming write performance (**0.97 s** median for 1M cells) while maintaining 100% full SST (Shared String Table) XML deduplication and ISO/IEC 29500 compatibility.
+- Sub-Second Streaming Write (< 1.0s / 1,000,000 cells):
+  - Achieved sub-second streaming write performance (0.97 s median for 1M cells) while maintaining 100% full SST (Shared String Table) XML deduplication and ISO/IEC 29500 compatibility.
   - Implemented 1-Pass Direct ZIP streaming pipeline, eliminating all intermediate tempfiles, disk seek-backs, and extra deflate flush cycles.
   - Added dedicated unstyled fast-path in `WorksheetWriter#write_row_values` with precomputed coordinate and integer lookup tables.
   - Pre-registered default date/time formatting styles, completely eliminating redundant per-row scan loops.
   - Streamlined `ZipWriter` instance variable lookups to eliminate per-chunk hash overhead.
   - Added `alias << row` to `WorksheetProxy` and `StreamWriter` for idiomatic Ruby streaming.
-- **High-Speed Streaming Read (1.61s / 1,000,000 cells)**:
-  - Reduced streaming read execution time from **3.40 s** down to **1.61 s** (over 2x speedup).
+- High-Speed Streaming Read (1.61s / 1,000,000 cells):
+  - Reduced streaming read execution time from 3.40 s down to 1.61 s (over 2x speedup).
   - Refactored `Elements::Cell` into an optimized lightweight class with `Cell.fast_create`, reducing 1M cell instantiation overhead by 5.2x (0.92s → 0.17s) while maintaining full pattern matching (`deconstruct`, `deconstruct_keys`) and immutability.
   - Replaced per-byte Ruby scanning in `WorksheetParser.fast_scan_cells_direct` with an Onigmo C-level regular expression scanner (`CELL_FAST_RE`), eliminating 100,000 intermediate XML substring allocations and nested byte loops.
   - Optimized `StreamRow#cells` to populate cell arrays via direct block traversal, eliminating Enumerator object allocations.
@@ -55,56 +129,56 @@
 ## [0.1.10] - 2026-08-19
 
 ### Added
-- **Peer Libraries Ecosystem Guide ([docs/PEER_LIBRARIES.md](docs/PEER_LIBRARIES.md))**: Introduced a respectful overview of the Ruby XLSX ecosystem featuring official self-descriptions, architectural tradeoffs (SST vs. Inline Strings, Streaming vs. In-Memory), and reproducible benchmarks across 9 popular Ruby XLSX gems.
-- **Visual Assets & Screen Previews**:
+- Peer Libraries Ecosystem Guide ([docs/PEER_LIBRARIES.md](docs/PEER_LIBRARIES.md)): Introduced a respectful overview of the Ruby XLSX ecosystem featuring official self-descriptions, architectural tradeoffs (SST vs. Inline Strings, Streaming vs. In-Memory), and reproducible benchmarks across 9 popular Ruby XLSX gems.
+- Visual Assets & Screen Previews:
   - Embedded interactive WebAssembly Playground live demo preview in `README.md`.
   - Added real-world Ruby LSP autocompletion and RBS type hint preview in `README.md`.
   - Created accurate, neutral linear-scale SVG benchmark performance chart.
-- **Enterprise-Grade Test Suite Expansion**:
-  - **ECMA-376 XSD Schema Validation**: Comprehensive XML schema validation suite ensuring strict element ordering and ISO/IEC 29500 compliance.
-  - **Contract Testing Suite**: Comprehensive parity verification between Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
-  - **Property-Based Testing (PBT)**: Expanded automated random generation tests for Row/Column invariants, styles, and edge cases.
-  - **Visual Regression Testing (VRT)**: Added new visual baselines for table styles, drawing shapes, and pivot tables.
-  - **E2E Interoperability Suite**: Added tests for namespace-prefixed XML streaming, conditional formatting, and table structures.
+- Multi-Layered Test Suite Expansion:
+  - ECMA-376 XSD Schema Validation: XML schema validation suite ensuring strict element ordering and ISO/IEC 29500 compliance.
+  - Contract Testing Suite: Parity verification between Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
+  - Property-Based Testing (PBT): Expanded automated random generation tests for Row/Column invariants, styles, and edge cases.
+  - Visual Regression Testing (VRT): Added new visual baselines for table styles, drawing shapes, and pivot tables.
+  - E2E Interoperability Suite: Added tests for namespace-prefixed XML streaming, conditional formatting, and table structures.
 
 ### Fixed
-- **WebAssembly (ruby.wasm) Compatibility**: Bundled `pp` and `prettyprint` standard libraries in `ruby.wasm` package to resolve REXML LoadError during browser-based evaluation.
+- WebAssembly (ruby.wasm) Compatibility: Bundled `pp` and `prettyprint` standard libraries in `ruby.wasm` package to resolve REXML LoadError during browser-based evaluation.
 
 ### Changed
-- **Streamlined README**: Refactored README from 363 to 175 lines, focusing on core motivation, clean 4-column feature matrix, concise usage examples, and direct links to specialized documentation.
+- Streamlined README: Refactored README from 363 to 175 lines, focusing on core motivation, clean 4-column feature matrix, concise usage examples, and direct links to specialized documentation.
 
 ## [0.1.9] - 2026-08-18
 
 ### Added
-- **Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB])**: Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
-  - **Standard Encryption**: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
-  - **Agile Encryption**: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
-  - **Compound File Binary (CFB) Engine**: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
-  - **Transparent Public API Integration**: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
-  - **Security & Threat Model Hardening**:
+- Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB]): Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
+  - Standard Encryption: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
+  - Agile Encryption: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
+  - Compound File Binary (CFB) Engine: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
+  - Transparent Public API Integration: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
+  - Security & Threat Model Hardening:
     - Constant-time hash verification via `OpenSSL.secure_compare` to prevent timing attacks (CWE-208).
     - CSPRNG-backed salt, IV, and session key generation via `SecureRandom` (CWE-330).
-    - Robust DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
+    - DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
     - Strict exception hierarchy (`EncryptedFileError`, `InvalidPasswordError`, `DecryptionError`).
-  - **Cross-Platform & Interoperability Validation**: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
-  - **WebAssembly (ruby.wasm) Support**: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
+  - Cross-Platform & Interoperability Validation: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
+  - WebAssembly (ruby.wasm) Support: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
 
 ## [0.1.8] - 2026-08-18
 
 ### Changed
-- **Unified Symmetric Entrypoints**: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
-- **Streaming-First Defaults**: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
-- **Explicit In-Memory Materialization (`#load`)**: Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
-- **`CoordinateAccess` Module**: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
+- Unified Symmetric Entrypoints: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
+- Streaming-First Defaults: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
+- Explicit In-Memory Materialization (`#load`): Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
+- `CoordinateAccess` Module: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
 
 ### Added
-- **Default Cell Streaming (`Xlsxrb::StreamRow`)**: Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
+- Default Cell Streaming (`Xlsxrb::StreamRow`): Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
 
 ## [0.1.7] - 2026-08-16
 
 ### Added
 - Bundled native Ruby LSP Add-on (`RubyLsp::Xlsxrb::Addon`) for zero-configuration, context-aware method autocompletion and rich markdown documentation in VS Code and LSP-enabled editors for block arguments (`wb.`, `s.`, `sheet.`, `stream_writer.`, `stream_sheet.`).
-- Comprehensive YARD documentation (`@param`, `@return`, `@example`) across all public APIs, builders, proxies, and elements.
+- YARD documentation (`@param`, `@return`, `@example`) across all public APIs, builders, proxies, and elements.
 
 ### Developer Experience
 - Enhanced `rbs-inline` type signatures across all facade methods and builder objects with automated RBS generation.
@@ -119,10 +193,10 @@
 - Hash-compatible symbol indexing in `Elements::Row#[]` (`:cells`, `:index`, `:height`, `:attrs`) and `Elements::Cell#[]` (`:value`, `:ref`, `:style_index`).
 
 ### Performance
-- **Streaming Write**: Replaced per-cell micro IO calls with row-level string buffering and fast-path serialization for unstyled cells (1,000,000 cells in 1.62s with standard SST).
-- **In-Memory Write**: Optimized DOM serialization (`WorksheetWriter#write_row`) with row-level buffer aggregation, boosting 1,000,000 cells write from 22.33s to 4.06s (5.5x faster) and reducing GC count by 83%.
-- **Streaming Read**: Implemented zero-allocation byte scanning for cell attributes (`r="..."`, `t="..."`, `s="..."`) and direct integer conversion for SST indexes, cutting GC count by ~70% (129 -> 40) and boosting 1,000,000 cells read to 3.38s.
-- **In-Memory Read**: Reduced peak memory footprint by 57% (582 MB -> 250 MB).
+- Streaming Write: Replaced per-cell micro IO calls with row-level string buffering and fast-path serialization for unstyled cells (1,000,000 cells in 1.62s with standard SST).
+- In-Memory Write: Optimized DOM serialization (`WorksheetWriter#write_row`) with row-level buffer aggregation, boosting 1,000,000 cells write from 22.33s to 4.06s (5.5x faster) and reducing GC count by 83%.
+- Streaming Read: Implemented zero-allocation byte scanning for cell attributes (`r="..."`, `t="..."`, `s="..."`) and direct integer conversion for SST indexes, cutting GC count by ~70% (129 -> 40) and boosting 1,000,000 cells read to 3.38s.
+- In-Memory Read: Reduced peak memory footprint by 57% (582 MB -> 250 MB).
 
 ### Documentation
 - Overhauled `benchmark.rb` with `bundler/inline` for deterministic, zero-setup benchmark reproduction pinning peer gem versions.
@@ -142,7 +216,7 @@
 - Full `RBS::Test` runtime type validation enabled for the entire test suite.
 - Extensive Excel limit warnings documented via YARD tags.
 - Formal SemVer API contract with `@api public` tags for user-facing methods.
-- Comprehensive mutation testing (Mutant) and test coverage (SimpleCov) integrations.
+- Mutation testing (Mutant) and test coverage (SimpleCov) integrations.
 
 ### Changed
 - Replaced `method_missing` with statically defined, fully typed methods in `WorksheetProxy`, `ChartBuilder`, and `SeriesBuilder`.

data/README.md

@@ -2,9 +2,11 @@
 
 A Ruby library for reading and writing XLSX files with streaming support.
 
+Drop-in compatibility adapters for peer Ruby XLSX libraries are available at [xlsxrb-adapters](https://github.com/niku/xlsxrb-adapters).
+
 ## Motivation
 
-The Ruby ecosystem already has great XLSX libraries, each designed for specific tradeoffs:
+The Ruby ecosystem has several XLSX libraries designed for specific tradeoffs:
 
 | Library | Read | Write | Streaming | In-Memory |
 | :--- | :---: | :---: | :---: | :---: |
@@ -17,23 +19,27 @@ The Ruby ecosystem already has great XLSX libraries, each designed for specific
 | [xlsxtream](https://rubygems.org/gems/xlsxtream) | ❌ | ✅ | ✅ | ❌ |
 | [fast_excel](https://rubygems.org/gems/fast_excel) | ❌ | ✅ | ✅ | ❌ |
 | [rubyXL](https://rubygems.org/gems/rubyXL) | ✅ | ✅ | ❌ | ✅ |
-| **[xlsxrb](https://github.com/niku/xlsxrb)** | **✅** | **✅** | **✅** | **✅** |
+| [xlsxrb](https://github.com/niku/xlsxrb) | ✅ | ✅ | ✅ | ✅ |
 
-Each of these libraries makes deliberate architectural choices:
-* **Streaming Model**: Writes or reads rows sequentially on-the-fly to maintain a constant $O(1)$, low-memory footprint regardless of dataset size.
-* **In-Memory Model**: Builds a complete document object model, offering flexible random access, cell updates, and document templates at the cost of memory usage on large spreadsheets.
+These libraries make different architectural tradeoffs:
+* Streaming Model: Writes or reads rows sequentially on-the-fly to maintain a constant $O(1)$, low-memory footprint regardless of dataset size.
+* In-Memory Model: Builds a complete document object model, offering flexible random access, cell updates, and document templates at the cost of memory usage on large spreadsheets.
 
-Traditionally, maintaining an all-in-one gem that offers both reading and writing across both streaming and in-memory models, alongside rich OOXML features, high performance, and strict compatibility, presents an inherent open-source challenge: the cumulative maintenance overhead often exceeds the capacity of individual human maintainers.
+Maintaining a gem that supports both reading and writing across streaming and in-memory models, alongside OOXML features and specification compatibility, involves significant ongoing maintenance overhead.
 
-`xlsxrb` is built on a modern premise: **Advanced Agentic AI (AI Coders) can sustainably handle this maintenance demand.** By utilizing AI agents to automate end-to-end testing, visual regression testing, specification compliance verification, and documentation updates, `xlsxrb` delivers a fast, specification-compliant, and fully-featured XLSX library built for long-term sustainability.
+`xlsxrb` addresses this through automated workflows: AI coding agents handle routine maintenance tasks such as end-to-end testing, visual regression testing, schema compliance checks, and documentation synchronization, enabling sustainable maintenance of both streaming and in-memory architectures.
 
 ### Design Principles
 
-- **Minimal Dependencies**: Zero core logic dependencies. Built purely on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.). The only runtime dependency is `opentelemetry-api` (zero-overhead no-op when unconfigured).
-- **Streaming Support**: True $O(1)$ constant memory streaming for both reading and writing massive spreadsheets.
-- **Strict OpenXML Interoperability**: Fully compliant with ISO/IEC 29500 (ECMA-376) and validated continuously against the official Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
-- **AI-Assisted Sustainability**: Leveraging AI coding agents for automated quality assurance, E2E validation, and continuous feature expansion.
-- **Modern Ruby**: Built for Ruby 4.0 or higher.
+- Zero Runtime Dependencies: Built strictly on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.) with zero third-party runtime dependencies.
+- Streaming Support: Constant $O(1)$ memory streaming for reading and writing spreadsheets.
+- OpenXML Interoperability: Compliant with ISO/IEC 29500 (ECMA-376) and validated against the Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
+- AI-Assisted Maintenance: Uses AI coding agents for automated quality assurance and verification workflows. Operational guidelines are defined in [AGENTS.md](AGENTS.md).
+- Ruby 4.0+: Requires Ruby 4.0 or higher.
+
+### Autonomous Quality Assurance
+
+To maintain its multi-layered QA suite (Steep static typing, 100% mutation kill rate across 38 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
 
@@ -134,7 +140,7 @@ end
 
 ### IDE Autocompletion & Ruby LSP Support
 
-Includes a native **Ruby LSP Add-on** and full **RBS signatures** for zero-configuration method autocompletion and hover documentation in VS Code and other editors:
+Includes a native Ruby LSP Add-on and full RBS signatures for zero-configuration method autocompletion and hover documentation in VS Code and other editors:
 
 <p align="center">
   <img src="docs/assets/lsp_autocompletion.png" width="100%" alt="Ruby LSP Autocompletion & Type Signature Hints in VS Code"/>
@@ -142,9 +148,9 @@ Includes a native **Ruby LSP Add-on** and full **RBS signatures** for zero-confi
 
 ## Feature Support & ECMA-376 Compliance
 
-`xlsxrb` supports nearly all major business spreadsheet features:
-* **Layout & Structure**: Formulas, Hyperlinks, Merge Cells, Freeze/Split Panes, Page Setup, Auto Filters, Data Validations, Sheet/Workbook Protection.
-* **Styling & Media**: Rich Text, Cell Styles & Fills, Conditional Formatting (color scales, data bars), Embedded Images, Charts (Line, Bar, Pie, Radar, Scatter).
+`xlsxrb` supports standard spreadsheet features:
+* Layout & Structure: Formulas, Hyperlinks, Merge Cells, Freeze/Split Panes, Page Setup, Auto Filters, Data Validations, Sheet/Workbook Protection.
+* Styling & Media: Rich Text, Cell Styles & Fills, Conditional Formatting (color scales, data bars), Embedded Images, Charts (Line, Bar, Pie, Radar, Scatter).
 
 For full details, see [docs/SPEC_SOURCES.md](docs/SPEC_SOURCES.md).
 
@@ -162,12 +168,12 @@ To reproduce locally: `ruby benchmark.rb 100000 10`
 
 ## Quality Assurance & Testing
 
-Backed by an enterprise-grade QA architecture to guarantee absolute reliability:
-* **Official 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,091/1,091 mutations across 38 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.
+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,091/1,091 mutations across 38 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/colors.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Xlsxrb
+  # ECMA-376 Part 4 §18.8.27 Standard Indexed Color Palette and utilities.
+  module Colors
+    # Standard ECMA-376 indexed colors (indices 0 through 63 as 6-character RRGGBB hex strings).
+    # Indices 8 through 63 represent the classic 56-color palette.
+    INDEXED_COLORS = [
+      "000000", # 0
+      "FFFFFF", # 1
+      "FF0000", # 2
+      "00FF00", # 3
+      "0000FF", # 4
+      "FFFF00", # 5
+      "FF00FF", # 6
+      "00FFFF", # 7
+      "000000", # 8: Black
+      "FFFFFF", # 9: White
+      "FF0000", # 10: Red
+      "00FF00", # 11: Green
+      "0000FF", # 12: Blue
+      "FFFF00", # 13: Yellow
+      "FF00FF", # 14: Magenta
+      "00FFFF", # 15: Cyan
+      "800000", # 16: Brown / Dark Red
+      "008000", # 17: Olive / Dark Green
+      "000080", # 18: Navy / Dark Blue
+      "808000", # 19: Dark Yellow
+      "800080", # 20: Purple
+      "008080", # 21: Teal
+      "C0C0C0", # 22: Silver / Light Gray
+      "808080", # 23: Gray
+      "9999FF", # 24
+      "993366", # 25
+      "FFFFCC", # 26
+      "CCFFFF", # 27
+      "660066", # 28
+      "FF8080", # 29
+      "0066CC", # 30
+      "CCCCFF", # 31
+      "000080", # 32
+      "FF00FF", # 33
+      "FFFF00", # 34
+      "00FFFF", # 35
+      "800080", # 36
+      "800000", # 37
+      "008080", # 38
+      "0000FF", # 39
+      "00CCFF", # 40
+      "CCFFFF", # 41
+      "CCFFCC", # 42
+      "FFFFC0", # 43
+      "CCE5FF", # 44
+      "99CCFF", # 45
+      "FF99CC", # 46
+      "CC99FF", # 47
+      "FFCC99", # 48
+      "3366FF", # 49
+      "33CCCC", # 50
+      "99CC00", # 51
+      "FFCC00", # 52
+      "FF9900", # 53
+      "FF6600", # 54
+      "666699", # 55
+      "969696", # 56
+      "003366", # 57
+      "339966", # 58
+      "003300", # 59
+      "333300", # 60
+      "993300", # 61
+      "993366", # 62
+      "333333"  # 63
+    ].freeze
+
+    # Resolves a palette index (0..63) to an RRGGBB hex string (or AARRGGBB if alpha: true).
+    #
+    # @example
+    #   Xlsxrb::Colors.palette_color(12)               #=> "0000FF"
+    #   Xlsxrb::Colors.palette_color(12, alpha: true)  #=> "FF0000FF"
+    #
+    # @param index [Object, nil] Palette index (0..63).
+    # @param alpha [Boolean] Whether to prefix "FF" alpha channel.
+    # @return [String, nil]
+    # @api public
+    #: (untyped index, ?alpha: bool) -> String?
+    def self.palette_color(index, alpha: false)
+      return nil unless index.is_a?(Integer) && index >= 0 && index < INDEXED_COLORS.size
+
+      hex = INDEXED_COLORS[index]
+      alpha ? "FF#{hex}" : hex
+    end
+
+    # Converts any supported color representation (palette index 0..63, CSS name, #RGB, #RRGGBB, #AARRGGBB, integer RGB)
+    # to a normalized hex string.
+    #
+    # @example
+    #   Xlsxrb::Colors.to_hex(12)                      #=> "0000FF"
+    #   Xlsxrb::Colors.to_hex(12, alpha: true)         #=> "FF0000FF"
+    #   Xlsxrb::Colors.to_hex(:navy)                   #=> "000080"
+    #   Xlsxrb::Colors.to_hex("#FF0000")               #=> "FF0000"
+    #   Xlsxrb::Colors.to_hex(0xFF0000)                #=> "FF0000"
+    #
+    # @param color [Integer, String, Symbol, nil]
+    # @param alpha [Boolean] Whether to include the alpha channel (default false -> "RRGGBB").
+    # @return [String, nil]
+    # @api public
+    #: (Integer | String | Symbol | nil color, ?alpha: bool) -> String?
+    def self.to_hex(color, alpha: false)
+      return nil if color.nil?
+
+      return palette_color(color, alpha: alpha) if color.is_a?(Integer) && color >= 0 && color < INDEXED_COLORS.size
+
+      StyleBuilder.normalize_color(color, alpha: alpha)
+    end
+  end
+end

data/lib/xlsxrb/dsl_helpers.rb

@@ -112,5 +112,64 @@ module Xlsxrb
       tbl.merge!(opts)
       tbl
     end
+
+    # Converts a cell range (e.g. "A1:B2" or "A1") to an absolute reference format (e.g. "$A$1:$B$2" or "$A$1").
+    #
+    # @param range [String]
+    # @return [String]
+    #: (String range) -> String
+    def self.absolute_range(range)
+      range.gsub(/(?:\$)?([A-Z]+)(?:\$)?(\d+)\b/, '$\1$\2')
+    end
+
+    # Normalizes row values: if given a column-keyed Hash, converts to a sparse Array.
+    # If already an Array or other non-Hash enumerable, returns as-is without allocations.
+    #
+    # @param values [Array<Object>, Hash{String, Integer, Symbol => Object}, nil]
+    # @return [Array<Object>, nil]
+    #: (untyped values) -> untyped
+    def self.normalize_row_values(values)
+      return values unless values.is_a?(Hash)
+
+      cells_array = []
+      values.each do |k, v|
+        cells_array[Elements::Cell.column_index(k)] = v
+      end
+      cells_array
+    end
+
+    # Normalizes row styles: if given a Hash of column-keyed styles (including Ranges/Arrays),
+    # expands to a sparse Array of styles. If already an Array or nil, returns as-is without allocations.
+    #
+    # @param styles [untyped]
+    # @return [untyped]
+    #: (untyped styles) -> untyped
+    def self.normalize_row_styles(styles)
+      return styles unless styles.is_a?(Hash)
+
+      styles_array = []
+      styles.each do |k, v|
+        if k.is_a?(Range) || k.is_a?(Array)
+          k.each { |idx| styles_array[Elements::Cell.column_index(idx)] = v }
+        else
+          styles_array[Elements::Cell.column_index(k)] = v
+        end
+      end
+      styles_array
+    end
+
+    # Validates row index and height against Excel limits in strict mode.
+    #
+    # @param row_index [Integer]
+    # @param height [Float, Integer, nil]
+    # @param strict_excel_mode [Boolean]
+    # @return [void]
+    #: (Integer row_index, Float | Integer | nil height, ?strict_excel_mode: bool) -> void
+    def self.validate_row_bounds!(row_index, height, strict_excel_mode: true)
+      return unless strict_excel_mode
+
+      raise ArgumentError, "Row index #{row_index} exceeds Excel limit of 1,048,576 rows" if row_index >= 1_048_576
+      raise ArgumentError, "Row height #{height} must be between 0 and 409 points (Excel limitation)" if height && (height.negative? || height > 409)
+    end
   end
 end