infotable 0.1.0

data/lib/infotable/base.rb

@@ -0,0 +1,463 @@
+module Infotable
+  class Base
+    class << self
+      attr_accessor :table_columns, :table_query, :table_query_sql, :pagination_settings, :sort_settings, :height_settings, :infinite_scroll_settings, :row_link_settings, :slim_rows_settings, :row_size_settings, :filters_button_settings, :display_settings, :nil_value_settings, :empty_value_settings, :table_authorize, :checkbox_settings, :batch_action_list, :countless_setting, :url_state_setting
+
+      def inherited(subclass)
+        super
+        subclass.table_columns = []
+        subclass.pagination_settings = {
+          per_page: Infotable.configuration.default_per_page,
+          per_page_options: Infotable.configuration.per_page_options
+        }
+        subclass.sort_settings = {}
+        subclass.height_settings = {
+          min_height: nil, # nil means use global config
+          max_height: nil  # nil means use global config
+        }
+        subclass.infinite_scroll_settings = {
+          enabled: false
+        }
+        subclass.row_link_settings = {
+          enabled: false,
+          url: nil
+        }
+        subclass.slim_rows_settings = {
+          enabled: false
+        }
+        subclass.row_size_settings = {
+          size: :default # :slim, :mid, :default
+        }
+        subclass.filters_button_settings = {
+          visible: true
+        }
+        subclass.display_settings = {
+          title: nil,
+          subtitle: nil
+        }
+        subclass.nil_value_settings = {
+          value: nil # nil means use global config
+        }
+        subclass.empty_value_settings = {
+          value: nil # nil means use global config
+        }
+        subclass.checkbox_settings = { enabled: false, id_method: :id }
+        subclass.batch_action_list = []
+        subclass.countless_setting = false
+        subclass.url_state_setting = nil
+
+        inherit_from_parent(subclass)
+      end
+
+      # Copy parent table definition so a subclass can extend it
+      def inherit_from_parent(subclass)
+        parent = subclass.superclass
+        return if parent == Infotable::Base || parent.table_columns.nil?
+
+        subclass.table_columns = parent.table_columns.map(&:dup)
+        subclass.table_query = parent.table_query
+        subclass.table_query_sql = parent.table_query_sql
+        subclass.table_authorize = parent.table_authorize
+        subclass.checkbox_settings = parent.checkbox_settings.dup
+        subclass.batch_action_list = parent.batch_action_list.map(&:dup)
+        subclass.countless_setting = parent.countless_setting
+        subclass.url_state_setting = parent.url_state_setting
+        %i[pagination_settings sort_settings height_settings infinite_scroll_settings row_link_settings
+           slim_rows_settings row_size_settings filters_button_settings display_settings
+           nil_value_settings empty_value_settings].each do |attr|
+          subclass.public_send("#{attr}=", parent.public_send(attr).dup)
+        end
+      end
+
+      # Define data source using ActiveRecord.
+      # The block receives the controller (current_user, params, ...) for per-request scoping:
+      #   query { |controller| Post.where(account: controller.current_account) }
+      def query(&block)
+        @table_query = block
+      end
+
+      # Skip SELECT COUNT(*) (slow on big tables): no total, no page numbers, only prev/next.
+      def countless(enabled = true)
+        @countless_setting = enabled
+      end
+
+      # Keep search, filters, sort and page in the page's address bar (shareable links, working Back
+      # button). Default: Infotable.configuration.url_state. Turn it off for tables in modals/tabs
+      # or when several unrelated tables should not fight over the URL.
+      def url_state(enabled = true)
+        @url_state_setting = enabled
+      end
+
+      def url_state?
+        @url_state_setting.nil? ? Infotable.configuration.url_state : @url_state_setting ? true : false
+      end
+
+      def countless?
+        @countless_setting ? true : false
+      end
+
+      # Row checkboxes without bulk actions (e.g. to read the selection from your own JS)
+      def checkbox_column(enabled: true, id_method: :id)
+        @checkbox_settings = { enabled: enabled, id_method: id_method }
+      end
+
+      # Bulk actions; defining any turns the checkbox column on. See Infotable::BatchActions.
+      def batch_actions(&block)
+        builder = Infotable::BatchActions::Builder.new
+        builder.instance_eval(&block)
+        @batch_action_list = builder.actions
+      end
+
+      def checkbox_enabled?
+        @checkbox_settings[:enabled] || @batch_action_list.any?
+      end
+
+      def checkbox_value(record)
+        record.public_send(@checkbox_settings[:id_method])
+      end
+
+      # Per-table access check. Block receives the controller; falsy => 403.
+      #   authorize { |controller| controller.current_user&.admin? }
+      def authorize(&block)
+        @table_authorize = block
+      end
+
+      def authorized?(context = nil)
+        @table_authorize.nil? || @table_authorize.call(context) ? true : false
+      end
+
+      # Define data source using raw SQL
+      # Raw SQL data source. The SQL becomes a sub-select aliased as the model's table, so
+      # filters, search, sorting, pagination and export work like with `query`:
+      #   query_sql "SELECT u.*, COUNT(p.id) AS posts_n FROM users u LEFT JOIN posts p ON ... GROUP BY u.id", model: User
+      # The SQL is developer-defined (never interpolate request input into it).
+      def query_sql(sql, model:)
+        raise ArgumentError, "query_sql requires a model: (an ActiveRecord class used for types and the table alias)" unless model.respond_to?(:table_name)
+
+        @table_query_sql = { sql: sql.to_s, model: model }
+      end
+
+      # Define a column
+      def column(name, **options)
+        @table_columns ||= []
+        type = options[:type] || :string
+
+        # Determine width - use custom if provided and not blank, otherwise use default
+        width = if options[:width].present?
+          options[:width]
+        else
+          default_column_width(type)
+        end
+
+        column_definition = {
+          name: name,
+          label: options[:label] || name.to_s.tr("_", " "),
+          type: type,
+          sortable: options.fetch(:sortable, false),
+          searchable: options.fetch(:searchable, false),
+          filterable: options.fetch(:filterable, false),
+          visible: options.fetch(:visible, true),
+          pinned: options[:pinned], # :left, :right, or nil
+          virtual: options.fetch(:virtual, false), # Virtual/computed columns (aggregates, subqueries)
+          virtual_sql: options[:virtual_sql], # SQL expression for aggregate columns (used in HAVING clause)
+          sql: options[:sql], # Row-level SQL expression for filtering/sorting (WHERE), e.g. "authors.name"
+          sort_sql: options[:sort_sql], # Overrides :sql for ORDER BY only, e.g. filter by id, sort by name
+          value: options[:value], # ->(record) { ... } reads the cell value when it is not a record attribute
+          includes: options[:includes], # association(s) to preload for this column (avoids N+1), e.g. :author
+          formatter: options[:formatter],
+          formatter_options: options[:formatter_options],
+          actions: options[:actions], # For action columns (deprecated - use formatter_options)
+          filter_type: options[:filter_type],
+          filter_options: options[:filter_options],
+          filter_options_cache: options[:filter_options_cache], # e.g. 5.minutes: cache a Proc's result (not for per-user options)
+          filter_options_limit: options[:filter_options_limit], # max <option>s rendered; default Infotable.configuration.max_filter_options
+          filter_multi_select: options.fetch(:filter_multi_select, false),
+          width: width
+        }
+        @table_columns << column_definition
+      end
+
+      # Get default width based on column type
+      def default_column_width(type)
+        case type
+        when :boolean
+          "80px"
+        when :date
+          "120px"
+        when :datetime
+          "180px"
+        when :integer
+          "100px"
+        when :decimal, :float, :currency
+          "120px"
+        when :badge, :status
+          "120px"
+        when :action, :actions
+          "100px"
+        when :text
+          "300px"
+        when :string
+          "200px"
+        else
+          "200px"
+        end
+      end
+
+      # Set pagination per_page
+      def per_page(value)
+        @pagination_settings[:per_page] = value
+      end
+
+      # Set per_page options
+      def per_page_options(values)
+        @pagination_settings[:per_page_options] = values
+      end
+
+      # Set default sort
+      def default_sort(column, direction = :asc)
+        @sort_settings = { column: column, direction: direction }
+      end
+
+      # Set table minimum height
+      def table_min_height(value)
+        @height_settings[:min_height] = value
+      end
+
+      # Set table maximum height
+      def table_max_height(value)
+        @height_settings[:max_height] = value
+      end
+
+      # Enable/disable infinite scroll
+      def infinite_scroll(enabled)
+        @infinite_scroll_settings[:enabled] = enabled
+      end
+
+      # Check if infinite scroll is enabled
+      def infinite_scroll_enabled?
+        @infinite_scroll_settings[:enabled]
+      end
+
+      # Configure row link
+      # @param url [Proc, String] - URL generator (Proc receives record) or static URL
+      # @example
+      #   row_link ->(record) { "/comments/#{record.id}" }
+      #   row_link "/posts/show"
+      def row_link(url)
+        @row_link_settings[:enabled] = true
+        @row_link_settings[:url] = url
+      end
+
+      # Check if row link is enabled
+      def row_link_enabled?
+        @row_link_settings[:enabled]
+      end
+
+      # Get row link URL for a record
+      def row_link_url(record)
+        return nil unless row_link_enabled?
+
+        url_generator = @row_link_settings[:url]
+        if url_generator.is_a?(Proc)
+          url_generator.call(record)
+        else
+          url_generator
+        end
+      end
+
+      # Set row size (padding and text size)
+      # @param size [Symbol] - Row size (:slim, :mid, :default)
+      # @example
+      #   row_size :slim
+      #   row_size :mid
+      #   row_size :default
+      def row_size(size)
+        valid_sizes = [ :slim, :mid, :default ]
+        unless valid_sizes.include?(size)
+          raise ArgumentError, "Invalid row size: #{size}. Must be one of #{valid_sizes.join(', ')}"
+        end
+        @row_size_settings ||= { size: :default }
+        @row_size_settings[:size] = size
+
+        # Also set slim_rows for backward compatibility
+        @slim_rows_settings ||= { enabled: false }
+        @slim_rows_settings[:enabled] = (size == :slim)
+      end
+
+      # Get current row size
+      def row_size_value
+        @row_size_settings ||= { size: :default }
+
+        # Check slim_rows for backward compatibility
+        if @slim_rows_settings && @slim_rows_settings[:enabled]
+          return :slim
+        end
+
+        @row_size_settings[:size]
+      end
+
+      # Enable slim rows (compact padding) - DEPRECATED: Use row_size(:slim) instead
+      # @example
+      #   slim_rows true
+      def slim_rows(enabled = true)
+        @slim_rows_settings ||= { enabled: false }
+        @slim_rows_settings[:enabled] = enabled
+
+        # Also update row_size_settings for consistency
+        @row_size_settings ||= { size: :default }
+        @row_size_settings[:size] = enabled ? :slim : :default
+      end
+
+      # Check if slim rows is enabled - DEPRECATED: Use row_size_value instead
+      def slim_rows_enabled?
+        row_size_value == :slim
+      end
+
+      # Show/hide filters button
+      # @param visible [Boolean] - Whether to show the filters button
+      # @example
+      #   show_filters_button false
+      def show_filters_button(visible = true)
+        @filters_button_settings ||= { visible: true }
+        @filters_button_settings[:visible] = visible
+      end
+
+      # Check if filters button is visible
+      def filters_button_visible?
+        @filters_button_settings ||= { visible: true }
+        @filters_button_settings[:visible]
+      end
+
+      # Set table title
+      # @param text [String] - The title to display above the table
+      # @example
+      #   table_title "User Management"
+      def table_title(text)
+        @display_settings ||= { title: nil, subtitle: nil }
+        @display_settings[:title] = text
+      end
+
+      # Set table subtitle
+      # @param text [String] - The subtitle to display below the title
+      # @example
+      #   table_subtitle "Manage all users in the system"
+      def table_subtitle(text)
+        @display_settings ||= { title: nil, subtitle: nil }
+        @display_settings[:subtitle] = text
+      end
+
+      # Get table title
+      def title
+        @display_settings ||= { title: nil, subtitle: nil }
+        @display_settings[:title]
+      end
+
+      # Get table subtitle
+      def subtitle
+        @display_settings ||= { title: nil, subtitle: nil }
+        @display_settings[:subtitle]
+      end
+
+      # Set nil value placeholder
+      # @param text [String] - The text to display for nil values
+      # @example
+      #   nil_value "N/A"
+      #   nil_value ""
+      def nil_value(text)
+        @nil_value_settings ||= { value: nil }
+        @nil_value_settings[:value] = text
+      end
+
+      # Get nil value placeholder (table-specific or global)
+      def nil_value_placeholder
+        @nil_value_settings ||= { value: nil }
+        @nil_value_settings[:value].nil? ? Infotable.configuration.nil_value : @nil_value_settings[:value]
+      end
+
+      # Set empty value placeholder
+      # @param text [String] - The text to display for empty strings
+      # @example
+      #   empty_value "N/A"
+      #   empty_value ""
+      def empty_value(text)
+        @empty_value_settings ||= { value: nil }
+        @empty_value_settings[:value] = text
+      end
+
+      # Get empty value placeholder (table-specific or global)
+      def empty_value_placeholder
+        @empty_value_settings ||= { value: nil }
+        @empty_value_settings[:value].nil? ? Infotable.configuration.empty_value : @empty_value_settings[:value]
+      end
+
+      # Get minimum height (table-specific or global)
+      def min_height
+        @height_settings[:min_height] || Infotable.configuration.table_min_height
+      end
+
+      # Get maximum height (table-specific or global)
+      def max_height
+        @height_settings[:max_height] || Infotable.configuration.table_max_height
+      end
+
+      # Get the base query
+      def base_query(context = nil)
+        if @table_query
+          @table_query.call(context)
+        elsif @table_query_sql
+          model = @table_query_sql[:model]
+          model.from(Arel.sql("(#{@table_query_sql[:sql]}) AS #{model.connection.quote_table_name(model.table_name)}"))
+        else
+          raise Infotable::Error, "No query or query_sql defined for #{name}"
+        end
+      end
+
+      # Raw cell value of a record for a column (value: proc, attribute or association)
+      def cell_value(record, column)
+        return column[:value].call(record) if column[:value]
+
+        record.try(column[:name]) || record[column[:name]]
+      end
+
+      # Associations to preload for the table's columns (deduplicated)
+      def preloads
+        columns.flat_map { |col| Array.wrap(col[:includes]) }.uniq
+      end
+
+      # Get all columns
+      def columns
+        @table_columns || []
+      end
+
+      # Get virtual (computed/aggregated) columns
+      def virtual_columns
+        columns.select { |col| col[:virtual] }
+      end
+
+      # Get non-virtual (regular database) columns
+      def regular_columns
+        columns.reject { |col| col[:virtual] }
+      end
+
+      # Get visible columns
+      def visible_columns
+        columns.select { |col| col[:visible] }
+      end
+
+      # Get sortable columns
+      def sortable_columns
+        columns.select { |col| col[:sortable] }
+      end
+
+      # Get filterable columns
+      def filterable_columns
+        columns.select { |col| col[:filterable] }
+      end
+
+      # Get searchable columns
+      def searchable_columns
+        columns.select { |col| col[:searchable] }
+      end
+    end
+  end
+end

data/lib/infotable/batch_actions.rb

@@ -0,0 +1,34 @@
+module Infotable
+  # Row selection + bulk actions. The gem renders the checkboxes and the action bar;
+  # the host app implements the endpoints and receives the ids as `ids[]`.
+  #
+  #   class PostsTable < Infotable::Base
+  #     batch_actions do
+  #       action :archive, label: "Archive", url: "/posts/archive", method: :patch
+  #       action :delete,  label: "Delete",  url: "/posts/delete",  method: :delete,
+  #                        confirm: "Delete %{count} posts?", color: :danger
+  #     end
+  #   end
+  module BatchActions
+    METHODS = %i[get post put patch delete].freeze
+    COLORS = %i[default primary success warning danger].freeze
+
+    class Builder
+      attr_reader :actions
+
+      def initialize
+        @actions = []
+      end
+
+      def action(name, url:, label: nil, method: :post, confirm: nil, color: :default)
+        method = method.to_s.downcase.to_sym
+        color = color.to_s.to_sym
+        raise ArgumentError, "batch action :#{name}: url must be a String" unless url.is_a?(String) && url.present?
+        raise ArgumentError, "batch action :#{name}: method must be one of #{METHODS.inspect}" unless METHODS.include?(method)
+        raise ArgumentError, "batch action :#{name}: color must be one of #{COLORS.inspect}" unless COLORS.include?(color)
+
+        @actions << { name: name.to_sym, label: label || name.to_s.humanize, url: url, method: method, confirm: confirm, color: color }
+      end
+    end
+  end
+end

data/lib/infotable/configuration.rb

@@ -0,0 +1,53 @@
+module Infotable
+  class Configuration
+    attr_accessor :default_per_page,
+                  :per_page_options,
+                  :drawer_position,
+                  :drawer_width,
+                  :theme,
+                  :turbo_enabled,
+                  :pagination_gem,
+                  :table_min_height,
+                  :table_max_height,
+                  :autofilter,
+                  :nil_value,
+                  :empty_value,
+                  :parent_controller,
+                  :max_filter_options,
+                  :url_state
+
+    def initialize
+      @default_per_page = 25
+      @per_page_options = [ 10, 25, 50, 100 ]
+      @drawer_position = :right # :left or :right
+      @drawer_width = "26rem"
+      @theme = :default # no effect yet (kept so existing initializers keep working)
+      @turbo_enabled = true # no effect yet
+      @pagination_gem = :pagy # no effect yet; Pagy is the only backend
+      @table_min_height = "400px"
+      @table_max_height = "600px"
+      @autofilter = true # true = auto-apply filters (debounced), false = manual apply button
+      @nil_value = "-" # Default placeholder for nil values
+      @empty_value = "-" # Default placeholder for empty strings
+      @url_state = true # mirror table state in the address bar
+      @max_filter_options = 500 # select filters render at most this many <option>s (nil = no limit)
+      @parent_controller = "ActionController::Base" # Set to "ApplicationController" to inherit host auth/filters
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/infotable/engine.rb

@@ -0,0 +1,51 @@
+require "turbo-rails"
+require "stimulus-rails"
+require "pagy"
+
+module Infotable
+  class Engine < ::Rails::Engine
+    isolate_namespace Infotable
+
+    # Configure engine
+    config.infotable = ActiveSupport::OrderedOptions.new
+
+    # Default configuration values
+    config.infotable.table_min_height = "400px"
+    config.infotable.table_max_height = "600px"
+
+    # Rails already adds the engine's app/assets/* directories to the asset path;
+    # only the precompile list is needed. Skipped for apps without an asset pipeline.
+    initializer "infotable.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[infotable/controllers/*.js]
+      end
+    end
+
+    # Setup Stimulus controllers for importmap (only runs if importmap-rails is installed)
+    initializer "infotable.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb") if root.join("config/importmap.rb").exist?
+      end
+    end
+
+    # Add helpers to host application
+    initializer "infotable.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Infotable::Engine.helpers
+      end
+    end
+
+    # Load engine i18n locale files
+    initializer "infotable.i18n" do |app|
+      config.i18n.load_path += Dir[root.join("config/locales/**/*.yml")]
+    end
+
+    # Expose gem paths via ENV variables for Tailwind CSS v4 @source directives
+    # This allows Tailwind to scan the gem's views/formatters at build time
+    # Works in development, production, Docker, CI - everywhere!
+    initializer "infotable.tailwind", before: :load_config_initializers do
+      ENV["INFOTABLE_VIEWS_PATH"] = root.join("app/views/infotable").to_s
+      ENV["INFOTABLE_FORMATTERS_PATH"] = root.join("lib/infotable/formatters").to_s
+    end
+  end
+end