crud_components 0.1.0

data/docs/forms.md

@@ -0,0 +1,253 @@
+# Forms
+
+`crud_form` derives a create/edit form from the same field metadata everything else uses.
+The gem renders the form; **your controller saves it** — there is no gem-owned controller
+and no gem-owned routes. The two are kept from drifting by a shared permit list.
+
+```erb
+<%= crud_form @book %>          <%# edit if persisted, new if not %>
+```
+
+![A derived edit form rendered through simple_form: required marks and valid-state inputs, read-only fields shown as compact labels, and the habtm association as a removable-chip picker with an "add" dropdown](screenshots/form.png)
+
+## The permit list — why fields can't silently fail to save
+
+The form and your strong-params both derive from the same metadata, so a field can't be
+in one and missing from the other. Use the list the gem derived the form from:
+
+```ruby
+def book_params
+  params.require(:book)
+        .permit(*CrudComponents.permitted_attributes(Book, action: action_name.to_sym, ability: current_ability))
+end
+```
+
+The classic "I added a field and it silently doesn't save" bug is structurally
+impossible: the permit list *is* the form's field set, projected to param keys. For
+models that don't `include CrudComponents::Model`, use
+`CrudComponents.permitted_attributes(Model, action:, ability:)` — identical result.
+
+What the list contains, per editable field:
+
+| Field                                         | Permit key                        |
+| --------------------------------------------- | --------------------------------- |
+| column (string/number/date/boolean/enum/text) | `:name`                           |
+| `belongs_to`                                  | `:publisher_id` (the foreign key) |
+| habtm / has_many (ids)                        | `{ author_ids: [] }`              |
+| single attachment                             | `:cover`                          |
+| `has_many_attached`                           | `{ images: [] }`                  |
+
+A `belongs_to` always permits the real foreign key (`:publisher_id`), never the slug —
+even when the target uses `identify_by :slug`. A form POST is a request body, not a
+shareable URL, so the slug buys nothing here (unlike a filter, which puts it in the URL);
+see the mapping-table row below.
+
+Excluded automatically: `id`, `created_at`, `updated_at`, computed fields (no form
+control), JSON columns (read-only in v1), `has_many` that isn't habtm, and any field that
+is non-editable or not permitted for the current user (below).
+
+## Two permission dimensions
+
+Editing introduces a question viewing doesn't: you may *see* a field but not be allowed
+to *change* it. So `editable:` sits alongside `if:`:
+
+```ruby
+attribute :slug,           editable: false        # shown read-only in the form
+attribute :state,          editable: :publish     # editable only if can?(:publish, Book)
+attribute :purchase_price, if: :manage            # invisible to non-managers, everywhere
+```
+
+- **`if:`** controls **visibility** — a field you can't see isn't in the form, the permit
+  list, the query, or any other surface.
+- **`editable:`** controls **writability** — a visible-but-not-editable field renders as
+  compact read-only text and is left out of the permit list. Same callable contract as
+  `if:` (symbol → `can?`, zero-arity lambda, record lambda / `it`); see
+  [Security → permissions](security.md#permissions).
+
+Because both are enforced on the permit list *and* the form, the two can never disagree:
+a user who can't edit a field can neither see an input for it nor smuggle it through
+params.
+
+## Which fields, and where it submits
+
+Form field selection falls back **action → `:form` → `:default`**:
+
+- `fieldset :form, %i[…]` — fields for all forms.
+- `fieldset :edit, %i[…]` / `fieldset :new, %i[…]` — override one form (`:update` maps to
+  `:edit`, `:create` to `:new`).
+- otherwise the `:default` set is used.
+
+New vs. edit (POST vs. PATCH) and the URL are inferred from the record (`persisted?`).
+Override with `url:` / `method:` when routes aren't conventional:
+
+```erb
+<%= crud_form @book, url: publisher_book_path(@publisher, @book), method: :patch %>
+```
+
+## Rendering: simple_form
+
+Forms render through [simple_form](https://github.com/heartcombo/simple_form) (a runtime
+dependency). The gem decides *which* fields appear, their flavor, the permit list and the
+read-only/permission logic; simple_form does the markup — labels, inputs, wrappers,
+required marks, and **per-field error display** — through your app's wrapper config
+(Bootstrap by default; the community ships Tailwind/Bulma/Foundation). So the gem's forms
+inherit your design system automatically, and there's no hand-rolled `field_with_errors`
+to fight.
+
+The flavor → simple_form mapping (one `form_fields/_<type>` partial each):
+
+| Field                             | simple_form call                                                                                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| string / number / date / datetime | `f.input :name` (type inferred from the column)                                                                                                         |
+| text                              | `f.input :name, as: :text`                                                                                                                              |
+| boolean                           | `f.input :name, as: :boolean` (a checkbox; a *nullable* column renders a 3-state Yes / No / not-set select instead)                                     |
+| enum                              | `f.input :name, collection: …` (your i18n'd keys; a *nullable* column adds a blank "not set" option)                                                    |
+| `belongs_to`                      | `f.association :publisher, collection: …` — submits the real **id** (forms are POST bodies, not shareable URLs, unlike filters which use `identify_by`) |
+| habtm                             | `f.association :authors, as: :select, multiple` + a `crud-multiselect` chip-picker hook (see below)                                                     |
+| single / many attachment          | a file input + current preview + a "keep" checkbox per file (signed_id) — see [Attachments](#attachments)                                               |
+| read-only (not editable)          | rendered by the gem as a compact `label: value`, not submitted                                                                                          |
+
+Errors: simple_form shows per-field errors inline; the gem adds a summary for base
+errors (`errors[:base]`) and any error on a column the form doesn't show, so "fix N
+errors" is never a dead end (see [validation errors](#validation-errors) below).
+
+To customise an input, override the per-type partial or point a single field at your own
+(see [Customising an input](#customising-an-input) below) — or use simple_form's own
+wrapper/component config, which the gem inherits.
+
+## Associations and attachments
+
+- **belongs_to** → a select valued by record id; permit `:publisher_id`.
+- **habtm** → a `<select multiple>` baseline (works no-JS, scales) that carries
+  `data-controller="crud-multiselect"`; permit `{ author_ids: [] }`. The optional
+  `crud-multiselect` Stimulus controller (shipped by `crud_components:install`) replaces the
+  select in place with a **chips-list + "add" dropdown** — the select stays the hidden source
+  of truth, so the form submits identically with or without JS. This handles up to a few
+  hundred options client-side.
+  - **Thousands of options?** That needs an autocomplete querying *your* endpoint (the gem
+    owns no controllers). Override the habtm input — drop a `form_fields/_habtm.html.erb`
+    into your app, or set a different `as:`/`input_html` for that field — and point your
+    library (tom-select, select2, a Stimulus+fetch) at your route. The param shape
+    (`author_ids[]`) stays the same, so any library drops in.
+
+### Attachments
+
+Attachment inputs show the **current** file(s) — drawn by content type (image inline, a
+previewable file like a PDF as a preview, anything else a **filetype icon + filename**) —
+and support **keep / add / remove** through the standard permit list with **no controller
+code**. The mechanism rests on one Active Storage fact: *an empty file input submits
+nothing*, so leaving it empty keeps the current file(s).
+
+- **single attachment** (`has_one_attached`) → permit `:cover`. Leave the file input empty
+  to keep; choose a file to **replace**; tick **Remove** to delete (it submits a blank,
+  which purges).
+- **has_many_attached** → permit `{ images: [] }`. Each existing file has a **Keep**
+  checkbox carrying its `signed_id` (untick to remove); the `multiple` file input adds. A
+  hidden blank keeps the array present so unticking everything actually clears it. On save
+  the set becomes exactly the kept ids + new uploads — see Rails'
+  [Replacing vs Adding Attachments](https://guides.rubyonrails.org/active_storage_overview.html#replacing-vs-adding-attachments).
+  Fully derived — see `Author` (`has_many_attached :images`) in the dummy app, *zero* config.
+
+A plain `@record.update(permitted)` keeps / adds / removes correctly; you write no
+attachment-specific controller code.
+
+The non-image fallback icon is chosen by file extension via `config.file_icons` (a map of
+extension → icon name, e.g. `'pdf' => 'filetype-pdf'`, `'zip' => 'file-earmark-zip'`),
+falling back to `config.file_fallback_icon`. The icon *library* is the `icon_prefix` entry
+in the [class map](extending.md#styling). Add or remap an extension in the config, or
+override `crud_components/fields/_attachment_thumb.html.erb` to change the markup.
+
+## Customising an input
+
+Each editable input is rendered through a per-type partial,
+`crud_components/form_fields/_<type>.html.erb`, where `<type>` is the field's form control
+(`string`, `number`, `date`, `datetime`, `text`, `boolean`, `enum`, `belongs_to`, `habtm`,
+`file`). simple_form still does the markup *inside* each partial. Two override levers,
+plus the escape hatch:
+
+- **A whole type** — drop a same-named partial into your app
+  (`app/views/crud_components/form_fields/_enum.html.erb`); Rails view-path precedence picks
+  yours. Every enum input now uses it.
+- **One field** — `attribute :blurb, form_as: :rich_text` points just that field at
+  `form_fields/_rich_text.html.erb`. `form_as:` is the form-side parallel of `as:` (which
+  picks the read-only/display renderer) and defaults to the field's type. The partial
+  receives the simple_form builder `f`, the `field`, and `form`.
+- **Everything** — override `crud_components/_form.html.erb` to take over form rendering
+  entirely.
+
+(There is deliberately no `form` facet — `render`/`filter`/`sort` facets are unchanged;
+forms customise through partials instead.)
+
+## Validation errors
+
+Validations live on your model; the gem re-renders the form correctly after a failed
+save. Your controller renders the form again with the invalid record and a 422:
+
+```ruby
+def update
+  @book = find_book
+  if @book.update(book_params)
+    redirect_to @book
+  else
+    render :edit, status: :unprocessable_entity   # crud_form @book re-renders with errors
+  end
+end
+```
+
+On that re-render:
+
+- **Entered values are kept** — `simple_form_for` reads the in-memory record, which holds
+  the submitted (invalid) attributes, so nothing the user typed is lost.
+- **Per-field errors** render inline (simple_form, via your wrapper config — Bootstrap's
+  `.invalid-feedback` by default).
+- **Base / non-field errors** — `errors[:base]`, or errors on a column the form doesn't
+  show — render in a summary at the top, so a counted error always has somewhere to be
+  fixed.
+
+## Scope (v1)
+
+Single record; flat columns plus belongs_to and habtm. No nested forms /
+`accepts_nested_attributes` and no JSON-column editing in v1.
+
+## A complete example
+
+```ruby
+# app/models/book.rb
+crud_structure do
+  attribute :slug,  editable: false
+  attribute :active, editable: :manage
+  attribute :purchase_price, if: :manage
+  fieldset :form, %i[title subtitle slug blurb price purchase_price pages
+                     published_on genre active publisher authors cover]
+end
+```
+
+```ruby
+# app/controllers/books_controller.rb
+def new   = (@book = Book.new)
+def edit  = (@book = Book.find_by!(slug: params[:id]))
+def create
+  @book = Book.new(book_params)
+  @book.save ? redirect_to(@book) : render(:new, status: :unprocessable_entity)
+end
+def update
+  @book.update(book_params) ? redirect_to(@book) : render(:edit, status: :unprocessable_entity)
+end
+
+private
+
+def book_params
+  params.require(:book).permit(*CrudComponents.permitted_attributes(Book, action: action_name.to_sym, ability: current_ability))
+end
+```
+
+```erb
+<%# app/views/books/edit.html.erb %>
+<%= crud_form @book %>
+```
+
+`slug` shows read-only; `active` is an input only for managers (read-only otherwise);
+`purchase_price` is absent entirely for non-managers — in the form *and* the permit list.
+
+See also: [Fields & rendering](fields.md) · [Views](views.md) · [Security](security.md) ·
+[Extending](extending.md).

data/docs/performance.md

@@ -0,0 +1,90 @@
+# Performance
+
+The gem keeps derived surfaces cheap by default and hands you the controls for the cases
+config can't guess.
+
+## On by default
+
+- **No N+1 from derived columns.** Associations of visible fields (`belongs_to` *and*
+  `has_many`/habtm, plus Active Storage attachments) are eager-loaded for the rendered set.
+  When a `label` or `render` block reaches *further* into associations, declare those deps
+  once — see [Eager-loading render dependencies](#eager-loading-render-dependencies).
+- **Fast cells** — built-in cell types are rendered inline, not a partial per cell — see
+  [Fast cell rendering](#fast-cell-rendering).
+- **belongs_to filters degrade gracefully.** A belongs_to filter renders a `<select>` of
+  the target's records up to `config.select_limit` (default 250); beyond that it switches
+  to a text input over the target's `search_in`, so a 50k-row association never builds a
+  giant `<select>`. (A typeahead/autocomplete is a later version.)
+- **Long text truncates** in collections — the full value renders on the record page.
+
+## Eager-loading render dependencies
+
+*Advanced.* Visible association and attachment columns are eager-loaded automatically.
+The cases the gem **can't** infer are a custom `label` or `render` block that reaches
+*further* into associations (the classic source of a per-row query). Declare those once
+and they compose into the collection's `includes` — declare where the dependency lives,
+and it's correct everywhere that thing is shown:
+
+```ruby
+class Review < ApplicationRecord
+  include CrudComponents::Model
+  crud_structure do
+    # this label reaches :book — eager-loaded whenever a Review is shown as another
+    # model's association column (e.g. a Book's reviews list):
+    label(preload: %i[book]) { |review| "#{review.reviewer_name} on #{review.book.title}" }
+
+    # the `book` column, re-titled for this context, reaches :publisher → nested:
+    attribute :book, label: ->(book) { "#{book.title} (#{book.publisher.name})" }, preload: %i[publisher]
+  end
+end
+
+class Book < ApplicationRecord
+  include CrudComponents::Model
+  crud_structure do
+    # a render block reaching associations on *this* model → top-level:
+    attribute :author_names, preload: %i[authors] do
+      render { |book| book.authors.map(&:name).to_sentence }
+    end
+    # …or model-level and standalone (additive with `label …, preload:`):
+    preload :publisher
+  end
+end
+```
+
+How it composes: an **association column** nests the target's declared preloads — a Book's
+`reviews` column becomes `includes(reviews: %i[book])` because `Review` declared
+`label … preload: %i[book]`; the re-titled `book` column above becomes
+`includes(book: %i[publisher])`. A `preload:` on a **non-association** column loads
+top-level. There's nothing to wire at the call site — the gem adds these to whatever scope
+you render, so `crud_collection @books` is already N+1-free.
+
+## Pagination (you bring it)
+
+The gem **never paginates on its own** — no surprise row limits, no records silently
+dropped. Rendering a 50k-row table unbounded is the documented footgun; bound it yourself:
+
+- Pass a paginated relation and the gem renders a footer pager automatically when it
+  detects one (kaminari / will_paginate, which decorate the relation):
+
+  ```ruby
+  @query = CrudComponents::Query.new(Book, params, ability: current_ability)
+  @books = @query.apply(Book.accessible_by(current_ability)).page(params[:page])  # kaminari
+  ```
+  ```erb
+  <%= crud_collection @books, query: @query %>
+  ```
+
+- Or pass any bounded scope. See [Views → the manual query](views.md#the-manual-query-pagination-and-big-tables)
+  for the full story (including pagy, whose state lives off the relation, so you render its
+  nav yourself).
+
+## Big associations in forms
+
+The derived habtm/has_many input is a `<select multiple>` (optionally enhanced by the
+`crud-multiselect` controller). It loads every option client-side — fine up to a few
+hundred. For thousands of options, don't render them all: override that one field's form
+input with `form_as:` and a [custom partial](forms.md#customising-an-input) that talks to
+your own autocomplete endpoint. Same for a huge belongs_to select — point it at a
+server-backed picker.
+
+See also: [Security](security.md) · [Views](views.md) · [Forms](forms.md).

data/docs/security.md

@@ -0,0 +1,139 @@
+# Security
+
+The gem has two security jobs:
+
+1. **Show only what the user is allowed to see** — and never let them filter or sort by it
+   either. Visibility is permission-aware, end to end.
+2. **Turn untrusted URL params into SQL with no injection** — every value, name and spec
+   that reaches the query is whitelisted, validated and parameterized.
+
+   Both are encoded as tests in
+   [`test/query_security_test.rb`](../test/query_security_test.rb).
+
+## Permissions: `if:` and `editable:`
+
+Two dimensions, declared on an attribute:
+
+```ruby
+attribute :purchase_price, if: :manage          # visible only to managers — hidden everywhere otherwise
+attribute :state,          editable: :publish   # everyone sees it; only :publish may change it in a form
+attribute :slug,           editable: false      # shown read-only in the form, never submitted
+```
+
+- **`if:`** governs **visibility** — and it is total. A field whose `if:` fails is absent
+  from the table, the record view, the form *and the query layer*: you cannot filter,
+  sort or `?q=`-search by a column you may not see. (See [the whitelist](#the-whitelist) and
+  [`?q=` and permissions](#q-search-and-permissions).)
+- **`editable:`** governs **writability in forms** only — a field can be visible but not
+  changeable. `false` (or an unmet permission) renders it read-only and drops it from the
+  [permit list](forms.md#the-permit-list); it stays visible for context.
+
+### Callable forms
+
+Both `if:` and `editable:` accept the same three forms:
+
+```ruby
+if: :manage                                       # Symbol — sugar for can?(:manage, record)
+if: -> { can?(:publish, Book) }                   # zero-arity lambda — ability only
+if: ->(book) { book.draft? }                      # one-arity lambda — receives the record
+if: ->(book) { can?(:edit, book) && book.draft? } # …and can? is in scope too — depend on both
+```
+
+- **Symbol** → `can?(symbol, record)` — the record being decided about (so it matches the
+  derived action check, `can?(:edit, @book)`), or the model class for a column-level
+  decision, where there is no record.
+- **Zero-arity lambda** runs in a context where `can?` works (the view when rendering, a
+  thin ability wrapper when querying); it receives no record.
+- **One-arity lambda** receives the record **and** runs where `can?` works — so a condition
+  can depend on the ability, the record, or both. Where there is no record — a column-level
+  or strong-params check that can't depend on a single row — the lambda is **not run**; it
+  defers to a safe default: visibility (`if:`) shows the column, editability (`editable:`)
+  withholds the field (a class-level permit list can't grant per-record write access).
+
+### The `can?` dependency (there isn't one)
+
+`can?` is **feature-detected**, not required. The gem depends on no authorization library;
+it works with [CanCanCan](https://github.com/CanCanCommunity/cancancan) or anything exposing
+a `can?(action, subject)` method.
+
+- Pass the ability where you build the query, or let auto mode pick up `current_ability`:
+
+  ```ruby
+  CrudComponents::Query.new(Book, params, ability: current_ability)
+  ```
+
+- **No `can?` provider and no ability?** A `Symbol` condition simply evaluates to *not
+  permitted* — the field is hidden. It does **not** raise. Safe by default: absent an
+  authority to say "yes", the answer is "no". (Lambdas that don't call `can?` are
+  unaffected.)
+
+## The whitelist
+
+> **A URL param is applied only if it names a filterable field of the fieldset in play
+> that the current user may see (or a reserved param). Everything else never reaches SQL.**
+
+Two consequences worth stating plainly:
+
+- **You can only filter and sort what you can see.** The set of filterable/sortable fields
+  is the visible fieldset (plus its declared `filters:`), minus anything an `if:` hides.
+- **Hidden data can't be probed.** Because a permission-gated column never reaches the
+  query, you can't bisect an invisible `purchase_price` by watching which rows survive a
+  crafted `purchase_price_geq`.
+
+## The injection-safe URL model
+
+The URL *is* the state — plain GET forms and links, `data-turbo-action="advance"`,
+shareable. Flat params:
+
+| Param                                    | Meaning                                             |
+| ---------------------------------------- | --------------------------------------------------- |
+| `?title=ruby`                            | filter a field (text / enum / boolean / belongs_to) |
+| `?price=12` / `?published_on=2026-01-01` | exact match (number / single day)                   |
+| `?price_geq=10&price_leq=20`             | ranges (numeric, date; dates whole-day-inclusive)   |
+| `?q=tolkien`                             | global search through `search_in`                   |
+| `?sort=title&dir=desc`                   | sorting; composes with active filters               |
+| `?cols[]=title&cols[]=price`             | column-picker selection (ordered, permitted subset) |
+
+`q`, `sort`, `dir`, `page`, `per`, `cols` are **reserved** — they're the gem's own control params.
+A field named after one would silently shadow it, so the gem raises at boot instead; rename
+the field (or scope the whole collection with `param_prefix: :books`, which prefixes every
+param). With `param_prefix:`, unprefixed params are ignored.
+
+The guarantees, each backed by a test:
+
+- **Unknown / non-scalar params are inert.** Only whitelisted fields are read; `?title[]=…`
+  and `?title[x]=…` are ignored.
+- **No injection through `sort`/`dir`.** `sort` resolves against sortable fields only —
+  `?sort=title;DROP TABLE books` yields *no* `ORDER BY`, not an escaped one. `dir` is
+  validated to `asc`/`desc`.
+- **`?cols=` can only narrow, never widen.** The column-picker selection is intersected
+  with the permitted column set, so a forged or stale `cols` (or a `picked_columns:` default
+  naming a now-gated column) can hide or reorder columns but never surface one the `if:`
+  gate forbids.
+- **Escaped LIKE.** Wildcards (`%`, `_`) and the backslash escape itself are escaped
+  (`sanitize_sql_like` with an explicit `\`), so `%` matches a literal percent.
+- **Validated casts.** Enum values are checked against the enum; booleans against an
+  explicit set (`t/f/1/0/yes/no/on/off`); numeric/date casts reject the unparsable *and*
+  the non-finite (`NaN`, `Infinity`). Anything invalid leaves the scope unchanged.
+- **belongs_to by `identify_by`.** belongs_to params resolve through the target's
+  `identify_by` column as a parameterized subquery — never a raw id (unless `identify_by`
+  is `:id` (default)).
+- **Specs are author-written.** A search spec contains only column/association names you
+  wrote; the gem builds joins + parameterized ILIKE from it. The one place SQL is
+  hand-written is the escape-hatch `filter { |scope, value| … }` block — and `where_like`
+  exists so you rarely need to. Raw SQL in a block is your responsibility.
+
+## `?q=` search and permissions
+
+`search_in` is the model's **text identity**, used model-globally (it powers `?q=`, the
+belongs_to text fallback, and delegated specs). Two things follow:
+
+- A **declared, permission-gated** column (`attribute :notes, if: :manage`) is dropped from
+  the search spec for a user who can't see it — `?q=` upholds "hidden everywhere".
+- An **undeclared** column in the zero-config default spec (all string/text columns) is
+  searched model-globally by design. If a model has a sensitive string column you don't
+  want reachable via `?q=`, declare `search_in` explicitly with only the columns you want.
+  The default is broad so zero-config search "just finds things"; narrowing it is the
+  author's call.
+
+  See also: [Performance](performance.md) · [Views](views.md) · [Fields](fields.md) · [Forms](forms.md).