infotable 1.4.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f00cd7591b4bc03f8f7443771dc1be2abc2e022602a2a2b14a61090d6eea76aa
-  data.tar.gz: 1c48ace8adb272674a1b0138b7aa1744dfe5154695b87ea5e1773cc918d912fc
+  metadata.gz: 31096b54bd71fb8799c287dbd43f91c2e05a3a5d5c8a652bd89f84e97c9fa5ed
+  data.tar.gz: 4cec84bed5d53f7599753fa30183e667833278aa4ebd89484cc2495ace2b7262
 SHA512:
-  metadata.gz: 9ed45ecaf4c41b844dd6a7df34e35bcecefe593fa146fbe352ec9c6e4b20501f7661464a383f6a6ae386190e13d6a4cb395765c6ea4450f1d2637f442256c148
-  data.tar.gz: 79fae3ddc36f3c98c826eb18fcb9856f810e5d8fd2681eb9244ba3577efa7a397b384eb8bb170c791cd1668c5c5f5e444f546553d55cffb0cd099813555366bd
+  metadata.gz: fa78ae7189b9c5ed8363ecd04c9abe444ed51ba3fcf231644fb14b624d5f7aa776811335efafc8ba521b99cfb9d8724ceccec647e3f3398e27377f5bc0ebaec6
+  data.tar.gz: 6bdaf90359935c4a3a1bad5575748b0dd40c47ce01ebd2fc7f8c10c6604d3b7720f9edde5fa387cd5e16868ce48165cc24183d6eeba1474b01b337621bd3829b

data/README.md

@@ -12,7 +12,7 @@ Modern, flexible datatable engine for Rails 8+ with Hotwire. Build beautiful, in
 - 🔧 **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
+- 🌍 **i18n Support** - English, Polish, German, French, Spanish, Greek and Italian translations included
 - 🎯 **Advanced Features** - Infinite scroll, column pinning, drag-to-reorder, row links, and more
 
 ## Quick Start
@@ -129,6 +129,15 @@ Infotable.configure do |config|
 end
 ```
 
+### Security
+
+Tables are served by the engine at `/infotable/tables/:name/{data,export,ids}`. A table without an
+`authorize { |controller| ... }` block is readable (and exportable as CSV) by **everyone who can reach the
+route**, unless the engine controllers inherit your app's authentication. The installer therefore sets
+`config.parent_controller = "ApplicationController"`; keep it (or point it at a controller with your
+`before_action :authenticate_user!`) and add `authorize` to tables with restricted data. The engine's own
+default (`ActionController::Base`) applies no authentication at all.
+
 ### Available Global Options
 
 | Option | Type | Default | Description |
@@ -137,7 +146,8 @@ end
 | `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 |
+| `parent_controller` | String | `"ActionController::Base"` (the installer sets `"ApplicationController"`) | Controller the engine's controllers inherit from. Set it to `"ApplicationController"` to reuse your authentication |
+| `max_select_all` | Integer, nil | `4000` | "Select all N matching" collects at most this many ids (each is sent as `ids[]`; Rack accepts 4096 parameters per request) |
 | `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 |
@@ -155,6 +165,8 @@ 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
+rails generate infotable:table Order --per-page=50 --sort=placed_at:desc --toolbar=rail --checkbox \
+  --authorize="controller.current_user&.admin?"   # also --row-click --infinite-scroll --countless
 ```
 
 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).
@@ -448,6 +460,30 @@ Features:
 - Cmd/Ctrl+Click to open in new tab
 - Ignores clicks on buttons, links, and inputs
 
+#### Row click, classes and data attributes
+
+```ruby
+# Style rows by their data (write the Tailwind classes out in full so they are generated)
+row_class ->(order) { "bg-red-50" if order.overdue? }
+
+# data-* attributes on the <tr>, e.g. for your own Stimulus controller
+row_data ->(post) { { post_id: post.id, status: post.status } }   # data-post-id, data-status
+
+# Rows fire a cancelable `infotable:row-click` event (needs no row_link)
+row_click
+```
+
+Every row also gets `id="<dom_id>"` (`order_42`), so Turbo Streams can target it (`turbo_stream.replace dom_id(order)`, `broadcasts_to`). Rows without a record id are left without one.
+
+Clicking a row (not a link, button or input inside it) first dispatches `infotable:row-click` on the `<tr>`, with `detail: { id, url, data, originalEvent }`. If nothing calls `preventDefault()` and the table has a `row_link`, the click then falls back to following it, so the two compose:
+
+```js
+document.addEventListener("infotable:row-click", event => {
+  if (event.detail.data.status === "locked") event.preventDefault()   // no navigation for locked rows
+  else openPreview(event.detail.data.postId)                          // ...or handle it yourself
+})
+```
+
 #### Row Size
 
 Control table row padding and text size with three options:
@@ -566,6 +602,100 @@ column :actions,
 
 `method:` and `confirm:` use Turbo (`data-turbo-method`, `data-turbo-confirm`). Labels are HTML-escaped.
 
+#### 6. Link Formatter (`:link`)
+
+```ruby
+column :website, formatter: :link, formatter_options: { external: true }   # the value is the URL
+
+column :email,
+  formatter: :link,
+  formatter_options: { url: ->(record) { "mailto:#{record.email}" } }       # email / phone: mailto: and tel:
+
+column :name,
+  formatter: :link,
+  formatter_options: { url: ->(record) { user_path(record) } }              # Proc (run in the view), Symbol or String
+```
+
+Only relative URLs, `http(s)`, `mailto` and `tel` are linked (`javascript:` and friends render as plain text). Options: `url`, `label`, `external` (`target="_blank"` + `rel="noopener noreferrer"`), `class`.
+
+#### 7. Avatar Formatter (`:avatar`)
+
+```ruby
+column :avatar_url,
+  formatter: :avatar,
+  formatter_options: { name: ->(record) { record.name }, size: :md }   # :sm, :md, :lg
+```
+
+The value is the image URL; without one, the initials of `name` are shown on a coloured disc. `label: false` hides the name next to the picture.
+
+#### 8. Percent Formatter (`:percent`)
+
+```ruby
+column :completion, formatter: :percent, formatter_options: { precision: 1, bar: true }
+```
+
+Options: `precision` (default 0), `scale: :percent` (0-100, default) or `:ratio` (0-1), `bar` (small progress bar).
+
+#### 9. Number Formatter (`:number`)
+
+```ruby
+column :views_count, formatter: :number, formatter_options: { compact: true }          # 1.5k, 3.4M
+column :latency,     formatter: :number, formatter_options: { unit: "ms", precision: 1 }
+column :stock,       formatter: :number, formatter_options: { zero: "-" }
+```
+
+Options: `precision`, `delimiter` (`","`), `separator` (`"."`), `unit` (appended), `compact`, `zero` (shown instead of 0).
+
+#### 10. Tags Formatter (`:tags`, alias `:list`)
+
+```ruby
+column :roles,
+  formatter: :tags,
+  formatter_options: { limit: 3, colors: { "admin" => "red" } }
+
+# several values in a cell that is not an attribute: use `value:`
+column :labels, value: ->(post) { post.tags.map(&:name) }, formatter: :tags, formatter_options: { limit: 2 }
+```
+
+The value is an Array, a relation or a comma separated string; each item is a small badge. `limit` shows N items and "+M" (the rest is in its tooltip), `label: ->(item) { item.name }` picks the text, `colors` maps item to badge colour (as in `:badge`), `separator: ", "` renders plain text instead of badges. The CSV export joins the items with `", "`.
+
+#### 11. Truncate Formatter (`:truncate`)
+
+```ruby
+column :description, formatter: :truncate, formatter_options: { length: 80 }
+```
+
+Long text is cut to `length` (default 60, `omission` default `"…"`); the full text is in the cell's tooltip.
+
+#### 12. Image Formatter (`:image`)
+
+```ruby
+column :photo_url,
+  formatter: :image,
+  formatter_options: { size: :md, alt: ->(record) { record.name }, link: true }   # :sm (32px), :md (48px), :lg (64px)
+```
+
+A square thumbnail (use `:avatar` for round pictures). Only http(s) and relative URLs are rendered. `link: true` opens the full image in a new tab.
+
+#### 13. Filesize Formatter (`:filesize`)
+
+```ruby
+column :byte_size, formatter: :filesize        # 1536 => "1.5 KB"
+```
+
+`precision` is the number of significant digits (default 2).
+
+#### 14. Duration Formatter (`:duration`)
+
+```ruby
+column :duration_seconds, formatter: :duration                                        # 3900 => "1h 05m"
+column :duration_seconds, formatter: :duration, formatter_options: { format: :long }  # "1 hour 5 minutes"
+```
+
+The value is in seconds. `parts` limits how many units are shown (default 2). Translated through `infotable.formatters.duration` (Polish plural forms work out of the box).
+
+The Date formatter's `format: :relative` keeps the exact time in a tooltip, and the Currency formatter takes `unit`, `precision`, `delimiter` and `separator` from your locale (`number.currency.format`) for whatever you do not pass.
+
 ### Custom Formatters
 
 #### Lambda/Proc Formatter
@@ -713,7 +843,7 @@ config.autofilter = false # Require "Apply Filters" button click
 
 ## Internationalization (i18n)
 
-InfoTable includes English and Polish translations.
+InfoTable includes English, Polish, German, French, Spanish, Greek and Italian translations. Any key can be overridden in your app.
 
 ### Set Locale
 
@@ -735,7 +865,7 @@ end
 ### Available Languages
 
 - English (`:en`) - Default
-- Polish (`:pl`)
+- Polish (`:pl`), German (`:de`), French (`:fr`), Spanish (`:es`), Greek (`:el`), Italian (`:it`)
 
 ### Customize Translations
 
@@ -750,11 +880,11 @@ en:
         export_csv: "Download CSV"
 ```
 
-### Add New Language
+### Add Another Language
 
 ```yaml
-# config/locales/infotable.es.yml
-es:
+# config/locales/infotable.pt.yml
+pt:
   infotable:
     table:
       buttons:
@@ -804,6 +934,48 @@ Built-in CSV export with:
 
 ---
 
+## MCP Server (AI assistants)
+
+The gem ships an [MCP](https://modelcontextprotocol.io) server, so an AI assistant (Claude Code, Cursor, ...) can create tables in your app: it reads your models, asks you how the table should look, generates `app/infotable/*_table.rb` and checks that it works. It talks to your app over stdio on your machine, no port is opened.
+
+Add the `mcp` gem to the app (it is not a dependency of infotable):
+
+```ruby
+# Gemfile
+gem "mcp", group: :development
+```
+
+Register the server in the client, from the app's root. For Claude Code:
+
+```bash
+claude mcp add infotable -- bundle exec infotable-mcp
+```
+
+or commit a `.mcp.json` (Cursor: `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "infotable": { "command": "bundle", "args": ["exec", "infotable-mcp"] }
+  }
+}
+```
+
+Then ask: *"create an InfoTable table for Order"*. Or use the `new_table` prompt, which makes the assistant ask for the settings first.
+
+| Tool | What it does |
+|------|--------------|
+| `list_models` | Models with column types, enums and associations |
+| `list_tables` | Tables that already exist, with their settings (the house style) |
+| `describe_dsl` | Column options, types, filters, formatters and settings of the installed version |
+| `table_options` | Questions about a new table (columns, sort, per page, toolbar, selection, authorization...) with defaults proposed from the model |
+| `generate_table` | Renders the table with the `infotable:table` generator. Only shows the code; `write: true` saves it, an existing file is replaced only with `overwrite: true` |
+| `validate_table` | Loads a table by name or from source and reports missing columns, a bad `default_sort`, a failing query or a missing `authorize`; `preview: 5` returns the first rows |
+
+The full README is available to the assistant as the `infotable://readme` resource.
+
+Notes: the server boots your app (development environment unless `RAILS_ENV` is set) and reads the development database; it writes only to `app/infotable/`. Tables are generated without `authorize` unless you give one, and `validate_table` warns about that (see [Security](#security)).
+
 ## Examples
 
 ### Basic Table
@@ -1046,10 +1218,6 @@ end
 ## Roadmap
 
 - [ ] Server-side persistence of column settings
-- [ ] Table state in the URL
-- [ ] More formatters (link, avatar, percent)
-- [ ] `infotable:table` generator
-- [ ] Tailwind v3 support
 
 ---