xlsxrb 0.1.13 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6733f82b936fb790e6192de72890ecedd016f21dd4a5e43ee0f5123a2d35f5e
-  data.tar.gz: 3dd84ebc97a5c10a2777f6bd7557b06660e690f0723f8af6664a244a143adaa6
+  metadata.gz: 476e6f6e689eb65fecbbda4b81592c124b50f16fff0bbc9fec027a1f55ed4454
+  data.tar.gz: 8364dc6bff9b5f9601dc4cb375ef27b0456b7f88e721b2b52d1db7ba342c7de5
 SHA512:
-  metadata.gz: 6ca0217ecd3a83a922a1098740d584c6e78fd0695f46acaa661286497a0e0de1c9214990eb7fef622a10ad4a1641f9aae73079ab61b0787570a22e434b446d0e
-  data.tar.gz: 7603890bc9f20d9143656ea83f0fd75410b4636cc66bbd152e79965b4b2bc07013de05f1489560fc896b9f5e1890c9fb6b421ec8dbc49b66ca9dec7912ab617c
+  metadata.gz: 31f365a17ad3f5976033ddc7a9220c5606c6d8f6acfca356ef1b3404cd1ed6d1f86d2c86d57a5e27daf15a46bea3d1c193f4fb60662b2eccbc7078fe41777bbb
+  data.tar.gz: 67fe19a961f2bb204d19e5b9a49ade2c01e48de7d6a09ac1c87f7c591b570c0ba64494b43ce59d3ea492a70e18cf967d775af4fb55623287ab6b7b648bb0843c

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 ## [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

data/README.md

@@ -2,6 +2,8 @@
 
 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 has several XLSX libraries designed for specific tradeoffs:

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/elements/cell.rb

@@ -16,7 +16,7 @@ module Xlsxrb
     #
     # @api public
     class Cell
-      attr_reader :row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors
+      attr_reader :row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors, :hyperlink, :comment, :raw_value, :format_code, :date1904
 
       # @param row_index [Integer] 0-based row index.
       # @param column_index [Integer] 0-based column index.
@@ -25,8 +25,13 @@ module Xlsxrb
       # @param style_index [Integer, String, nil] Style identifier.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (row_index: untyped, column_index: untyped, ?value: untyped, ?formula: (Elements::Formula | String)?, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
-      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil)
+      # @param hyperlink [Hash, String, Elements::Hyperlink, nil] Optional hyperlink metadata or URL.
+      # @param comment [Hash, String, nil] Optional cell comment or note.
+      # @param raw_value [String, nil] Optional unparsed raw string value.
+      # @param format_code [String, nil] Optional OpenXML number/date format code.
+      # @param date1904 [Boolean] Whether the cell belongs to a 1904 date system workbook.
+      #: (row_index: untyped, column_index: untyped, ?value: untyped, ?formula: (Elements::Formula | String)?, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?hyperlink: (Hash[Symbol, untyped] | String | Elements::Hyperlink)?, ?comment: (Hash[Symbol, untyped] | String)?, ?raw_value: String?, ?format_code: String?, ?date1904: bool) -> void
+      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil, hyperlink: nil, comment: nil, raw_value: nil, format_code: nil, date1904: false)
         @row_index = row_index
         @column_index = column_index
         @value = value
@@ -35,9 +40,15 @@ module Xlsxrb
         @unmapped_data = unmapped_data || EMPTY_HASH
         computed_errors = errors || self.class.validate(row_index, column_index, value)
         @errors = computed_errors.frozen? ? computed_errors : computed_errors.freeze
+        @hyperlink = hyperlink
+        @comment = comment
+        @raw_value = raw_value
+        @format_code = format_code
+        @date1904 = date1904 ? true : false
       end
 
-      def self.fast_create(row_index, column_index, value, style_index = nil, formula = nil)
+      # rubocop:disable Style/OptionalBooleanParameter
+      def self.fast_create(row_index, column_index, value, style_index = nil, formula = nil, raw_value = nil, format_code = nil, date1904 = false)
         inst = allocate
         inst.instance_variable_set(:@row_index, row_index)
         inst.instance_variable_set(:@column_index, column_index)
@@ -46,8 +57,14 @@ module Xlsxrb
         inst.instance_variable_set(:@style_index, style_index)
         inst.instance_variable_set(:@unmapped_data, EMPTY_HASH)
         inst.instance_variable_set(:@errors, EMPTY_ERRORS)
+        inst.instance_variable_set(:@hyperlink, nil)
+        inst.instance_variable_set(:@comment, nil)
+        inst.instance_variable_set(:@raw_value, raw_value)
+        inst.instance_variable_set(:@format_code, format_code)
+        inst.instance_variable_set(:@date1904, date1904 ? true : false)
         inst
       end
+      # rubocop:enable Style/OptionalBooleanParameter
 
       def ==(other)
         other.is_a?(Cell) &&
@@ -57,21 +74,26 @@ module Xlsxrb
           formula == other.formula &&
           style_index == other.style_index &&
           unmapped_data == other.unmapped_data &&
-          errors == other.errors
+          errors == other.errors &&
+          hyperlink == other.hyperlink &&
+          comment == other.comment &&
+          raw_value == other.raw_value &&
+          format_code == other.format_code
       end
       alias eql? ==
 
       def hash
-        [row_index, column_index, value, formula, style_index, unmapped_data, errors].hash
+        [row_index, column_index, value, formula, style_index, unmapped_data, errors, hyperlink, comment, raw_value, format_code].hash
       end
 
       def deconstruct
-        [row_index, column_index, value, formula, style_index, unmapped_data, errors]
+        [row_index, column_index, value, formula, style_index, unmapped_data, errors, hyperlink, comment, raw_value, format_code]
       end
 
       def deconstruct_keys(keys)
         h = { row_index: row_index, column_index: column_index, value: value, formula: formula,
-              style_index: style_index, unmapped_data: unmapped_data, errors: errors }
+              style_index: style_index, unmapped_data: unmapped_data, errors: errors, hyperlink: hyperlink,
+              comment: comment, raw_value: raw_value, format_code: format_code }
         keys ? h.slice(*keys) : h
       end
 
@@ -83,7 +105,12 @@ module Xlsxrb
           formula: changes.fetch(:formula, formula),
           style_index: changes.fetch(:style_index, style_index),
           unmapped_data: changes.fetch(:unmapped_data, unmapped_data),
-          errors: changes.fetch(:errors, errors)
+          errors: changes.fetch(:errors, errors),
+          hyperlink: changes.fetch(:hyperlink, hyperlink),
+          comment: changes.fetch(:comment, comment),
+          raw_value: changes.fetch(:raw_value, raw_value),
+          format_code: changes.fetch(:format_code, format_code),
+          date1904: changes.fetch(:date1904, @date1904 || false)
         )
       end
 
@@ -104,9 +131,120 @@ module Xlsxrb
         "#{self.class.column_letter(column_index)}#{row_index + 1}"
       end
 
+      # Returns whether the cell contains a formula.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def formula?
+        if formula.is_a?(Formula)
+          !formula.expression.nil? && !formula.expression.empty?
+        else
+          !formula.nil? && !formula.to_s.empty?
+        end
+      end
+
+      # Returns the formula expression string without leading '=', or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def formula_expression
+        expr = formula.is_a?(Formula) ? formula.expression : formula
+        return nil if expr.nil?
+
+        str = expr.to_s
+        str.empty? ? nil : str
+      end
+
+      # Returns whether the cell contains a hyperlink.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def link?
+        case hyperlink
+        when nil then false
+        when Hash, String then !hyperlink.empty?
+        else true
+        end
+      end
+      alias hyperlink? link?
+
+      # Returns the hyperlink target URL or location string, or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def url
+        case hyperlink
+        when Hash
+          u = hyperlink[:url] || hyperlink[:location]
+          u&.to_s
+        when String
+          hyperlink.empty? ? nil : hyperlink
+        when Elements::Hyperlink
+          (hyperlink.url || hyperlink.location)&.to_s
+        end
+      end
+
+      # Returns the hyperlink tooltip (ScreenTip) text, or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def tooltip
+        case hyperlink
+        when Hash
+          hyperlink[:tooltip]&.to_s
+        when Elements::Hyperlink
+          hyperlink.tooltip&.to_s
+        end
+      end
+
+      # Returns whether the cell contains a comment or note.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def comment?
+        case comment
+        when nil then false
+        when Hash, String then !comment.empty?
+        else true
+        end
+      end
+
+      # Returns the plain text of the cell comment or note, or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def comment_text
+        case comment
+        when Hash
+          txt = comment[:text]
+          txt&.to_s
+        when String
+          comment.empty? ? nil : comment
+        end
+      end
+
+      # Returns the formatted string representation of the cell value according to its format code.
+      #
+      # @param custom_format_code [String, nil] Optional format code override.
+      # @return [String, nil]
+      # @api public
+      #: (?String? custom_format_code) -> String?
+      def formatted_value(custom_format_code = nil)
+        return nil if value.nil?
+
+        NumberFormatter.format(value, custom_format_code || format_code)
+      end
+
       # Access cell attributes by Symbol key.
       #
-      # @param key [Symbol] Attribute key (:value, :formula, :style_index, :ref, :column_index, :row_index, :type).
+      # @param key [Symbol] Attribute key (:value, :formula, :style_index, :ref, :column_index, :row_index, :type, :raw_value, :format_code, :formatted_value).
       # @return [Object, nil]
       # @api public
       #: (Symbol key) -> untyped
@@ -119,6 +257,17 @@ module Xlsxrb
         when :ref then ref
         when :column_index then column_index
         when :row_index then row_index
+        when :hyperlink then hyperlink
+        when :url then url
+        when :tooltip then tooltip
+        when :comment then comment
+        when :raw_value then raw_value
+        when :format_code then format_code
+        when :formatted_value then formatted_value
+        when :format_type then format_type
+        when :date_format then date_format?
+        when :time_format then time_format?
+        when :date1904 then date1904?
         when :type
           case value
           when String then "s"
@@ -127,6 +276,42 @@ module Xlsxrb
         end
       end
 
+      # Returns the classified format category for this cell (:date, :datetime, :time, :number, :text, :general, or nil).
+      #
+      # @return [Symbol, nil]
+      # @api public
+      #: () -> Symbol?
+      def format_type
+        format_code ? NumberFormatter.format_type(format_code) : nil
+      end
+
+      # Returns whether the cell has a date, datetime, or time format.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def date_format?
+        format_code ? NumberFormatter.date_format?(format_code) : false
+      end
+
+      # Returns whether the cell has a time-only format.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def time_format?
+        format_code ? NumberFormatter.time_format?(format_code) : false
+      end
+
+      # Returns whether the cell's workbook uses the 1904 date system.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def date1904?
+        @date1904 ? true : false
+      end
+
       # Returns the cell value.
       #
       # @return [Object, nil]
@@ -165,14 +350,16 @@ module Xlsxrb
 
       # Converts the cell value (numeric serial date or date string) to Date.
       #
+      # @param date1904 [Boolean, nil] Whether to use the 1904 date system (defaults to cell's date1904 setting).
       # @return [Date, nil]
       # @api public
-      #: () -> Date?
-      def to_date
+      #: (?date1904: bool?) -> Date?
+      def to_date(date1904: nil)
         return value if value.is_a?(Date)
 
+        d1904 = date1904.nil? ? date1904? : date1904
         if value.is_a?(Numeric)
-          Ooxml::Utils.serial_to_date(value)
+          Ooxml::Utils.serial_to_date(value, date1904: d1904)
         else
           begin
             Date.parse(value.to_s)
@@ -184,14 +371,16 @@ module Xlsxrb
 
       # Converts the cell value (numeric serial datetime or datetime string) to Time.
       #
+      # @param date1904 [Boolean, nil] Whether to use the 1904 date system (defaults to cell's date1904 setting).
       # @return [Time, nil]
       # @api public
-      #: () -> Time?
-      def to_time
+      #: (?date1904: bool?) -> Time?
+      def to_time(date1904: nil)
         return value if value.is_a?(Time)
 
+        d1904 = date1904.nil? ? date1904? : date1904
         if value.is_a?(Numeric)
-          Ooxml::Utils.serial_to_datetime(value)
+          Ooxml::Utils.serial_to_datetime(value, date1904: d1904)
         else
           begin
             Time.parse(value.to_s)

data/lib/xlsxrb/elements/column.rb

@@ -12,21 +12,23 @@ module Xlsxrb
     #
     # @api public
     # rubocop:disable Style/DataInheritance -- Required as class syntax for mutant subject matcher
-    class Column < Data.define(:index, :width, :hidden, :custom_width, :outline_level, :unmapped_data, :errors)
+    class Column < Data.define(:index, :width, :hidden, :custom_width, :outline_level, :style_index, :unmapped_data, :errors)
       # rubocop:enable Style/DataInheritance
       # @param index [Integer] 0-based column index.
       # @param width [Float, Integer, nil] Column width in characters.
       # @param hidden [Boolean] Whether the column is hidden.
       # @param custom_width [Boolean] Whether custom width flag is set.
       # @param outline_level [Integer, nil] Grouping/outline level.
+      # @param style_index [Integer, String, nil] Optional style identifier.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (index: Integer, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      #: (index: Integer, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       def initialize(index:, width: nil, hidden: false, custom_width: false, outline_level: nil,
-                     unmapped_data: {}, errors: nil)
+                     style_index: nil, unmapped_data: {}, errors: nil)
+        style_idx = style_index || unmapped_data[:style_index] || unmapped_data[:style]
         computed_errors = errors || self.class.validate(index)
         super(index: index, width: width, hidden: hidden, custom_width: custom_width,
-              outline_level: outline_level, unmapped_data: unmapped_data,
+              outline_level: outline_level, style_index: style_idx, unmapped_data: unmapped_data,
               errors: computed_errors.freeze)
       end
 

data/lib/xlsxrb/elements/coordinate_access.rb

@@ -76,6 +76,38 @@ module Xlsxrb
         rows.max_by(&:index)
       end
 
+      # Returns the 1-based index of the first column containing data, or nil.
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def first_column
+        min_c = nil
+        rows.each do |r|
+          r.cells.each do |c|
+            min_c = c.column_index if min_c.nil? || c.column_index < min_c
+          end
+        end
+        min_c ? min_c + 1 : nil
+      end
+      alias first_col first_column
+
+      # Returns the 1-based index of the last column containing data, or nil.
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def last_column
+        max_c = nil
+        rows.each do |r|
+          r.cells.each do |c|
+            max_c = c.column_index if max_c.nil? || c.column_index > max_c
+          end
+        end
+        max_c ? max_c + 1 : nil
+      end
+      alias last_col last_column
+
       # Returns the raw cell value at the given Excel-style reference (e.g. "A1").
       #
       # @example