infotable 0.1.0

data/README.md

@@ -0,0 +1,1043 @@
+# InfoTable
+
+Modern, flexible datatable engine for Rails 8+ with Hotwire. Build beautiful, interactive tables with server-side filtering, sorting, searching, and pagination—without page reloads.
+
+## Features
+
+- ✨ **Server-side operations** - Filtering, sorting, searching, pagination all on the backend
+- ⚡ **No page reloads** - Built with Hotwire (Turbo + Stimulus)
+- 🎨 **Pure Tailwind CSS** - Beautiful, modern UI using only Tailwind utility classes (no custom CSS!)
+- 🔧 **Highly customizable** - Easy to override defaults and add custom formatters
+- 📦 **Works with any bundler** - Importmap, esbuild, webpack, vite—we support them all
+- 🚀 **Rails 8+ ready** - Built for modern Rails applications
+- 🌍 **i18n Support** - English and Polish translations included
+- 🎯 **Advanced Features** - Infinite scroll, column pinning, drag-to-reorder, row links, and more
+
+## Quick Start
+
+```ruby
+# 1. Add to Gemfile
+gem 'infotable'
+
+# 2. Install
+bundle install
+rails generate infotable:install
+
+# 3. Create a table definition (app/infotable/users_table.rb)
+class UsersTable < Infotable::Base
+  query { User.all }
+
+  column :name, label: "Name", type: :string, sortable: true
+  column :email, label: "Email", type: :string, sortable: true
+  column :created_at, label: "Created", type: :datetime, sortable: true
+
+  per_page 25
+end
+
+# 4. Use in your view
+<%= infotable :users_table %>
+```
+
+That's it! You now have a fully functional datatable with sorting and pagination.
+
+## Requirements
+
+- Rails 8.0+
+- Ruby 3.3+
+- PostgreSQL (filters use `ILIKE`, `HAVING` and `CAST(... AS numeric)`; other databases are not supported)
+- [Pagy](https://github.com/ddnexus/pagy) 43 (installed as a dependency)
+- Tailwind CSS v4 (via `tailwindcss-rails` gem) - **Required for styling**
+- Hotwire (Turbo + Stimulus)
+
+**Note:** InfoTable uses pure Tailwind CSS utility classes for all styling. No custom CSS is included or required.
+
+## Installation
+
+### Automatic Installation (Recommended)
+
+```bash
+bundle add infotable
+rails generate infotable:install
+```
+
+The installer will:
+- Auto-detect your JavaScript bundler (importmap, esbuild, webpack, vite)
+- Configure Tailwind CSS (v4 or v3) to scan InfoTable views
+- Mount engine routes
+- Create `app/infotable/` directory
+- Generate configuration file
+
+**After installation:**
+```bash
+# Rebuild Tailwind to include InfoTable styles
+rails tailwindcss:build
+
+# Restart your Rails server
+rails server
+```
+
+**Important:** Verify your layout (`app/views/layouts/application.html.erb`) includes:
+```erb
+<%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
+```
+
+### Manual Installation
+
+See [docs/installation.md](docs/installation.md) for detailed instructions for each bundler type.
+
+## Bundler Support
+
+InfoTable works seamlessly with:
+- **Importmap** (Rails default)
+- **esbuild**
+- **webpack**
+- **vite**
+- Other JavaScript bundlers
+
+The installer automatically detects and configures your setup.
+
+---
+
+## Configuration
+
+### Global Configuration
+
+Customize in `config/initializers/infotable.rb`:
+
+```ruby
+Infotable.configure do |config|
+  # Pagination defaults
+  config.default_per_page = 25
+  config.per_page_options = [10, 25, 50, 100]
+
+  # Drawer/side panel settings
+  config.drawer_position = :right  # :left or :right
+  config.drawer_width = "26rem"  # px, rem, em, vw or %
+
+  # Controller the engine controllers inherit from, so authentication, locale,
+  # tenant scoping etc. also protect the tables
+  config.parent_controller = "ApplicationController"
+
+  # Table height defaults
+  config.table_min_height = "400px"
+  config.table_max_height = "600px"
+
+  # Filter behavior
+  config.autofilter = true  # true = auto-apply filters (debounced), false = manual apply button
+end
+```
+
+### Available Global Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `default_per_page` | Integer | `25` | Default number of rows per page |
+| `per_page_options` | Array | `[10, 25, 50, 100]` | Available rows per page options |
+| `drawer_position` | Symbol | `:right` | Position of filter/column drawer (`:left` or `:right`) |
+| `drawer_width` | String | `"26rem"` | Width of the drawer (`px`, `rem`, `em`, `vw` or `%`; anything else falls back to the default) |
+| `parent_controller` | String | `"ActionController::Base"` | Controller the engine's controllers inherit from. Set it to `"ApplicationController"` to reuse your authentication |
+| `table_min_height` | String | `"400px"` | Minimum table height |
+| `table_max_height` | String | `"600px"` | Maximum table height (enables scrolling) |
+| `autofilter` | Boolean | `true` | Auto-apply filters on change (debounced) vs manual apply |
+| `url_state` | Boolean | `true` | Mirror search, filters, sort and page in the address bar (override per table with `url_state false`) |
+| `max_filter_options` | Integer | `500` | Cap on `<option>`s in a select filter (`nil` = no cap) |
+
+`theme`, `turbo_enabled` and `pagination_gem` are still accepted so old initializers keep loading, but they do nothing.
+
+---
+
+## Table Definition
+
+Generate a starting point from a model's columns:
+
+```bash
+rails generate infotable:table User
+rails generate infotable:table Admin::Order --only=id number status   # or --skip=notes
+```
+
+It writes `app/infotable/users_table.rb` with a column per attribute (types and filters inferred, enums become select filters, passwords/tokens and foreign keys are left out, `belongs_to` associations come as commented hints).
+
+Or create table classes in `app/infotable/` by hand:
+
+```ruby
+class UsersTable < Infotable::Base
+  # Define data source
+  query { User.all }
+
+  # Define columns
+  column :name, label: "Full Name", type: :string, sortable: true
+
+  # Configure table settings
+  per_page 25
+  default_sort :created_at, :desc
+end
+```
+
+### Organizing Tables in Folders
+
+You can organize table definitions in subfolders. Rails' Zeitwerk autoloader automatically creates namespaces from the directory structure:
+
+**Single-level nesting:**
+```ruby
+# app/infotable/cms/users_table.rb
+class Cms::UsersTable < Infotable::Base
+  query { User.all }
+  # ... columns
+end
+
+# Use in views:
+<%= infotable :cms_users_table %>
+```
+
+**Multi-level nesting:**
+```ruby
+# app/infotable/cms/admins/users_table.rb
+class Cms::Admins::UsersTable < Infotable::Base
+  query { User.where(admin: true) }
+  # ... columns
+end
+
+# Use in views:
+<%= infotable :cms_admins_users_table %>
+```
+
+**How it works:**
+- Rails' Zeitwerk autoloader infers namespaces from directory structure
+- File path: `app/infotable/cms/users_table.rb` → Class: `Cms::UsersTable` → Symbol: `:cms_users_table`
+- File path: `app/infotable/cms/admins/users_table.rb` → Class: `Cms::Admins::UsersTable` → Symbol: `:cms_admins_users_table`
+- No need for `module` wrappers - the directory structure provides the namespace
+
+**Naming convention:**
+- Pattern: folder names joined with underscores, followed by the table name
+- Example: folder `cms/admins` + file `users_table.rb` = symbol `:cms_admins_users_table`
+
+### Data Source Methods
+
+#### `query`
+Define data source using ActiveRecord relation:
+
+```ruby
+query { User.includes(:company).where(active: true) }
+```
+
+The block receives the controller, so you can scope by the current user:
+
+```ruby
+query { |controller| controller.current_user.projects }
+```
+
+#### `query_sql`
+Define data source using raw SQL. A `model:` is required; it supplies the column types and the table alias. The SQL is wrapped in a sub-select, so filters, search, sorting, pagination and export all work:
+
+```ruby
+query_sql "SELECT * FROM users WHERE active = true", model: User
+```
+
+#### `authorize`
+Return false to answer `403 Forbidden` for the table, its data and its export:
+
+```ruby
+authorize { |controller| controller.current_user&.admin? }
+```
+
+### Column Definition
+
+```ruby
+column :name, **options
+```
+
+#### Virtual/Computed Columns
+
+For aggregated or computed columns (COUNT, SUM, subqueries, calculations), mark them as `virtual: true`:
+
+```ruby
+query do
+  Shop.select(
+    "shops.*",
+    "COUNT(products.id) AS products_count"
+  )
+    .left_joins(:products)
+    .group("shops.id")
+end
+
+# Regular column
+column :name, sortable: true, filterable: true
+
+# Virtual column (aggregate)
+column :products_count,
+  type: :integer,
+  sortable: true,        # ✅ Sorting works
+  filterable: true,      # ✅ Filtering uses HAVING clause
+  filter_type: :number,
+  virtual: true,         # ⭐ Required for aggregates!
+  virtual_sql: "COUNT(products.id)" # ⭐ SQL expression for filtering (without AS alias)
+```
+
+**Why `virtual: true` and `virtual_sql`?**
+- Aggregated columns require `HAVING` clause for filtering (not `WHERE`)
+- The `virtual_sql` option provides the SQL expression used in both HAVING and ORDER BY clauses
+- InfoTable automatically uses the correct SQL clauses for filtering and sorting
+- Works with all filter types
+- See [docs/virtual_columns.md](docs/virtual_columns.md) for detailed examples
+
+#### Column Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `label` | String | Humanized column name | Display label for column header |
+| `type` | Symbol | `:string` | Data type (see Column Types below) |
+| `sortable` | Boolean | `false` | Enable sorting for this column |
+| `searchable` | Boolean | `false` | Include in global search |
+| `filterable` | Boolean | `false` | Enable filtering for this column |
+| `visible` | Boolean | `true` | Show column by default |
+| `pinned` | Symbol | `nil` | Pin column (`:left`, `:right`, or `nil`) |
+| `width` | String | Auto (see defaults) | Column width (e.g., `"200px"`) |
+| `formatter` | Symbol/Proc/Hash | `nil` | Custom formatter (see Formatters) |
+| `filter_type` | Symbol | Auto-detected | Filter UI type (`:text`, `:number`, `:date`, `:select`, `:boolean`) |
+| `filter_options` | Array/Proc | `nil` | Options for select filters (`["a", "b"]`, `[["Label", value]]` or a Proc) |
+| `filter_options_cache` | Duration | `nil` | Cache a Proc's result with `Rails.cache`, e.g. `5.minutes`. Keyed per table and column, so do not use it for options that depend on the current user |
+| `filter_options_limit` | Integer | `max_filter_options` | Most `<option>`s rendered for this filter; the drawer says when the list was cut. For big lists use a text filter instead |
+| `virtual` | Boolean | `false` | Mark column as virtual/computed (aggregates, subqueries) - uses HAVING for filters |
+| `virtual_sql` | String | `nil` | SQL expression for virtual columns (used in HAVING and ORDER BY clauses, without AS alias) |
+| `sql` | String | `nil` | Row-level SQL expression to filter and search on instead of the column (e.g. `"comments.post_id"`). Not an aggregate, so it goes in `WHERE` |
+| `sort_sql` | String | `nil` | SQL expression to sort by (e.g. `"authors.name"` for an association column) |
+| `value` | Proc | `nil` | Computes the cell value from the record: `value: ->(post) { post.author.name }` |
+| `includes` | Symbol/Array/Hash | `nil` | Association to preload for this column (avoids N+1 in the table and the CSV export) |
+| `filter_multi_select` | Boolean | `false` | Let a `:select` filter take several values |
+
+#### Column Types
+
+Available types and their default widths:
+
+| Type | Default Width | Description |
+|------|---------------|-------------|
+| `:string` | `200px` | Text string |
+| `:text` | `300px` | Long text content |
+| `:integer` | `100px` | Integer number |
+| `:decimal` | `120px` | Decimal number |
+| `:float` | `120px` | Float number |
+| `:currency` | `120px` | Currency value |
+| `:boolean` | `80px` | True/false value |
+| `:date` | `120px` | Date only |
+| `:datetime` | `180px` | Date and time |
+| `:badge` | `120px` | Badge/status indicator |
+| `:status` | `120px` | Alias for badge |
+| `:action` | `100px` | Action buttons |
+| `:actions` | `100px` | Alias for action |
+
+### Table Configuration Methods
+
+#### Pagination
+
+```ruby
+# Set rows per page
+per_page 25
+
+# Set per-page options dropdown
+per_page_options [10, 25, 50, 100]
+```
+
+#### Sorting
+
+```ruby
+# Set default sort
+default_sort :created_at, :desc  # column, direction (:asc or :desc)
+```
+
+Click a header to sort; **Shift+click** adds up to three sort columns (`?sort=name:asc,age:desc`). The primary key is always appended as a tiebreaker, so pages never repeat or skip rows.
+
+#### Search
+
+Mark columns `searchable: true` to get a search box. Every word (up to 5) must match at least one searchable column, case-insensitively.
+
+#### Filters
+
+Filter types are inferred from the column type or set with `filter_type:`.
+
+| Type | Operators |
+|------|-----------|
+| text | contains, equals, starts with, ends with, not contains, is empty, is not empty |
+| number | `eq` `neq` `gt` `gte` `lt` `lte` `between` `is_empty` `is_not_empty` (plain `from`/`to` still work) |
+| date | `on` `before` `after` `between` `is_empty` `is_not_empty` (plain `from`/`to` still work) |
+| boolean | any, yes, no |
+| select | one value, or several with `filter_multi_select: true` |
+
+Filters, search and sort survive pagination, per-page changes and CSV export.
+
+#### Table state in the URL
+
+Search, filters, sort, page and page size are mirrored in the page's address bar, one namespace per table (`/users?users_table[search]=ann&users_table[page]=2`). Links can be shared and bookmarked, a reload keeps the table as it was, and the Back button steps through the states. Turn it off globally with `config.url_state = false` or per table with `url_state false` (e.g. tables inside modals or tabs).
+
+#### Large tables
+
+```ruby
+# Skip SELECT COUNT(*): only previous/next, no total or page numbers
+countless
+```
+
+#### Batch actions
+
+Row checkboxes plus an action bar. The gem renders them and sends the selected ids as `ids[]` to your endpoints:
+
+```ruby
+batch_actions do
+  action :feature, label: "Feature", url: "/posts/batch", method: :patch, color: :primary
+  action :delete,  label: "Delete",  url: "/posts/batch", method: :delete, color: :danger,
+                   confirm: "Delete %{count} posts?"
+end
+
+# Checkboxes only (read the selection from your own JavaScript)
+checkbox_column
+```
+
+`color:` is one of `:default`, `:primary`, `:success`, `:warning`, `:danger`; `method:` is one of `:get`, `:post`, `:put`, `:patch`, `:delete`.
+
+#### Table Height
+
+```ruby
+# Override global height settings for this table
+table_min_height "500px"
+table_max_height "700px"
+```
+
+#### Infinite Scroll
+
+```ruby
+# Enable infinite scroll (replaces pagination)
+infinite_scroll true
+```
+
+#### Row Links
+
+Make entire rows clickable:
+
+```ruby
+# Dynamic URL based on record
+row_link ->(record) { "/users/#{record.id}" }
+
+# Static URL
+row_link "/users/show"
+```
+
+Features:
+- Click row to navigate
+- Cmd/Ctrl+Click to open in new tab
+- Ignores clicks on buttons, links, and inputs
+
+#### Row Size
+
+Control table row padding and text size with three options:
+
+```ruby
+# Slim - Compact padding (px-2 py-1) with smaller text
+row_size :slim
+
+# Mid - Medium padding (px-4 py-2.5) - default text size
+row_size :mid
+
+# Default - Full padding (px-6 py-4) with normal text (default)
+row_size :default
+```
+
+**Backward compatibility:** The old `slim_rows true` method still works and maps to `row_size :slim`
+
+**Visual comparison:**
+- **Slim**: Minimal padding, smaller text - ideal for dense data tables
+- **Mid**: Moderate padding, normal text - balanced appearance
+- **Default**: Generous padding, normal text - comfortable reading
+
+#### Filters Button Visibility
+
+Show or hide the filters button:
+
+```ruby
+show_filters_button false  # Hide filters button
+```
+
+---
+
+## Formatters
+
+Formatters customize how values are displayed.
+
+### Built-in Formatters
+
+#### 1. Date Formatter (`:date`)
+
+```ruby
+column :created_at,
+  type: :datetime,
+  formatter: :date,
+  formatter_options: { format: :short }  # :short, :long, :datetime
+```
+
+#### 2. Currency Formatter (`:currency`)
+
+```ruby
+column :price,
+  type: :decimal,
+  formatter: :currency,
+  formatter_options: { precision: 2 }
+```
+
+#### 3. Boolean Formatter (`:boolean`)
+
+```ruby
+column :active,
+  type: :boolean,
+  formatter: :boolean
+```
+
+Displays checkmark (✓) for true, X (✗) for false.
+
+#### 4. Badge Formatter (`:badge`)
+
+```ruby
+column :status,
+  type: :badge,
+  formatter: :badge,
+  formatter_options: {
+    colors: {
+      "active" => "green",
+      "inactive" => "gray",
+      "pending" => "yellow"
+    }
+  }
+```
+
+Available colors: `green`, `red`, `yellow`, `blue`, `indigo`, `purple`, `pink`, `gray`, `cyan`
+
+#### 5. Action Formatter (`:action`)
+
+```ruby
+column :actions,
+  type: :action,
+  formatter: :action,
+  formatter_options: {
+    actions: [
+      {
+        label: "View",
+        url: ->(record) { "/users/#{record.id}" },
+        color: "primary"  # primary, secondary, danger
+      },
+      {
+        label: "Delete",
+        url: ->(record) { "/users/#{record.id}" },
+        method: :delete,
+        color: "danger",
+        confirm: "Are you sure?"
+      }
+    ],
+    style: :buttons  # :buttons (default), :links or :dropdown (a keyboard-friendly menu, no JavaScript)
+  }
+```
+
+`method:` and `confirm:` use Turbo (`data-turbo-method`, `data-turbo-confirm`). Labels are HTML-escaped.
+
+### Custom Formatters
+
+#### Lambda/Proc Formatter
+
+```ruby
+column :name,
+  formatter: ->(value, record) { content_tag(:strong, value) }
+```
+
+The lambda receives:
+- `value` - Column value
+- `record` - Full record object
+
+The returned string is rendered as-is when you mark it `html_safe`, so escape anything that comes from user data: `safe_join(["<strong>".html_safe, value, "</strong>".html_safe])` or `content_tag(:strong, value)`.
+
+#### Hash Formatter
+
+```ruby
+column :status,
+  formatter: {
+    type: :badge,
+    options: { colors: { "active" => "green" } }
+  }
+```
+
+---
+
+## Filters
+
+### Filter Types
+
+Filters are automatically enabled for columns with `filterable: true`.
+
+#### Text Filter (`:text`)
+
+```ruby
+column :name,
+  filterable: true,
+  filter_type: :text
+```
+
+Operators: Contains, Starts with, Ends with, Equals, Does not contain
+
+#### Number Filter (`:number`)
+
+```ruby
+column :age,
+  filterable: true,
+  filter_type: :number
+```
+
+Operators: Equals, Greater than, Less than, Greater or equal, Less or equal, Between
+
+#### Date Filter (`:date`)
+
+```ruby
+column :created_at,
+  filterable: true,
+  filter_type: :date
+```
+
+Operators: On, Before, After, Between
+
+#### Select Filter (`:select`)
+
+```ruby
+column :status,
+  filterable: true,
+  filter_type: :select,
+  filter_options: ["active", "inactive", "pending"]
+
+# Or with dynamic options (Proc)
+column :company,
+  filterable: true,
+  filter_type: :select,
+  filter_options: -> { Company.pluck(:name) }
+
+# Or with custom label/value pairs
+column :status,
+  filterable: true,
+  filter_type: :select,
+  filter_options: [["Active", "active"], ["Inactive", "inactive"]]
+```
+
+#### Boolean Filter (`:boolean`)
+
+```ruby
+column :active,
+  filterable: true,
+  filter_type: :boolean
+```
+
+Options: True, False, Any
+
+### Auto-apply Filters
+
+Control filter application behavior:
+
+```ruby
+# Global (in initializer)
+config.autofilter = true  # Apply filters automatically (debounced)
+config.autofilter = false # Require "Apply Filters" button click
+
+# Per-table (in view)
+<%= infotable :users_table, autofilter: false %>
+```
+
+---
+
+## View Helpers
+
+### Basic Usage
+
+```ruby
+<%= infotable :users_table %>
+```
+
+### Available Options
+
+```ruby
+<%= infotable :users_table,
+    title: "Active Users",
+    subtitle: "Currently logged in users",
+    autofilter: false,
+    per_page: 50,
+    per_page_options: [25, 50, 100],
+    drawer_position: :left,
+    drawer_width: "500px",
+    theme: :default
+%>
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title` | String | Table title (defaults to table class name) |
+| `subtitle` | String | Optional subtitle (not shown if nil) |
+| `autofilter` | Boolean | Override global autofilter setting |
+| `per_page` | Integer | Override default per page |
+| `per_page_options` | Array | Override per page options |
+| `drawer_position` | Symbol | Override drawer position |
+| `drawer_width` | String | Override drawer width |
+| `theme` | Symbol | Override theme |
+
+---
+
+## Internationalization (i18n)
+
+InfoTable includes English and Polish translations.
+
+### Set Locale
+
+```ruby
+# config/application.rb
+config.i18n.default_locale = :en
+config.i18n.available_locales = [:en, :pl]
+
+# Or per-request
+class ApplicationController < ActionController::Base
+  before_action :set_locale
+
+  def set_locale
+    I18n.locale = params[:locale] || I18n.default_locale
+  end
+end
+```
+
+### Available Languages
+
+- English (`:en`) - Default
+- Polish (`:pl`)
+
+### Customize Translations
+
+Override translations in your app:
+
+```yaml
+# config/locales/infotable.en.yml
+en:
+  infotable:
+    table:
+      buttons:
+        export_csv: "Download CSV"
+```
+
+### Add New Language
+
+```yaml
+# config/locales/infotable.es.yml
+es:
+  infotable:
+    table:
+      buttons:
+        export_csv: "Exportar CSV"
+        filters: "Filtros"
+      # ... see config/locales/en.yml for full structure
+```
+
+See [docs/i18n.md](docs/i18n.md) for complete translation documentation.
+
+---
+
+## Advanced Features
+
+### Column Visibility & Ordering
+
+Users can:
+- Show/hide columns
+- Drag to reorder columns
+- Pin columns to left or right
+- Reset to defaults
+
+Changes persist in localStorage per table.
+
+### Pinned Columns
+
+Pin columns by default:
+
+```ruby
+column :id, pinned: :left   # Pin to left
+column :actions, pinned: :right  # Pin to right
+```
+
+Users can also pin/unpin columns via the UI.
+
+### Sticky Header
+
+Table headers remain visible while scrolling through table content.
+
+### Export to CSV
+
+Built-in CSV export with:
+- Current filters applied
+- Current sort order
+- Only visible columns
+- All pages (not just current)
+
+---
+
+## Examples
+
+### Basic Table
+
+```ruby
+class UsersTable < Infotable::Base
+  query { User.all }
+
+  column :id, sortable: true
+  column :name, sortable: true, searchable: true
+  column :email, sortable: true
+  column :created_at, type: :datetime, sortable: true
+
+  per_page 25
+  default_sort :created_at, :desc
+end
+```
+
+### Table with Filters
+
+```ruby
+class ProductsTable < Infotable::Base
+  query { Product.all }
+
+  column :name,
+    sortable: true,
+    filterable: true,
+    filter_type: :text
+
+  column :category,
+    sortable: true,
+    filterable: true,
+    filter_type: :select,
+    filter_options: -> { Product.distinct.pluck(:category) }
+
+  column :price,
+    type: :decimal,
+    sortable: true,
+    filterable: true,
+    filter_type: :number,
+    formatter: :currency
+
+  column :in_stock,
+    type: :boolean,
+    filterable: true,
+    formatter: :boolean
+
+  per_page 25
+end
+```
+
+### Table with Custom Formatters
+
+```ruby
+class OrdersTable < Infotable::Base
+  query { Order.includes(:customer) }
+
+  column :order_number,
+    formatter: ->(value, record) {
+      "<code class='font-mono'>#{value}</code>".html_safe
+    }
+
+  column :customer,
+    formatter: ->(value, record) { record.customer.name }
+
+  column :status,
+    type: :badge,
+    formatter: :badge,
+    formatter_options: {
+      colors: {
+        "pending" => "yellow",
+        "processing" => "blue",
+        "shipped" => "green",
+        "delivered" => "green",
+        "cancelled" => "red"
+      }
+    }
+
+  column :total,
+    type: :currency,
+    formatter: :currency,
+    formatter_options: { precision: 2 }
+
+  column :actions,
+    type: :action,
+    formatter: :action,
+    formatter_options: {
+      actions: [
+        { label: "View", url: ->(r) { "/orders/#{r.id}" } },
+        { label: "Invoice", url: ->(r) { "/orders/#{r.id}/invoice" } }
+      ]
+    }
+end
+```
+
+### Infinite Scroll Table
+
+```ruby
+class PostsTable < Infotable::Base
+  query { Post.published.includes(:author) }
+
+  column :title, sortable: true
+  column :author, sortable: true
+  column :published_at, type: :datetime, sortable: true
+
+  infinite_scroll true
+  per_page 50
+  default_sort :published_at, :desc
+end
+```
+
+### Clickable Rows Table
+
+```ruby
+class CommentsTable < Infotable::Base
+  query { Comment.includes(:post) }
+
+  column :body, type: :text
+  column :author_name
+  column :created_at, type: :datetime
+
+  # Make rows clickable
+  row_link ->(record) { "/comments/#{record.id}" }
+
+  # Use slim rows for compact display
+  row_size :slim
+end
+```
+
+### Table with Pinned Columns
+
+```ruby
+class SalesTable < Infotable::Base
+  query { Sale.all }
+
+  column :id, pinned: :left, width: "60px"
+  column :product_name
+  column :quantity
+  column :price, type: :currency
+  column :total, type: :currency
+  column :actions, pinned: :right, type: :action
+end
+```
+
+### Tables with Different Row Sizes
+
+```ruby
+# Slim - Compact for dense data
+class CompactDataTable < Infotable::Base
+  query { Data.all }
+
+  column :id
+  column :name
+  column :value
+
+  row_size :slim # Minimal padding, smaller text
+end
+
+# Mid - Balanced appearance
+class BalancedTable < Infotable::Base
+  query { Product.all }
+
+  column :id
+  column :name
+  column :price, type: :currency
+
+  row_size :mid # Medium padding, normal text
+end
+
+# Default - Comfortable reading
+class ReadableTable < Infotable::Base
+  query { Article.all }
+
+  column :title
+  column :author
+  column :published_at, type: :datetime
+
+  row_size :default # Full padding (or omit - it's the default)
+end
+```
+
+### Table with Virtual (Aggregated) Columns
+
+```ruby
+class ShopsTable < Infotable::Base
+  # Query with aggregated columns
+  query do
+    Shop.select(
+      "shops.*",
+      "COUNT(products.id) AS products_count",
+      "COUNT(accessories.id) AS accessories_count",
+      "SUM(products.price) AS total_products_value"
+    )
+      .left_joins(:products, :accessories)
+      .group("shops.id")
+  end
+
+  # Regular columns - use WHERE for filtering
+  column :id, sortable: true
+  column :name, sortable: true, filterable: true, filter_type: :text
+  column :active, type: :boolean, sortable: true, filterable: true
+
+  # Virtual columns - use HAVING for filtering
+  column :products_count,
+    label: "Products",
+    type: :integer,
+    sortable: true,
+    filterable: true,
+    filter_type: :number,
+    virtual: true,  # ⭐ Enables HAVING clause for filters
+    virtual_sql: "COUNT(products.id)"  # SQL expression for filtering
+
+  column :accessories_count,
+    label: "Accessories",
+    type: :integer,
+    sortable: true,
+    filterable: true,
+    filter_type: :number,
+    virtual: true,  # ⭐ Enables HAVING clause for filters
+    virtual_sql: "COUNT(accessories.id)"  # SQL expression for filtering
+
+  column :total_products_value,
+    label: "Total Value",
+    type: :decimal,
+    sortable: true,
+    filterable: true,
+    filter_type: :number,
+    virtual: true,  # ⭐ Enables HAVING clause for filters
+    virtual_sql: "SUM(products.price)",  # SQL expression for filtering
+    formatter: :currency
+
+  per_page 25
+end
+```
+
+**See [docs/virtual_columns.md](docs/virtual_columns.md) for more examples and detailed explanation.**
+
+---
+
+## Roadmap
+
+- [ ] Server-side persistence of column settings
+- [ ] Table state in the URL
+- [ ] More formatters (link, avatar, percent)
+- [ ] `infotable:table` generator
+- [ ] Tailwind v3 support
+
+---
+
+## Documentation
+
+- [Installation Guide](docs/installation.md) - Detailed setup for all bundlers
+- [Tailwind setup](docs/tailwind.md)
+- [Bundler support](docs/bundlers.md)
+- [Virtual columns](docs/virtual_columns.md)
+- [i18n Guide](docs/i18n.md)
+- [Changelog](CHANGELOG.md)
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jcieslar/infotable.
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).