xlsxrb 0.1.15 → 0.1.16

data/lib/xlsxrb/elements/styles.rb

@@ -7,19 +7,20 @@ require_relative "../ooxml/utils"
 
 module Xlsxrb
   module Elements
-    # Represents the workbook stylesheet definitions (fonts, fills, borders, cellXfs, and numFmts).
-    # Inherits from Hash for backward compatibility with existing styles hash structures,
-    # while providing precomputed O(1) number format classifications.
+    # Represents the workbook stylesheet definitions (fonts, fills, borders, cellXfs, numFmts, etc.).
+    # Encapsulates stylesheet collections, item lookups, and precomputed O(1) number format classifications.
     #
     # @api public
-    class Styles < Hash #[untyped, untyped]
-      # Initializes the styles container, optionally wrapping an existing styles hash.
+    class Styles
+      EMPTY_ARRAY = [].freeze
+      EMPTY_HASH = {}.freeze
+
+      # Initializes the styles container, optionally wrapping an existing styles dictionary.
       #
       # @param initial_hash [Hash, nil] Initial styles dictionary.
       #: (?Hash[untyped, untyped]? initial_hash) -> void
       def initialize(initial_hash = nil)
-        super()
-        merge!(initial_hash) if initial_hash.is_a?(Hash)
+        @data = initial_hash.is_a?(Hash) ? initial_hash.dup : {}
         @format_codes = nil
         @format_types = nil
         @date_flags = nil
@@ -27,6 +28,402 @@ module Xlsxrb
         @time_flags = nil
       end
 
+      # Returns array of font entries from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def fonts
+        @data[:fonts] || EMPTY_ARRAY
+      end
+
+      # Returns array of fill entries from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def fills
+        @data[:fills] || EMPTY_ARRAY
+      end
+
+      # Returns array of border entries from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def borders
+        @data[:borders] || EMPTY_ARRAY
+      end
+
+      # Returns array of cell format (cellXfs) entries from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def cell_xfs
+        @data[:cell_xfs] || EMPTY_ARRAY
+      end
+
+      # Returns custom number formats as { numFmtId => formatCode }.
+      #
+      # @return [Hash<Integer, String>]
+      # @api public
+      #: () -> Hash[Integer, String]
+      def num_fmts
+        @data[:num_fmts] || EMPTY_HASH
+      end
+
+      # Returns array of differential format (dxf) entries from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def dxfs
+        @data[:dxfs] || EMPTY_ARRAY
+      end
+
+      # Returns array of cell style format (cellStyleXfs) entries from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def cell_style_xfs
+        @data[:cell_style_xfs] || EMPTY_ARRAY
+      end
+
+      # Returns array of named cell styles from the styles.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def cell_styles
+        @data[:cell_styles] || EMPTY_ARRAY
+      end
+
+      # Returns table styles configuration dictionary from the styles.
+      #
+      # @return [Hash, Array]
+      # @api public
+      #: () -> (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])
+      def table_styles
+        @data[:table_styles] || EMPTY_HASH
+      end
+
+      # Returns array of indexed color strings (ARGB hex).
+      #
+      # @return [Array<String>]
+      # @api public
+      #: () -> Array[String]
+      def indexed_colors
+        @data[:indexed_colors] || EMPTY_ARRAY
+      end
+
+      # Returns array of MRU (most recently used) color dictionaries.
+      #
+      # @return [Array<Hash>]
+      # @api public
+      #: () -> Array[Hash[Symbol, untyped]]
+      def mru_colors
+        @data[:mru_colors] || EMPTY_ARRAY
+      end
+
+      # Returns colors dictionary or palette.
+      #
+      # @return [Hash, Array]
+      # @api public
+      #: () -> (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])
+      def colors
+        @data[:colors] || EMPTY_HASH
+      end
+
+      # Looks up a font entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def font(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:fonts]&.at(id)
+      end
+
+      # Looks up a fill entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def fill(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:fills]&.at(id)
+      end
+
+      # Looks up a border entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def border(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:borders]&.at(id)
+      end
+
+      # Looks up a cell format (cellXf) entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def cell_xf(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:cell_xfs]&.at(id)
+      end
+      alias xf cell_xf
+
+      # Looks up a custom format code by numFmtId.
+      #
+      # @param id [Integer, nil]
+      # @return [String, nil]
+      # @api public
+      #: (Integer? id) -> String?
+      def num_fmt(id)
+        return nil unless id.is_a?(Integer)
+
+        @data[:num_fmts]&.[](id)
+      end
+
+      # Looks up a differential format (dxf) entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def dxf(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:dxfs]&.at(id)
+      end
+
+      # Looks up a cell style format (cellStyleXf) entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def cell_style_xf(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:cell_style_xfs]&.at(id)
+      end
+
+      # Looks up a named cell style entry by 0-based index.
+      #
+      # @param id [Integer, nil]
+      # @return [Hash, nil]
+      # @api public
+      #: (Integer? id) -> Hash[Symbol, untyped]?
+      def cell_style(id)
+        return nil unless id.is_a?(Integer) && id >= 0
+
+        @data[:cell_styles]&.at(id)
+      end
+
+      # Appends a font entry to the stylesheet and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_font(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        fonts_arr = (@data[:fonts] ||= [])
+        fonts_arr << entry
+        fonts_arr.size - 1
+      end
+
+      # Appends a fill entry to the stylesheet and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_fill(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        fills_arr = (@data[:fills] ||= [])
+        fills_arr << entry
+        fills_arr.size - 1
+      end
+
+      # Appends a border entry to the stylesheet and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_border(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        borders_arr = (@data[:borders] ||= [])
+        borders_arr << entry
+        borders_arr.size - 1
+      end
+
+      # Sets a custom number format code and returns the num_fmt_id.
+      #
+      # @param id [Integer] Format ID (custom formats typically start at 164).
+      # @param code [String] Format code pattern.
+      # @return [Integer]
+      # @api public
+      #: (Integer id, String code) -> Integer
+      def add_num_fmt(id, code)
+        raise ArgumentError, "num_fmt_id must be an Integer" unless id.is_a?(Integer)
+        raise ArgumentError, "format_code must be a String" unless code.is_a?(String)
+
+        (@data[:num_fmts] ||= {})[id] = code
+        invalidate_cache!
+        id
+      end
+
+      # Appends a cell format (cellXf) entry and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_xf(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        xfs_arr = (@data[:cell_xfs] ||= [])
+        xfs_arr << entry
+        invalidate_cache!
+        xfs_arr.size - 1
+      end
+
+      # Appends a differential format (dxf) entry and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_dxf(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        dxfs_arr = (@data[:dxfs] ||= [])
+        dxfs_arr << entry
+        dxfs_arr.size - 1
+      end
+
+      # Appends a cell style format (cellStyleXf) entry and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_cell_style_xf(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        xfs_arr = (@data[:cell_style_xfs] ||= [])
+        xfs_arr << entry
+        invalidate_cache!
+        xfs_arr.size - 1
+      end
+
+      # Appends a named cell style entry and returns its 0-based index.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_cell_style(spec = nil, **kwargs)
+        entry = (spec || kwargs).dup
+        cs_arr = (@data[:cell_styles] ||= [])
+        cs_arr << entry
+        cs_arr.size - 1
+      end
+
+      # High-level helper to compose and register a cell format (xf), adding subordinate
+      # font, fill, border, and number format definitions as needed. Returns the xf_id.
+      #
+      # @param spec [Hash, nil]
+      # @return [Integer]
+      # @api public
+      #: (?Hash[Symbol, untyped]? spec, **untyped kwargs) -> Integer
+      def add_style(spec = nil, **kwargs)
+        opts = (spec || kwargs).dup
+        font_id = opts[:font_id] || (opts[:font] ? add_font(opts[:font]) : 0)
+        fill_id = opts[:fill_id] || (opts[:fill] ? add_fill(opts[:fill]) : 0)
+        border_id = opts[:border_id] || (opts[:border] ? add_border(opts[:border]) : 0)
+        num_fmt_id = opts[:num_fmt_id] || 0
+        if opts[:num_fmt] || opts[:format_code]
+          code = (opts[:num_fmt] || opts[:format_code]).to_s
+          existing_id = num_fmts.key(code) || Ooxml::Utils::BUILTIN_NUM_FMT_CODES.key(code)
+          num_fmt_id = existing_id || add_num_fmt(next_num_fmt_id, code)
+        end
+
+        xf_spec = {
+          font_id: font_id,
+          fill_id: fill_id,
+          border_id: border_id,
+          num_fmt_id: num_fmt_id
+        }
+        xf_spec[:alignment] = opts[:alignment] if opts[:alignment]
+        xf_spec[:apply_alignment] = true if opts[:alignment] || opts[:apply_alignment]
+        xf_spec[:apply_fill] = true if opts[:fill] || opts[:apply_fill]
+        xf_spec[:apply_font] = true if opts[:font] || opts[:apply_font]
+        xf_spec[:apply_border] = true if opts[:border] || opts[:apply_border]
+        xf_spec[:apply_number_format] = true if opts[:num_fmt] || opts[:format_code] || opts[:apply_number_format]
+        xf_spec[:protection] = opts[:protection] if opts[:protection]
+        xf_spec[:apply_protection] = true if opts[:protection] || opts[:apply_protection]
+
+        add_xf(xf_spec)
+      end
+
+      # Returns true if the styles container has no registered definitions.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def empty?
+        @data.empty?
+      end
+
+      # Converts the styles container to a standard Hash.
+      #
+      # @return [Hash]
+      # @api public
+      #: () -> Hash[Symbol, untyped]
+      def to_h
+        @data.dup
+      end
+      alias to_hash to_h
+
+      # Equality check against another Styles or Hash.
+      #
+      # @param other [Object]
+      # @return [Boolean]
+      # @api public
+      #: (untyped other) -> bool
+      def ==(other)
+        if other.is_a?(Styles)
+          @data == other.to_h
+        elsif other.is_a?(Hash)
+          @data == other
+        else
+          false
+        end
+      end
+      alias eql? ==
+
+      # Computes hash code based on underlying data.
+      #
+      # @return [Integer]
+      # @api public
+      #: () -> Integer
+      def hash
+        @data.hash
+      end
+
       # Returns the format code string for a given style index.
       #
       # @param style_index [Integer, nil]
@@ -111,8 +508,8 @@ module Xlsxrb
       # @api public
       #: () -> self
       def precompute!
-        cell_xfs = self[:cell_xfs]
-        size = cell_xfs.is_a?(Array) ? cell_xfs.size : 0
+        xfs = cell_xfs
+        size = xfs.is_a?(Array) ? xfs.size : 0
 
         codes = Array.new(size)
         types = Array.new(size)
@@ -121,20 +518,20 @@ module Xlsxrb
         t_flags = Array.new(size, false)
 
         if size.positive?
-          cell_style_xfs = self[:cell_style_xfs]
-          num_fmts = self[:num_fmts] || {}
+          cs_xfs = cell_style_xfs
+          n_fmts = num_fmts
 
           size.times do |i|
-            xf = cell_xfs[i]
+            xf = xfs[i]
             next unless xf.is_a?(Hash)
 
             num_fmt_id = xf[:num_fmt_id]
-            if (num_fmt_id.nil? || num_fmt_id.zero?) && xf[:xf_id] && cell_style_xfs.is_a?(Array)
-              parent_xf = cell_style_xfs[xf[:xf_id]]
+            if (num_fmt_id.nil? || num_fmt_id.zero?) && xf[:xf_id] && cs_xfs.is_a?(Array)
+              parent_xf = cs_xfs[xf[:xf_id]]
               num_fmt_id = parent_xf[:num_fmt_id] if parent_xf.is_a?(Hash)
             end
 
-            code = num_fmt_id ? (num_fmts[num_fmt_id] || Ooxml::Utils::BUILTIN_NUM_FMT_CODES[num_fmt_id]) : nil
+            code = num_fmt_id ? (n_fmts[num_fmt_id] || Ooxml::Utils::BUILTIN_NUM_FMT_CODES[num_fmt_id]) : nil
 
             codes[i] = code
             type = NumberFormatter.format_type(code)
@@ -152,6 +549,21 @@ module Xlsxrb
         @time_flags = t_flags
         self
       end
+
+      private
+
+      def next_num_fmt_id
+        max_id = [163, *num_fmts.keys].max
+        max_id + 1
+      end
+
+      def invalidate_cache!
+        @format_codes = nil
+        @format_types = nil
+        @date_flags = nil
+        @datetime_flags = nil
+        @time_flags = nil
+      end
     end
   end
 end

data/lib/xlsxrb/elements/workbook.rb

@@ -19,12 +19,12 @@ module Xlsxrb
 
       # @param sheets [Array<Elements::Worksheet, StreamSheet>] Worksheets in the workbook.
       # @param shared_strings [Array<String>] Shared strings table.
-      # @param styles [Hash] Styles definition.
+      # @param styles [Elements::Styles, Hash] Styles definition.
       # @param unmapped_data [Hash] Additional metadata for round-tripping.
       # @param errors [Array<String>, nil] Validation errors.
       # @param defined_names [Array<Hash>, nil] Defined names list.
       # @param date1904 [Boolean] Whether the workbook uses the 1904 date system.
-      #: (?sheets: Array[Elements::Worksheet | StreamSheet], ?shared_strings: Array[String], ?styles: Hash[untyped, untyped], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?defined_names: Array[Hash[Symbol, untyped]]?, ?date1904: bool) -> void
+      #: (?sheets: Array[Elements::Worksheet | StreamSheet], ?shared_strings: Array[String], ?styles: Elements::Styles | Hash[untyped, untyped], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?defined_names: Array[Hash[Symbol, untyped]]?, ?date1904: bool) -> void
       def initialize(sheets: [], shared_strings: [], styles: {}, unmapped_data: {}, errors: nil, defined_names: nil, date1904: false)
         dns = defined_names || unmapped_data[:defined_names] || unmapped_data.dig(:facade, :defined_names) || []
         computed_errors = errors || self.class.validate(sheets)
@@ -62,15 +62,42 @@ module Xlsxrb
         errors.empty?
       end
 
+      # Returns workbook-level properties (e.g. date1904, active_tab, full_calc_on_load), or an empty hash.
+      #
+      # @return [Hash<Symbol, untyped>]
+      # @api public
+      #: () -> Hash[Symbol, untyped]
+      def workbook_properties
+        unmapped_data[:workbook_properties] || unmapped_data.dig(:facade, :workbook_properties) || {}
+      end
+
       # Returns whether the workbook uses the 1904 date system.
       #
       # @return [Boolean]
       # @api public
       #: () -> bool
       def date1904?
-        props = unmapped_data[:workbook_properties] || unmapped_data.dig(:facade, :workbook_properties)
-        props&.[](:date1904) ? true : false
+        workbook_properties[:date1904] ? true : false
+      end
+
+      # Returns the 0-based active worksheet tab index from workbookView, or nil if not set.
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def active_tab
+        workbook_properties[:active_tab]
+      end
+
+      # Returns whether Excel is instructed to perform a full recalculation when loading the workbook.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def full_calc_on_load?
+        workbook_properties[:full_calc_on_load] ? true : false
       end
+      alias full_calc_on_load full_calc_on_load?
 
       # Returns core document properties (e.g. title, creator, created), or an empty hash.
       #

data/lib/xlsxrb/elements/worksheet.rb

@@ -17,7 +17,7 @@ module Xlsxrb
     class Worksheet
       [Enumerable, CoordinateAccess].each { |m| include m }
 
-      attr_reader :name, :rows, :columns, :charts, :conditional_formatting, :data_validations, :unmapped_data, :errors, :state, :hyperlinks, :comments, :images, :styles, :date1904, :print_area, :print_titles, :sparkline_groups, :merged_cells, :auto_filter, :tables, :shapes, :freeze_pane, :page_setup, :page_margins, :header_footer, :print_options, :sheet_protection, :sheet_view, :sheet_properties, :sheet_format, :row_breaks, :col_breaks, :protected_ranges, :cell_watches
+      attr_reader :name, :rows, :columns, :charts, :conditional_formatting, :data_validations, :unmapped_data, :errors, :state, :hyperlinks, :comments, :images, :styles, :date1904, :print_area, :print_titles, :sparkline_groups, :merged_cells, :auto_filter, :tables, :shapes, :freeze_pane, :page_setup, :page_margins, :header_footer, :print_options, :sheet_protection, :sheet_view, :sheet_properties, :sheet_format, :row_breaks, :col_breaks, :protected_ranges, :cell_watches, :selection
       attr_writer :dimension
       alias conditional_formats conditional_formatting
 
@@ -59,8 +59,9 @@ module Xlsxrb
       # @param col_breaks [Array<Integer | Hash>] Explicit page column breaks.
       # @param protected_ranges [Array<Hash>] Protected range definitions.
       # @param cell_watches [Array<String>] Watched cell references.
-      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?conditional_formatting: Array[Hash[Symbol, untyped]]?, ?data_validations: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?conditional_formats: Array[Hash[Symbol, untyped]]?, ?state: Symbol, ?hyperlinks: Hash[String, untyped], ?comments: Array[Hash[Symbol, untyped]], ?images: Array[Elements::Image], ?styles: Hash[untyped, untyped]?, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool, ?print_area: String?, ?print_titles: Hash[Symbol, untyped]?, ?sparkline_groups: Array[Hash[Symbol, untyped]], ?merged_cells: Array[String], ?auto_filter: String?, ?tables: Array[Hash[Symbol, untyped]], ?shapes: Array[Hash[Symbol, untyped]], ?freeze_pane: Hash[Symbol, untyped]?, ?page_setup: Hash[Symbol, untyped], ?page_margins: Hash[Symbol, untyped]?, ?header_footer: Hash[Symbol, untyped], ?print_options: Hash[Symbol, untyped], ?sheet_protection: Hash[Symbol, untyped]?, ?sheet_view: Hash[Symbol, untyped], ?sheet_properties: Hash[Symbol, untyped], ?sheet_format: Hash[Symbol, untyped], ?row_breaks: Array[untyped], ?col_breaks: Array[untyped], ?protected_ranges: Array[Hash[Symbol, untyped]], ?cell_watches: Array[String]) -> void
-      def initialize(name:, rows: [], columns: [], charts: [], conditional_formatting: nil, data_validations: [], unmapped_data: {}, errors: nil, conditional_formats: nil, state: :visible, hyperlinks: {}, comments: [], images: [], styles: nil, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, print_area: nil, print_titles: nil, sparkline_groups: [], merged_cells: [], auto_filter: nil, tables: [], shapes: [], freeze_pane: nil, page_setup: {}, page_margins: nil, header_footer: {}, print_options: {}, sheet_protection: nil, sheet_view: {}, sheet_properties: {}, sheet_format: {}, row_breaks: [], col_breaks: [], protected_ranges: [], cell_watches: [])
+      # @param selection [Hash, Array<Hash>, nil] Active cell and selection settings.
+      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?conditional_formatting: Array[Hash[Symbol, untyped]]?, ?data_validations: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?conditional_formats: Array[Hash[Symbol, untyped]]?, ?state: Symbol, ?hyperlinks: Hash[String, untyped], ?comments: Array[Hash[Symbol, untyped]], ?images: Array[Elements::Image], ?styles: (Elements::Styles | Hash[untyped, untyped])?, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool, ?print_area: String?, ?print_titles: Hash[Symbol, untyped]?, ?sparkline_groups: Array[Hash[Symbol, untyped]], ?merged_cells: Array[String], ?auto_filter: String?, ?tables: Array[Hash[Symbol, untyped]], ?shapes: Array[Hash[Symbol, untyped]], ?freeze_pane: Hash[Symbol, untyped]?, ?page_setup: Hash[Symbol, untyped], ?page_margins: Hash[Symbol, untyped]?, ?header_footer: Hash[Symbol, untyped], ?print_options: Hash[Symbol, untyped], ?sheet_protection: Hash[Symbol, untyped]?, ?sheet_view: Hash[Symbol, untyped], ?sheet_properties: Hash[Symbol, untyped], ?sheet_format: Hash[Symbol, untyped], ?row_breaks: Array[untyped], ?col_breaks: Array[untyped], ?protected_ranges: Array[Hash[Symbol, untyped]], ?cell_watches: Array[String], ?selection: (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])?) -> void
+      def initialize(name:, rows: [], columns: [], charts: [], conditional_formatting: nil, data_validations: [], unmapped_data: {}, errors: nil, conditional_formats: nil, state: :visible, hyperlinks: {}, comments: [], images: [], styles: nil, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, print_area: nil, print_titles: nil, sparkline_groups: [], merged_cells: [], auto_filter: nil, tables: [], shapes: [], freeze_pane: nil, page_setup: {}, page_margins: nil, header_footer: {}, print_options: {}, sheet_protection: nil, sheet_view: {}, sheet_properties: {}, sheet_format: {}, row_breaks: [], col_breaks: [], protected_ranges: [], cell_watches: [], selection: nil)
         @name = name
         @rows = (rows || []).freeze
         @columns = (columns || []).freeze
@@ -101,6 +102,7 @@ module Xlsxrb
         @col_breaks = (col_breaks || []).freeze
         @protected_ranges = (protected_ranges || unmapped_data[:protected_ranges] || unmapped_data.dig(:facade, :protected_ranges) || []).freeze
         @cell_watches = (cell_watches || unmapped_data[:cell_watches] || unmapped_data.dig(:facade, :cell_watches) || []).freeze
+        @selection = selection&.freeze
       end
 
       # Returns whether trailing empty rows are omitted during iteration.
@@ -362,6 +364,15 @@ module Xlsxrb
         @state == :visible
       end
 
+      # Returns whether the worksheet is very hidden (:very_hidden).
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def very_hidden?
+        @state == :very_hidden
+      end
+
       # Returns hyperlink metadata for the given cell reference, or nil.
       #
       # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
@@ -539,6 +550,7 @@ module Xlsxrb
         new_col_breaks = changes.key?(:col_breaks) ? changes[:col_breaks] : col_breaks
         new_protected_ranges = changes.key?(:protected_ranges) ? changes[:protected_ranges] : protected_ranges
         new_cell_watches = changes.key?(:cell_watches) ? changes[:cell_watches] : cell_watches
+        new_selection = changes.key?(:selection) ? changes[:selection] : selection
 
         self.class.new(
           name: new_name,
@@ -575,7 +587,8 @@ module Xlsxrb
           row_breaks: new_row_breaks,
           col_breaks: new_col_breaks,
           protected_ranges: new_protected_ranges,
-          cell_watches: new_cell_watches
+          cell_watches: new_cell_watches,
+          selection: new_selection
         )
       end
 
@@ -616,7 +629,8 @@ module Xlsxrb
           sheet_properties: sheet_properties,
           sheet_format: sheet_format,
           row_breaks: row_breaks,
-          col_breaks: col_breaks
+          col_breaks: col_breaks,
+          selection: selection
         }
       end
 
@@ -634,7 +648,8 @@ module Xlsxrb
           header_footer == other.header_footer && print_options == other.print_options &&
           sheet_protection == other.sheet_protection && sheet_view == other.sheet_view &&
           sheet_properties == other.sheet_properties && sheet_format == other.sheet_format &&
-          row_breaks == other.row_breaks && col_breaks == other.col_breaks
+          row_breaks == other.row_breaks && col_breaks == other.col_breaks &&
+          selection == other.selection
       end
       alias eql? ==
 
@@ -644,7 +659,7 @@ module Xlsxrb
           self.class, name, rows, columns, charts, conditional_formatting, data_validations,
           state, hyperlinks, comments, merged_cells, auto_filter, tables, shapes, freeze_pane,
           page_setup, page_margins, header_footer, print_options, sheet_protection, sheet_view,
-          sheet_properties, sheet_format, row_breaks, col_breaks
+          sheet_properties, sheet_format, row_breaks, col_breaks, selection
         ].hash
       end
 

data/lib/xlsxrb/ooxml/cfb.rb

@@ -100,9 +100,16 @@ module Xlsxrb
           raise Xlsxrb::Error, "CFB file is too small" if @data.bytesize < 512
 
           _, major_ver = @data[0x18, 4].unpack("v2")
+          raise Xlsxrb::Error, "Unsupported CFB major version: #{major_ver}" unless [3, 4].include?(major_ver)
+
           @major_version = major_ver
           @sector_shift = @data[0x1E, 2].unpack1("v")
           @mini_sector_shift = @data[0x20, 2].unpack1("v")
+
+          expected_shift = @major_version == 4 ? 12 : 9
+          raise Xlsxrb::Error, "Invalid CFB sector shift in header: #{@sector_shift}" unless @sector_shift == expected_shift
+          raise Xlsxrb::Error, "Invalid CFB mini sector shift in header: #{@mini_sector_shift}" unless @mini_sector_shift == 6
+
           @sector_size = 1 << @sector_shift
           @mini_sector_size = 1 << @mini_sector_shift
 
@@ -123,6 +130,9 @@ module Xlsxrb
         end
 
         def read_sector(sector_id)
+          max_sectors = (@data.bytesize - 512) / @sector_size
+          return "".b if sector_id.negative? || sector_id >= max_sectors
+
           offset = sector_offset(sector_id)
           @data[offset, @sector_size] || "".b
         end