hakumi_components 0.1.3.pre

data/app/components/hakumi/table/component.rb

@@ -0,0 +1,957 @@
+# frozen_string_literal: true
+
+module Hakumi
+  module Table
+    # A complex Table component supporting sorting, filtering, selection, expansion, and editing.
+    class Component < Hakumi::BaseComponent
+      include Concerns::Columns
+
+      # @group Configuration Constants
+      SIZES = %i[default middle small].freeze
+      ROW_SELECTION_TYPES = %i[checkbox radio].freeze
+      SORT_DIRECTIONS = %i[ascend descend].freeze
+      FIXED_SIDES = %i[left right].freeze
+      RESPONSIVE_BREAKPOINTS = %i[xs sm md lg xl xxl].freeze
+      EDITABLE_MODES = %i[cell row].freeze
+      EDITABLE_TRIGGERS = %i[click dblclick].freeze
+      EDITABLE_INPUT_TYPES = %i[text number textarea select].freeze
+      ROW_BUTTON_ACTIONS = %i[edit save cancel].freeze
+
+      # @group Slot Definitions
+      SELECTION_COLUMN = :selection_column
+      EXPAND_COLUMN = :expand_column
+
+      renders_many :columns, types: {
+        column: {
+          renders: lambda do |title:, data_index: nil, key: nil, align: nil, width: nil, ellipsis: false,
+                              sorter: nil, sort_directions: nil, sort_order: nil, default_sort_order: nil,
+                              filters: nil, filter_multiple: true, filtered_value: nil, default_filtered_value: nil,
+                              filter_mode: nil, filter_search: nil, hidden: false, on_cell: nil, class_name: nil,
+                              **options, &block|
+            Hakumi::Table::Column::Component.new(
+              title: title,
+              data_index: data_index,
+              key: key,
+              align: align,
+              width: width,
+              ellipsis: ellipsis,
+              sorter: sorter,
+              sort_directions: sort_directions,
+              sort_order: sort_order,
+              default_sort_order: default_sort_order,
+              filters: filters,
+              filter_multiple: filter_multiple,
+              filtered_value: filtered_value,
+              default_filtered_value: default_filtered_value,
+              filter_mode: filter_mode,
+              filter_search: filter_search,
+              hidden: hidden,
+              on_cell: on_cell,
+              class_name: class_name,
+              **options,
+              &block
+            )
+          end,
+          as: :column
+        },
+        group: {
+          renders: lambda do |title:, key: nil, align: nil, width: nil, hidden: false, **options, &block|
+            Hakumi::Table::ColumnGroup::Component.new(
+              title: title,
+              key: key,
+              align: align,
+              width: width,
+              hidden: hidden,
+              **options,
+              &block
+            )
+          end,
+          as: :group
+        }
+      }
+
+      # Extracts local variables for the controller from the params hash.
+      # @param params [Hash] parameters from the request
+      # @return [Hash] hash of local variables
+      def self.extract_controller_locals(params)
+        {
+          columns: parse_json_param(params[:columns]),
+          data_source: parse_json_param(params[:data_source]),
+          row_key: params[:row_key],
+          size: params[:size],
+          bordered: params[:bordered],
+          title: params[:title],
+          footer: params[:footer],
+          row_selection: params[:row_selection],
+          expandable: params[:expandable],
+          pagination: params[:pagination],
+          summary: params[:summary],
+          empty_text: params[:empty_text],
+          sort_directions: params[:sort_directions],
+          filter_on_close: params[:filter_on_close],
+          filter_mode: params[:filter_mode],
+          filter_search: params[:filter_search],
+          children_column_name: params[:children_column_name],
+          indent_size: params[:indent_size],
+          scroll: params[:scroll],
+          sticky: params[:sticky],
+          row_class_name: params[:row_class_name],
+          editable: parse_json_param(params[:editable])
+        }
+      end
+
+      def self.parse_json_param(value)
+        return value unless value.is_a?(String)
+
+        JSON.parse(value)
+      rescue JSON::ParserError
+        value
+      end
+
+      def initialize(
+        columns: nil,
+        data_source: [],
+        row_key: :key,
+        size: :default,
+        bordered: false,
+        title: nil,
+        footer: nil,
+        row_selection: nil,
+        expandable: nil,
+        pagination: nil,
+        summary: nil,
+        empty_text: nil,
+        sort_directions: SORT_DIRECTIONS,
+        filter_on_close: true,
+        filter_mode: :menu,
+        filter_search: false,
+        children_column_name: :children,
+        indent_size: 16,
+        scroll: nil,
+        sticky: false,
+        row_class_name: nil,
+        editable: nil,
+        row_drag: nil,
+        column_drag: false,
+        data_url: nil,
+        **html_options
+      )
+        @columns_data = columns
+        @data_source = data_source
+        @row_key = row_key
+        @size = size
+        @bordered = bordered
+        @title = title
+        @footer = footer
+        @row_selection = row_selection
+        @expandable = expandable
+        @pagination = pagination
+        @summary = summary
+        @empty_text = empty_text
+        @sort_directions = Array(sort_directions).presence || SORT_DIRECTIONS
+        @filter_on_close = filter_on_close
+        @filter_mode = filter_mode
+        @filter_search = filter_search
+        @children_column_name = children_column_name
+        @indent_size = indent_size
+        @scroll = normalize_scroll(scroll)
+        @scroll_x = @scroll&.dig(:x)
+        @scroll_y = @scroll&.dig(:y)
+        @sticky = cast_boolean(sticky)
+        @row_class_name = row_class_name
+        @editable = normalize_editable(editable)
+        @row_drag = normalize_row_drag(row_drag)
+        @column_drag = cast_boolean(column_drag)
+        @data_url = data_url
+        @html_options = html_options
+
+        normalize_row_selection!
+        normalize_expandable!
+
+        validate_props!
+      end
+
+      attr_reader :row_selection, :expandable, :pagination, :summary
+
+      def table_classes
+        class_names(
+          "table",
+          {
+            size: @size,
+            bordered: @bordered,
+            empty: display_rows.empty?,
+            sticky: @sticky,
+            scroll_x: @scroll_x.present?,
+            scroll_y: @scroll_y.present?,
+            fixed: fixed_columns?
+          },
+          @html_options[:class]
+        )
+      end
+
+      def table_container_attributes
+        attrs = {
+          class: container_classes,
+          data: {
+            "hakumi--table-target": "scrollContainer"
+          }
+        }
+        styles = scroll_styles
+        attrs[:style] = styles if styles.present?
+        attrs
+      end
+
+      def table_attributes
+        attrs = { class: "hakumi-table-table" }
+        attrs[:style] = table_style if table_style.present?
+        attrs
+      end
+
+      def container_classes
+        class_names(
+          "table-container",
+          {
+            scroll_x: @scroll_x.present?,
+            scroll_y: @scroll_y.present?
+          }
+        )
+      end
+
+      def wrapper_attributes
+        data_attributes = {
+          controller: "hakumi--table",
+          "hakumi--table-selection-type-value": @row_selection_type,
+          "hakumi--table-selected-row-keys-value": @selected_row_keys.to_json,
+          "hakumi--table-preserve-selected-row-keys-value": @row_selection_preserve,
+          "hakumi--table-sort-directions-value": @sort_directions.join(","),
+          "hakumi--table-filter-on-close-value": @filter_on_close,
+          "hakumi--table-filter-mode-value": @filter_mode,
+          "hakumi--table-filter-search-value": @filter_search
+        }
+        if (editable_json = editable_config_json)
+          data_attributes["hakumi--table-editable-config-value"] = editable_json
+        end
+
+        # Server-side pagination/sorting configuration
+        if @pagination.is_a?(Hash)
+          if @pagination[:href]
+            data_attributes["hakumi--table-href-value"] = @pagination[:href]
+            data_attributes["hakumi--table-server-side-value"] = true
+
+            # Add pagination state for preserve_params (sort state from columns)
+            data_attributes["pagination-state"] = true
+            current_sort = current_sort_state
+            if current_sort
+              data_attributes["sort-field"] = current_sort[:field]
+              data_attributes["sort-order"] = current_sort[:order]
+            end
+          end
+          if @pagination[:turbo_frame]
+            data_attributes["hakumi--table-turbo-frame-value"] = @pagination[:turbo_frame]
+          end
+          if @pagination[:sort_field_param]
+            data_attributes["hakumi--table-sort-field-param-value"] = @pagination[:sort_field_param]
+          end
+          if @pagination[:sort_order_param]
+            data_attributes["hakumi--table-sort-order-param-value"] = @pagination[:sort_order_param]
+          end
+        end
+
+        # Drag sorting configuration
+        if @row_drag
+          data_attributes["hakumi--table-row-drag-value"] = @row_drag[:enabled]
+          data_attributes["hakumi--table-row-drag-handle-value"] = @row_drag[:handle]
+        end
+        if @column_drag
+          data_attributes["hakumi--table-column-drag-value"] = true
+        end
+
+        # AJAX data loading configuration
+        if @data_url
+          data_attributes["hakumi--table-data-url-value"] = @data_url
+          data_attributes["hakumi--table-columns-config-value"] = columns_config_json
+          if @pagination.is_a?(Hash)
+            data_attributes["hakumi--table-page-size-value"] = @pagination[:page_size] || 10
+          end
+        end
+
+        base = {
+          class: table_classes,
+          data: data_attributes
+        }
+        merge_attributes(base, @html_options)
+      end
+
+      def header_rows
+        @header_rows ||= build_header_rows(normalized_columns)
+      end
+
+      def display_rows
+        @display_rows ||= build_display_rows
+      end
+
+      def row_key_for(row, index)
+        case @row_key
+        when Proc
+          @row_key.call(row)
+        when Symbol, String
+          value_from_row(row, @row_key)
+        else
+          row.respond_to?(:[]) ? row[@row_key] : index
+        end
+      end
+
+      def row_selected?(row_key)
+        @selected_row_keys.include?(row_key.to_s)
+      end
+
+      def row_classes(row, row_index, row_key)
+        classes = [ "hakumi-table-row" ]
+        classes << "hakumi-table-row-selected" if row_selected?(row_key)
+        classes << "hakumi-table-row-odd" if row_index.odd?
+        if @row_class_name.respond_to?(:call)
+          classes << @row_class_name.call(row, row_index)
+        elsif @row_class_name.is_a?(String)
+          classes << @row_class_name
+        end
+        classes.compact.join(" ")
+      end
+
+      def cell_attributes(column, row, row_index, depth, row_key = nil, raw_value = nil)
+        attrs = {
+          class: cell_classes(column),
+          data: {
+            column_key: column[:key],
+            row_key: row_key,
+            sort_value: extract_sort_value(column, row, raw_value),
+            value: raw_value
+          }.compact
+        }
+        attrs[:style] = "text-align: #{column[:align]};" if column[:align]
+        attrs[:style] = [ attrs[:style], "width: #{column[:width]};" ].compact.join(" ") if column[:width]
+        if column[:on_cell].respond_to?(:call)
+          cell_attrs = column[:on_cell].call(row, row_index)
+          attrs[:colspan] = cell_attrs[:colspan] if cell_attrs
+          attrs[:rowspan] = cell_attrs[:rowspan] if cell_attrs
+          attrs[:class] = [ attrs[:class], cell_attrs[:class] ].compact.join(" ")
+          attrs[:style] = [ attrs[:style], cell_attrs[:style] ].compact.join(" ")
+        end
+        if depth.positive? && column == first_data_column
+          attrs[:style] = [ attrs[:style], "padding-left: #{depth * @indent_size}px;" ].compact.join(" ")
+        end
+        apply_editable_attributes!(attrs, column)
+        apply_should_cell_update_attributes!(attrs, column)
+        apply_fixed_column_attributes!(attrs, column, header: false)
+        attrs
+      end
+
+      def header_cell_attributes(column, col_span:, row_span:)
+        attrs = { class: header_cell_classes(column) }
+        attrs[:colspan] = col_span if col_span > 1
+        attrs[:rowspan] = row_span if row_span > 1
+        attrs[:style] = "text-align: #{column[:align]};" if column[:align]
+        attrs[:style] = [ attrs[:style], "width: #{column[:width]};" ].compact.join(" ") if column[:width]
+        apply_fixed_column_attributes!(attrs, column, header: true)
+        attrs
+      end
+
+      def cell_content(column, row, row_index, raw_value = nil)
+        return selection_cell(row, row_index) if column[:selection]
+        return expand_cell(row, row_index) if column[:expand]
+        return { drag_handle: true } if column[:drag_handle]
+
+        value = raw_value
+        value = value_from_row(row, column[:data_index]) if value.nil? && column[:data_index]
+        if column[:render].respond_to?(:call)
+          column[:render].call(value, row, row_index)
+        else
+          value
+        end
+      end
+
+      def render_cell_display(column, content, raw_value, row, row_index)
+        config = ellipsis_config(column)
+
+        value_fragment = if content.is_a?(ViewComponent::Base)
+          render(content)
+        else
+          content
+        end
+        value_fragment = raw_value if value_fragment.nil?
+
+        span_options = { class: "hakumi-table-cell-content" }
+        title_text = ellipsis_title(config, raw_value, value_fragment)
+        span_options[:title] = title_text if title_text.present?
+
+        display_value = value_fragment.is_a?(Numeric) ? value_fragment.to_s : value_fragment
+        inner = tag.span(**span_options) { display_value }
+
+        tooltip_component = ellipsis_tooltip_component(config, raw_value, row, row_index)
+        tooltip_component ? render(tooltip_component) { inner } : inner
+      end
+
+      def empty_state
+        if @empty_text.present?
+          if @empty_text.is_a?(ViewComponent::Base)
+            render(@empty_text)
+          elsif @empty_text.respond_to?(:call)
+            instance_exec(&@empty_text)
+          else
+            @empty_text
+          end
+        else
+          render(Hakumi::Empty::Component.new)
+        end
+      end
+
+      def pagination_component
+        return nil unless @pagination
+        return nil if @data_url # AJAX mode uses ajax_pagination_component
+        return @pagination if @pagination.is_a?(ViewComponent::Base)
+
+        options = @pagination.is_a?(Hash) ? @pagination : {}
+        normalized = normalize_pagination_options(options)
+        return nil unless normalized
+
+        Hakumi::Pagination::Component.new(**normalized)
+      end
+
+      def ajax_pagination_component
+        return nil unless @data_url && @pagination
+
+        options = @pagination.is_a?(Hash) ? @pagination : {}
+        Hakumi::Pagination::Component.new(
+          current: 1,
+          page_size: options[:page_size] || 10,
+          total: 0,
+          show_size_changer: options[:show_size_changer] != false
+        )
+      end
+
+      def summary_content
+        return nil unless @summary
+        return @summary.call(display_rows.map { |row| row[:row] }) if @summary.respond_to?(:call)
+
+        @summary
+      end
+
+      def scroll_styles
+        styles = []
+        if @scroll_x
+          styles << "overflow-x: auto"
+        end
+        if @scroll_y
+          styles << "max-height: #{dimension_to_css(@scroll_y)}"
+          styles << "overflow-y: auto"
+        end
+        styles.join("; ")
+      end
+
+      def table_style
+        return nil unless @scroll_x
+
+        "min-width: #{dimension_to_css(@scroll_x)}"
+      end
+
+      def selection_column?
+        @row_selection.present?
+      end
+
+      def selection_actions?
+        @row_selection.present? && @row_selection_selections
+      end
+
+      def selection_all_enabled?
+        @row_selection_type == :checkbox
+      end
+
+      def expanded_row?(row_key)
+        @expanded_row_keys.include?(row_key.to_s)
+      end
+
+      def expanded_row_content(row, row_index)
+        return nil unless @expandable&.dig(:expanded_row_render).respond_to?(:call)
+
+        @expandable[:expanded_row_render].call(row, row_index)
+      end
+
+      def header_filter_options(column)
+        Array(column[:filters])
+      end
+
+      def column_sortable?(column)
+        column[:sorter].present?
+      end
+
+      def column_filterable?(column)
+        column[:filters].present?
+      end
+
+      def column_filter_multiple?(column)
+        column[:filter_multiple] != false
+      end
+
+      def default_filtered_values(column)
+        Array(column[:filtered_value] || column[:default_filtered_value])
+      end
+
+      def default_sort_order(column)
+        column[:sort_order] || column[:default_sort_order]
+      end
+
+      def current_sort_state
+        sorted_column = leaf_columns.find { |col| default_sort_order(col).present? }
+        return nil unless sorted_column
+
+        {
+          field: sorted_column[:key]&.to_s || sorted_column[:data_index]&.to_s,
+          order: default_sort_order(sorted_column)
+        }
+      end
+
+      def header_cell_classes(column)
+        classes = [ "hakumi-table-cell", "hakumi-table-header-cell" ]
+        classes.concat(responsive_classes(column))
+        classes << "hakumi-table-cell-ellipsis" if ellipsis_config(column)
+        classes << "hakumi-table-cell-sortable" if column_sortable?(column)
+        classes << "hakumi-table-cell-filterable" if column_filterable?(column)
+        classes << column[:class_name] if column[:class_name]
+        classes.compact.join(" ")
+      end
+
+      def cell_classes(column)
+        classes = [ "hakumi-table-cell" ]
+        classes.concat(responsive_classes(column))
+        classes << "hakumi-table-cell-ellipsis" if ellipsis_config(column)
+        classes << "hakumi-table-cell-selection" if column[:selection]
+        classes << "hakumi-table-cell-expand" if column[:expand]
+        classes << column[:class_name] if column[:class_name]
+        classes.compact.join(" ")
+      end
+
+      def selection_header_state
+        total = display_rows.size
+        selected = @selected_row_keys.size
+        {
+          checked: total.positive? && selected == total,
+          indeterminate: selected.positive? && selected < total
+        }
+      end
+
+      def fixed_columns?
+        fixed_offsets.present?
+      end
+
+      private
+
+      def normalize_row_selection!
+        @selected_row_keys = Array(@row_selection&.dig(:selected_row_keys) || @row_selection&.dig(:selectedRowKeys)).map(&:to_s)
+        @row_selection_type = @row_selection.present? ? (@row_selection&.dig(:type)&.to_sym || :checkbox) : nil
+        @row_selection_preserve = @row_selection&.dig(:preserve_selected_row_keys) || @row_selection&.dig(:preserveSelectedRowKeys) || false
+        @row_selection_selections = @row_selection&.dig(:selections)
+      end
+
+      def normalize_expandable!
+        @expanded_row_keys = Array(@expandable&.dig(:expanded_row_keys) || @expandable&.dig(:expandedRowKeys) || @expandable&.dig(:default_expanded_row_keys) || @expandable&.dig(:defaultExpandedRowKeys)).map(&:to_s)
+        return unless @expandable.present?
+
+        @expandable[:show_expand_column] = true if @expandable[:show_expand_column].nil?
+      end
+
+      def validate_props!
+        validate_inclusion!(:size, SIZES)
+        validate_inclusion!(:row_selection_type, ROW_SELECTION_TYPES) if @row_selection.present?
+        @sort_directions.each do |direction|
+          raise ArgumentError, "sort_directions must be one of #{SORT_DIRECTIONS.inspect}" unless SORT_DIRECTIONS.include?(direction)
+        end
+      end
+
+      def normalize_scroll(value)
+        return nil unless value.is_a?(Hash)
+
+        {
+          x: dimension_to_css(value[:x]),
+          y: dimension_to_css(value[:y])
+        }.compact.presence
+      end
+
+      def cast_boolean(value)
+        ActiveModel::Type::Boolean.new.cast(value)
+      end
+
+      def fixed_offsets
+        @fixed_offsets ||= {}
+      end
+
+      def apply_fixed_column_attributes!(attrs, column, header: false)
+        info = fixed_offsets[column[:key]]
+        return unless info
+
+        attrs[:class] = [ attrs[:class], "hakumi-table-cell-fixed", "hakumi-table-cell-fixed-#{info[:side]}" ].compact.join(" ")
+
+        style_parts = []
+        style_parts << attrs[:style] if attrs[:style].present?
+        style_parts << "position: sticky"
+        style_parts << "#{info[:side]}: #{info[:offset]}px"
+        style_parts << "z-index: #{header ? 3 : 2}"
+        attrs[:style] = style_parts.compact.join("; ")
+
+        attrs[:data] ||= {}
+        attrs[:data][:fixed] = info[:side]
+      end
+
+      def apply_editable_attributes!(attrs, column)
+        payload = cell_editable_payload(column)
+        return unless payload
+
+        attrs[:class] = [ attrs[:class], "hakumi-table-cell-editable" ].compact.join(" ")
+        attrs[:data] ||= {}
+        attrs[:data][:editable] = true
+        attrs[:data][:editableConfig] = payload.to_json
+        attrs[:data][:action] = "click->hakumi--table#editCell"
+      end
+
+      def compute_fixed_offsets(leaf_columns)
+        @fixed_offsets = {}
+        return if leaf_columns.blank?
+
+        left_offset = 0
+        leaf_columns.each do |column|
+          next unless column[:fixed] == :left
+
+          width = fixed_column_width!(column)
+          @fixed_offsets[column[:key]] = { side: :left, offset: left_offset }
+          left_offset += width
+        end
+
+        right_offset = 0
+        leaf_columns.reverse_each do |column|
+          next unless column[:fixed] == :right
+
+          width = fixed_column_width!(column)
+          @fixed_offsets[column[:key]] = { side: :right, offset: right_offset }
+          right_offset += width
+        end
+      end
+
+      def fixed_column_width!(column)
+        width = numeric_width(column[:width])
+        return width if width&.positive?
+
+        raise ArgumentError, "Column #{column[:key] || column[:data_index] || column[:title]} must define a pixel width when fixed"
+      end
+
+      def numeric_width(value)
+        return value.to_f if value.is_a?(Numeric)
+        return nil unless value.is_a?(String)
+
+        stripped = value.strip
+        return stripped.to_f if stripped.match?(/\A[\d.]+\z/)
+
+        match = stripped.match(/\A([\d.]+)px\z/i)
+        match ? match[1].to_f : nil
+      end
+
+      def ellipsis_config(column)
+        column[:ellipsis]
+      end
+
+      def normalize_ellipsis_option(option)
+        return nil if option.nil? || option == false
+
+        if option == true
+          { show_title: true }
+        elsif option.is_a?(Hash)
+          normalized = option.deep_symbolize_keys
+          normalized[:tooltip] = normalize_ellipsis_tooltip_option(normalized[:tooltip])
+          normalized.compact.presence
+        else
+          { tooltip: normalize_ellipsis_tooltip_option(option) }
+        end
+      end
+
+      def normalize_ellipsis_tooltip_option(option)
+        return nil if option.nil? || option == false
+        return {} if option == true
+        return { title: option } if option.is_a?(String)
+        return option.deep_symbolize_keys if option.is_a?(Hash)
+
+        nil
+      end
+
+      def ellipsis_title(config, raw_value, content_fragment)
+        return nil unless config&.dig(:show_title)
+
+        value = raw_value.presence || content_fragment
+        value = value.to_s if value.respond_to?(:to_s)
+        value.present? ? value : nil
+      end
+
+      def ellipsis_tooltip_component(config, raw_value, row, row_index)
+        tooltip = config&.dig(:tooltip)
+        return nil unless tooltip
+
+        options = tooltip.deep_dup
+        title = options.delete(:title)
+        title ||= raw_value
+        title = title.call(row, row_index) if title.respond_to?(:call)
+        title = title.to_s if title.respond_to?(:to_s)
+        return nil if title.blank?
+
+        Hakumi::Tooltip::Component.new(**{ title: title }.merge(options))
+      end
+
+      def responsive_classes(column)
+        responsive = column[:responsive]
+        return [] unless responsive.present?
+
+        responsive.map do |breakpoint|
+          "hakumi-table-col-show-#{breakpoint}"
+        end.prepend("hakumi-table-col-responsive")
+      end
+
+      def extract_sort_value(column, row, raw_value)
+        sort_value_config = column[:sort_value]
+        return raw_value unless sort_value_config
+
+        if sort_value_config.respond_to?(:call)
+          sort_value_config.call(raw_value, row)
+        elsif sort_value_config.is_a?(Symbol) || sort_value_config.is_a?(String)
+          row[sort_value_config.to_sym]
+        else
+          raw_value
+        end
+      end
+
+      def normalize_responsive_breakpoints(value)
+        return nil unless value.present?
+
+        Array(value).map do |breakpoint|
+          sym = breakpoint.to_s.downcase.to_sym
+          sym if RESPONSIVE_BREAKPOINTS.include?(sym)
+        end.compact.presence
+      end
+
+      def normalize_pagination_options(options)
+        normalized = options.symbolize_keys
+
+        total = normalized[:total] || (@data_source.respond_to?(:size) ? @data_source.size : display_rows.size)
+        current = normalized[:current] || 1
+        page_size = normalized[:page_size] || 10
+
+        result = {
+          total: total,
+          current: current,
+          page_size: page_size
+        }
+
+        %i[
+          size align simple show_size_changer show_quick_jumper
+          page_size_options page_param per_page_param href turbo_frame turbo_action
+          show_total hide_on_single_page prev_text next_text preserve_params
+        ].each do |key|
+          result[key] = normalized[key] if normalized.key?(key)
+        end
+
+        result
+      end
+
+      def columns_data
+        return Array(@columns_data) if @columns_data.present?
+        return columns.map(&:to_h) if columns.any?
+
+        []
+      end
+
+      def build_display_rows
+        rows = Array(@data_source)
+        rows = flatten_tree(rows)
+        apply_pagination(rows)
+      end
+
+      def flatten_tree(rows, depth = 0)
+        rows.flat_map do |row|
+          children = row.respond_to?(:[]) ? row[@children_column_name] || row[@children_column_name.to_s] : nil
+          current = { row: row, depth: depth }
+          if children.respond_to?(:each)
+            [ current, *flatten_tree(children, depth + 1) ]
+          else
+            [ current ]
+          end
+        end
+      end
+
+      def apply_pagination(rows)
+        return rows unless @pagination.is_a?(Hash)
+
+        # Skip client-side pagination if data is already paginated server-side
+        return rows if @pagination[:server_side] || @pagination[:href]
+
+        current = @pagination[:current] || @pagination[:page] || 1
+        page_size = @pagination[:page_size] || @pagination[:pageSize] || 10
+        start = (current.to_i - 1) * page_size.to_i
+        rows.slice(start, page_size.to_i) || []
+      end
+
+      def value_from_row(row, data_index)
+        return nil if data_index.nil?
+
+        if row.is_a?(Hash)
+          return row[data_index] if row.key?(data_index)
+          return row[data_index.to_s] if row.key?(data_index.to_s)
+        end
+
+        return row.public_send(data_index) if row.respond_to?(data_index)
+
+        nil
+      end
+
+      def selection_cell(row, row_index)
+        row_key = row_key_for(row, row_index)
+        {
+          type: @row_selection_type,
+          row_key: row_key,
+          checked: row_selected?(row_key)
+        }
+      end
+
+      def expand_cell(row, row_index)
+        row_key = row_key_for(row, row_index)
+        {
+          row_key: row_key,
+          expanded: expanded_row?(row_key)
+        }
+      end
+
+      # Normalizes the table-level editable configuration.
+      # Accepts boolean, symbol (:cell or :row), or hash with options.
+      # Returns nil if editing is disabled, or a hash with normalized options.
+      #
+      # @param value [Boolean, Symbol, Hash, nil] editable configuration
+      # @return [Hash, nil] normalized configuration
+      def normalize_editable(value)
+        return nil if value.nil? || value == false
+
+        case value
+        when true
+          { mode: :cell, trigger: :click }
+        when Symbol
+          mode = EDITABLE_MODES.include?(value) ? value : :cell
+          { mode: mode, trigger: :click }
+        when Hash
+          normalized = value.deep_symbolize_keys
+          mode = normalized[:mode]&.to_sym
+          normalized[:mode] = EDITABLE_MODES.include?(mode) ? mode : :cell
+          trigger = normalized[:trigger]&.to_sym
+          normalized[:trigger] = EDITABLE_TRIGGERS.include?(trigger) ? trigger : :click
+          normalized
+        else
+          nil
+        end
+      end
+
+      # Normalizes row drag configuration.
+      # Can be: true (drag whole row), :handle (drag via handle only), or Hash with options
+      #
+      # @param value [Boolean, Symbol, Hash, nil] row drag configuration
+      # @return [Hash, nil] normalized configuration { enabled: true, handle: false }
+      def normalize_row_drag(value)
+        return nil if value.nil? || value == false
+
+        case value
+        when true
+          { enabled: true, handle: false }
+        when :handle
+          { enabled: true, handle: true }
+        when Hash
+          normalized = value.deep_symbolize_keys
+          {
+            enabled: normalized.fetch(:enabled, true),
+            handle: normalized.fetch(:handle, false)
+          }
+        else
+          nil
+        end
+      end
+
+      # Normalizes column-level editable configuration.
+      # Column editable can override table-level settings.
+      #
+      # @param value [Boolean, Hash, nil] column editable configuration
+      # @return [Hash, nil] normalized configuration
+      def normalize_column_editable(value)
+        return nil if value.nil? || value == false
+        return {} if value == true
+
+        return nil unless value.is_a?(Hash)
+
+        normalized = value.deep_symbolize_keys
+        input_type = normalized[:type]&.to_sym || normalized[:input_type]&.to_sym
+        normalized[:input_type] = EDITABLE_INPUT_TYPES.include?(input_type) ? input_type : :text
+        normalized.except(:type)
+      end
+
+      def normalize_should_cell_update(value)
+        case value
+        when Symbol
+          value.to_s
+        when String
+          value.strip.presence
+        else
+          nil
+        end
+      end
+
+      # Returns JSON configuration for the table-level editable settings
+      # to be passed to the Stimulus controller.
+      #
+      # @return [String, nil] JSON string or nil if not editable
+      def editable_config_json
+        return nil unless @editable
+
+        @editable.to_json
+      end
+
+      def columns_config_json
+        leaf_columns.map do |col|
+          {
+            key: col[:key],
+            dataIndex: col[:data_index],
+            sorter: col[:sorter].present?
+          }.compact
+        end.to_json
+      end
+
+      # Returns the editable payload for a specific cell/column.
+      # Used to add data-editable-config attribute to editable cells.
+      #
+      # @param column [Hash] the column definition
+      # @return [Hash, nil] editable configuration for the cell
+      def cell_editable_payload(column)
+        return nil if column[:selection] || column[:expand]
+        return nil unless column[:data_index]
+
+        column_config = column[:editable]
+
+        # Column must explicitly opt-in to be editable
+        return nil if column_config.nil? || column_config == false
+
+        # Merge table-level and column-level config
+        base_config = @editable&.dup || {}
+        base_config.merge!(column_config) if column_config.is_a?(Hash)
+
+        base_config[:data_index] = column[:data_index]
+        base_config[:key] = column[:key]
+        base_config
+      end
+
+      def apply_should_cell_update_attributes!(attrs, column)
+        hook = column[:should_cell_update]
+        return unless hook.present?
+
+        attrs[:data] ||= {}
+        attrs[:data][:should_cell_update] = hook
+      end
+    end
+  end
+end