RubyGems - cafe_car - Versions diffs - 0.2.1 → 0.3.0 - Mend

cafe_car 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (110) hide show

checksums.yaml +4 -4
data/.claude-plugin/marketplace.json +23 -0
data/README.md +417 -29
data/Rakefile +2 -2
data/app/assets/stylesheets/cafe_car/chart.css +41 -0
data/app/assets/stylesheets/cafe_car/dashboard.css +43 -0
data/app/assets/stylesheets/cafe_car/filters.css +50 -0
data/app/assets/stylesheets/cafe_car/themes/cool2.css +2 -0
data/app/assets/stylesheets/cafe_car/themes/warm.css +30 -0
data/app/assets/stylesheets/cafe_car/tooltips.css +1 -1
data/app/assets/stylesheets/cafe_car.css +14 -4
data/app/assets/stylesheets/tom-select.css +95 -0
data/app/assets/stylesheets/ui/Button.css +7 -5
data/app/assets/stylesheets/ui/Input.css +92 -1
data/app/assets/stylesheets/ui/Page.css +7 -0
data/app/assets/stylesheets/ui/Table.css +25 -0
data/app/controllers/cafe_car/dashboards_controller.rb +29 -0
data/app/javascript/cafe_car.js +68 -0
data/app/javascript/tom-select.complete.min.js +444 -0
data/app/policies/cafe_car/application_policy.rb +1 -1
data/app/presenters/cafe_car/active_storage/attachment_presenter.rb +4 -1
data/app/presenters/cafe_car/presenter.rb +2 -2
data/app/views/application/_actions.html.haml +9 -0
data/app/views/application/_active_filters.html.haml +15 -0
data/app/views/application/_belongs_to_filter.html.haml +6 -0
data/app/views/application/_boolean_filter.html.haml +4 -0
data/app/views/application/_bulk_actions.html.haml +9 -0
data/app/views/application/_chart.html.haml +18 -0
data/app/views/application/_controls.html.haml +8 -0
data/app/views/application/_enum_filter.html.haml +5 -0
data/app/views/application/_filter.html.haml +4 -0
data/app/views/application/_filters.html.haml +13 -4
data/app/views/application/_has_many_filter.html.haml +7 -0
data/app/views/application/_head.html.haml +1 -0
data/app/views/application/_index.html.haml +3 -1
data/app/views/application/_index_actions.html.haml +12 -3
data/app/views/application/_navigation.html.haml +5 -0
data/app/views/application/_nested_field.html.haml +1 -1
data/app/views/application/_range_filter.html.haml +8 -0
data/app/views/application/_scope_filter.html.haml +5 -0
data/app/views/application/_string_filter.html.haml +4 -0
data/app/views/application/_table.html.haml +8 -6
data/app/views/application/_text_filter.html.haml +1 -0
data/app/views/cafe_car/application/index.html.haml +5 -2
data/app/views/cafe_car/dashboard/_chart.html.haml +11 -0
data/app/views/cafe_car/dashboard/_metric.html.haml +4 -0
data/config/brakeman.ignore +0 -48
data/config/importmap.rb +1 -0
data/config/locales/en.yml +60 -0
data/config/routes.rb +15 -2
data/lib/cafe_car/attributes.rb +40 -12
data/lib/cafe_car/chart_builder.rb +217 -0
data/lib/cafe_car/controller/filtering.rb +108 -6
data/lib/cafe_car/controller.rb +220 -11
data/lib/cafe_car/engine.rb +2 -2
data/lib/cafe_car/field_info.rb +14 -4
data/lib/cafe_car/filter/field_info.rb +56 -7
data/lib/cafe_car/filter/form_builder.rb +57 -7
data/lib/cafe_car/filter_builder.rb +14 -1
data/lib/cafe_car/form_builder.rb +61 -6
data/lib/cafe_car/helpers.rb +196 -0
data/lib/cafe_car/inputs/association_input.rb +11 -0
data/lib/cafe_car/inputs/base_input.rb +56 -7
data/lib/cafe_car/inputs/boolean_input.rb +9 -0
data/lib/cafe_car/inputs/date_input.rb +8 -0
data/lib/cafe_car/inputs/datetime_input.rb +8 -0
data/lib/cafe_car/inputs/file_input.rb +11 -0
data/lib/cafe_car/inputs/nested_input.rb +10 -0
data/lib/cafe_car/inputs/number_input.rb +9 -0
data/lib/cafe_car/inputs/password_input.rb +4 -2
data/lib/cafe_car/inputs/rich_text_input.rb +9 -0
data/lib/cafe_car/inputs/select_input.rb +10 -0
data/lib/cafe_car/inputs/string_input.rb +3 -1
data/lib/cafe_car/inputs/text_area_input.rb +9 -0
data/lib/cafe_car/link_builder.rb +11 -0
data/lib/cafe_car/model.rb +37 -8
data/lib/cafe_car/navigation.rb +10 -0
data/lib/cafe_car/policy.rb +85 -15
data/lib/cafe_car/query_builder.rb +22 -0
data/lib/cafe_car/routing.rb +26 -2
data/lib/cafe_car/table/builder.rb +1 -1
data/lib/cafe_car/table/foot_builder.rb +1 -0
data/lib/cafe_car/table/head_builder.rb +6 -0
data/lib/cafe_car/table/row_builder.rb +7 -0
data/lib/cafe_car/version.rb +1 -1
data/lib/cafe_car.rb +32 -2
data/lib/generators/cafe_car/agents/USAGE +13 -0
data/lib/generators/cafe_car/agents/agents_generator.rb +49 -0
data/lib/generators/cafe_car/resource/resource_generator.rb +12 -1
data/lib/tasks/demo.rake +9 -0
data/llms.txt +25 -0
data/skills/cafe_car/SKILL.md +135 -0
data/skills/cafe_car/references/components.md +93 -0
data/skills/cafe_car/references/controllers.md +106 -0
data/skills/cafe_car/references/filtering.md +102 -0
data/skills/cafe_car/references/forms.md +84 -0
data/skills/cafe_car/references/locales.md +74 -0
data/skills/cafe_car/references/navigation.md +67 -0
data/skills/cafe_car/references/policies.md +112 -0
data/skills/cafe_car/references/presenters.md +76 -0
data/skills/cafe_car/references/turbo.md +53 -0
data/skills/cafe_car/references/views.md +96 -0
metadata +59 -16
data/app/assets/stylesheets/cafe_car/themes/warm-dark.css +0 -29
data/app/views/application/_search.html.haml +0 -6
data/lib/cafe_car/auto_resolver.rb +0 -49
data/lib/cafe_car/inputs/association_builder.rb +0 -6
data/lib/cafe_car/inputs/belongs_to_builder.rb +0 -6
data/lib/tasks/holdco_tasks.rake +0 -532
data/lib/tasks/templates/tasks_header.md +0 -37

data/skills/cafe_car/references/components.md ADDED Viewed

@@ -0,0 +1,93 @@
+# Components, CSS, theming
+Source: `lib/cafe_car/component.rb`, declarations in `app/ui/cafe_car/ui/*.rb`,
+styles in `app/assets/stylesheets/` (all in the gem). This is CafeCar's own
+component system — not ViewComponent or Phlex. Any capitalized call in a view is a
+component.
+## Using components
+```haml
+= Card title: object.title, image: object.logo, actions: object.controls do |card|
+  = card.Section object.show(:price)
+  = card.Foot do
+    = Button :primary, href: href_for(record) do
+      = t(:show)
+```
+- **Flags** are bare symbols: `Button :primary`, `Button :danger`, `Card :slim`,
+  `Page :slim, :center`. They become CSS modifier classes (`Button-primary`).
+- **Options** are keywords the component declares (`title:`, `image:`, `actions:`,
+  `href:`, `tip:`, `tag:`, `data:`). Anything with `href:` renders as a link and
+  gets `current`/`ancestor` classes automatically.
+- **Children** are capitalized methods on the block arg: `card.Section`,
+  `card.Foot`, `page.Body`, `page.Aside`. Undeclared children work too — they
+  become nested class names (`a.Title` inside `Article` → `Article_Title`).
+- A component that captures blank content renders nothing — no empty wrappers.
+Shipped components include `Page`, `Card`, `Grid`, `Row`, `Group`, `Button`,
+`Field`, `Table`, `Alert`, `Menu`, `Navigation`, `Modal`, `Icon`, `Controls`.
+Declarations live in the gem's `app/ui/cafe_car/ui/` (e.g. `Card` declares its
+flags, options, and named children there).
+## Custom components — drop a partial
+No registration. Calling `ui.Badge` (or `= Badge` in a view) looks for a partial at
+`ui/badge`; give it one:
+```haml
+-# app/views/cafe_car/ui/_badge.html.haml
+%span{ class: badge.class_name }= yield
+```
+Locals: the component instance under its name (`badge`), plus `options` and
+`flags`. The same mechanism overrides the markup of a *shipped* component — a host
+`app/views/cafe_car/ui/_card.html.haml` replaces Card's markup app-wide while
+keeping its Ruby API.
+For behavior-bearing components, declare a class the way the gem does:
+```ruby
+# app/ui/cafe_car/ui/badge.rb (host)
+module CafeCar
+  module UI
+    component :Badge do
+      flag :success
+    end
+  end
+end
+```
+## CSS — no styles outside components
+Owner rule: global CSS is banned; it breaks components reused in unexpected places.
+Every component has a scoped stylesheet (gem: `app/assets/stylesheets/ui/Card.css`
+etc.) selecting its own class (`.Card`, `.Button-danger`). Style a new component
+with its own file selecting its own class names; never restyle tags or other
+components globally. The gem's `cafe_car.css` organizes everything in cascade
+layers (`vendor, default, theme, component, modifier, layout, utility`).
+## Theming
+Three bundled themes — sets of CSS custom properties with dark-mode variants:
+```ruby
+# config/initializers/cafe_car.rb
+CafeCar.theme = :cool    # :warm (default), :cool, :cool2
+```
+The theme is injected as a `<link>` in `<head>` after `application.css`. All tokens
+are defined on `:root` in the gem's `themes/defaults.css`: `--accent`, `--primary`,
+`--danger`, `--card`, `--button`, `--link`, `--font-family`, `--gap`, `--radius`,
+`--page-width`, and friends.
+**Caveat:** `CafeCar.theme=` only accepts the bundled names (raises otherwise) —
+you cannot register a new named theme. For a custom look, pick the closest bundled
+theme and override its `:root` tokens with CSS loaded *after* the theme link —
+either override the `_head` partial to append your stylesheet after
+`theme_stylesheet_tag`, or use a higher-specificity selector (e.g. `:root:root`)
+in your `application.css`:
+```css
+:root:root { --accent: #7c3aed; --radius: 6px; }
+```

data/skills/cafe_car/references/controllers.md ADDED Viewed

@@ -0,0 +1,106 @@
+# Controllers
+Source: `lib/cafe_car/controller.rb` (the `CafeCar::Controller` concern — usually
+included in the host's `ApplicationController` by the installer).
+## The macro
+```ruby
+module Admin
+  class ProductsController < ApplicationController
+    cafe_car
+  end
+end
+```
+`cafe_car` wires the full CRUD surface: `index show new edit create update destroy`,
+plus `batch` (bulk actions) and `options` (association-select typeahead JSON). It
+authorizes every action through Pundit (`verify_authorized` and
+`verify_policy_scoped` are enforced), responds to `:html`, `:json`, `:turbo_stream`,
+and `:csv`, rescues validation failures into a re-rendered form, and appends the
+engine's view fallbacks.
+The model is inferred from the controller name (`Admin::ProductsController` →
+`Product`). Variants:
+```ruby
+cafe_car only: %i[index show]          # limit actions
+cafe_car except: %i[destroy]
+cafe_car model: Company                # or the standalone `model Company` macro
+class AttachmentsController < ApplicationController
+  cafe_car
+  model ::ActiveStorage::Attachment    # point at any model, even a library's
+  default_view :grid                   # index defaults to grid instead of table
+end
+```
+## The scope pipeline
+Every action reads records through one method:
+```ruby
+def scope = model.all.then { policy_scope _1 }
+                     .then { sorted _1 }
+                     .then { filtered _1 }
+                     .then { eager_loaded _1 }
+                     .then { paginated _1 }
+```
+`policy_scope` applies the policy's `Scope#resolve`; `sorted` reads `?sort=`;
+`filtered` reads the dot-query params and `?q=`; `eager_loaded` preloads displayed
+associations (no N+1); `paginated` is Kaminari (`?page=`, `?per=` capped at
+`CafeCar.max_per_page`). CSV requests skip pagination and export the whole
+filtered set.
+Narrow one controller without touching the policy:
+```ruby
+class Admin::PublishedArticlesController < ApplicationController
+  cafe_car model: Article
+  def scope = super.published
+end
+```
+Prefer the policy `Scope` when the restriction is about *who may see what*; override
+`scope` when it's about *what this particular screen lists*.
+## Objects and callbacks
+`object` / `objects` are the current record/collection, also exposed as the
+conventional ivars (`@product`, `@products`). Lifecycle callbacks exist for
+`:create`, `:update`, `:destroy`, and `:render`:
+```ruby
+class ProductsController < ApplicationController
+  cafe_car
+  after_create do
+    NotificationMailer.product_created(object).deliver_later
+  end
+end
+```
+(`before_`/`around_`/`after_` + `skip_*` helpers are defined for each; blocks run in
+controller context around `object.save!` / `object.destroy!`.)
+## Extra endpoints
+Host routes drawn with `resources` automatically gain two collection routes
+(`lib/cafe_car/routing.rb`):
+- `POST /products/batch` — applies a bulk action to selected ids. The action name
+  must be in the policy's `permitted_bulk_actions`; each record is authorized
+  individually against `<action>?` then receives `<action>!`. See
+  [policies.md](policies.md).
+- `GET /products/options?q=…` — policy-scoped `[{value, text}]` JSON feeding the
+  searchable association selects. See [forms.md](forms.md).
+## Responses
+Success responds per format: HTML redirects with a locale-driven flash
+(`flashes.create_html` etc.), turbo_stream emits a page refresh (morph — see
+[turbo.md](turbo.md)), JSON serializes `[:id] + attributes.displayable` per the
+policy. Validation failure re-renders `new`/`edit` with `422`. Authorization failure
+returns 403 — or redirects to login when the opt-in sessions are installed
+(`bin/rails g cafe_car:sessions`).

data/skills/cafe_car/references/filtering.md ADDED Viewed

@@ -0,0 +1,102 @@
+# Filtering, sorting, search
+Source: `lib/cafe_car/param_parser.rb`, `lib/cafe_car/query_builder.rb`,
+`lib/cafe_car/controller/filtering.rb`, `lib/cafe_car/queryable.rb`,
+`lib/cafe_car/model.rb`.
+On an index request, every query param that isn't a control param
+(`sort page per view tab q chart_* …`) is a filter. **Never invent bespoke filter
+params for an admin screen — link with this grammar** and the whole pipeline (table,
+grid, chart, CSV export, pagination) honors it.
+## The dot-query URL grammar
+| URL | Meaning |
+|---|---|
+| `?name=Widget` | `name = 'Widget'` |
+| `?status.eq=active` | explicit equals |
+| `?price.min=10&price.max=50` | `>=` and `<=` (aliases `gte`/`lte`; also `gt`/`lt`) |
+| `?created_at=2024-01-01..2024-12-31` | range (`...` = exclusive end) |
+| `?tags=red,blue,green` | `IN (…)` |
+| `?name!=bob` | negate any filter (`!` suffix on the key) |
+| `?name~=^wid` | regex match, case-insensitive (`~` suffix) |
+| `?author=true` / `?author=false` | association exists / doesn't |
+| `?line_items=3`, `?line_items.min=2` | association count |
+| `?author.name~=bob` | filter through an association (nests recursively) |
+| `?published=true` | call a model scope (zero-arity); with a value, the value is the argument |
+| `?q=widget` | keyword search (see below) |
+Datetime values parse with Chronic, so `?created_at.min=last%20week` works. Combine
+freely; everything composes with `sort`, `q`, `view`, and `.csv`.
+## Sorting
+```
+?sort=name              ascending
+?sort=-price            descending
+?sort=category,-price   multiple
+?sort=author.name       through a belongs_to (joins automatically)
+```
+Keys are validated against real columns/associations — bad input is dropped, never
+raw SQL. Table headers emit these links already.
+## Keyword search
+`?q=term` matches case-insensitively across the model's string/text columns
+(parameter-filtered columns like passwords are skipped). A model overrides the
+default by defining a `search` scope:
+```ruby
+scope :search, ->(term) { query("title~": term) }
+```
+## Programmatic: `Model.query`
+The same engine, from Ruby — available on every model with no opt-in:
+```ruby
+Article.query("published" => true, "author.name~" => "bob")
+Invoice.query("total.min" => 100)
+Article.query(["draft term"])        # a bare string routes to search
+```
+Returns a relation; chain as usual.
+## CSV export
+Every index responds to `.csv` (the toolbar has a Download CSV button). The export
+carries the current filters + sort, spans the whole result set (not just the page),
+mirrors the policy's displayable columns, and is capped at
+`CafeCar.csv_export_row_limit` (default 10,000; truncation sets
+`X-CafeCar-Truncated: true`).
+## Chart view
+Every index has a third view beside table and grid:
+```
+?view=chart&chart_x=published_at&chart_by=month        # count per month
+?view=chart&chart_x=issued_on&chart_y=sum:total        # or sum:/avg: of a numeric column
+```
+Buckets `day`/`week`/`month`; columns are validated against the policy's
+displayable date/numeric attributes. The chart aggregates the same filtered,
+policy-scoped collection the table shows, as dependency-free inline SVG.
+## Filter panel
+The grammar above also drives a rendered panel: the model policy's
+`permitted_filters` enumerates the controls (one typed per attribute), and the
+same list is the query whitelist. List a dot-path to filter through an
+association:
+```ruby
+def permitted_filters = %i[status client.status client.owner_id]
+```
+Each hop is the association name; the terminal may be the far column, its enum,
+or a belongs_to (`client.owner_id` ≡ `client.owner`). The control is typed by
+that terminal. An undeclared path — even one naming a real far column
+(`?client.owner.email=`) — is pruned before any join, exactly like an
+unpermitted top-level column.

data/skills/cafe_car/references/forms.md ADDED Viewed

@@ -0,0 +1,84 @@
+# Forms
+Source: `lib/cafe_car/form_builder.rb`, `lib/cafe_car/field_builder.rb`,
+`lib/cafe_car/field_info.rb`. CafeCar controllers set `CafeCar::FormBuilder` as the
+default form builder, so plain `form_for`/`form_with` get all of this.
+The default `_form` partial renders every field the policy permits — most form
+changes are `permitted_attributes` changes (see [policies.md](policies.md)), not
+view changes.
+## Builder methods
+```haml
+= form_for object, url: href_for(object) do |f|
+  = f.field :name                 -# label + input + hint + error, wrapped in a Field
+  = f.field :price
+  = f.association :category      -# searchable select (see below)
+  = f.remaining_fields           -# every editable attribute not yet rendered
+  = f.submit
+```
+- `f.field(method)` — the full labeled field. This is what the default form loops.
+- `f.input(method, as: nil, **opts)` — just the input; `as:` forces a helper
+  (`as: :hidden_field`, `as: :text_area`, …).
+- `f.association(method)` — a select for a `belongs_to`/`has_many`.
+- `f.remaining_fields` — `policy.attributes.editable` minus fields already built;
+  keeps custom forms policy-driven instead of hand-listing everything.
+- `f.hidden(:a, :b)`, `f.label`, `f.hint`, `f.error` as expected. Labels append `*`
+  for presence-validated fields; label/hint/placeholder text comes from the locale
+  (see [locales.md](locales.md)).
+## Type inference
+`FieldInfo#input` picks the input from the schema — string/decimal → text field,
+text/json → textarea, integer → number, boolean → checkbox, date/datetime → typed
+pickers, `has_secure_password` digests → password fields, ActiveStorage attachments
+→ file field (`multiple` for `has_many_attached`), ActionText → rich text area,
+`belongs_to`/`has_many` → association select, `accepts_nested_attributes_for` →
+nested sub-forms.
+## Association selects
+`f.association :client` renders a select capped at `CafeCar.max_collection_options`
+(default 100) options, enhanced with Tom Select typeahead that queries the model's
+policy-scoped `GET /clients/options?q=…` feed — records past the cap stay reachable,
+hidden rows never leak, and without JS it degrades to a plain select. Option labels
+come from each record's presented `title`.
+## Nested records
+`accepts_nested_attributes_for :line_items, allow_destroy: true` plus the permit:
+```ruby
+def permitted_attributes
+  [ :number, :issued_on,
+    line_items_attributes: [ :id, :_destroy, *policy(LineItem).permitted_attributes ] ]
+end
+```
+The default form then renders add/remove-able line-item rows with no view code.
+`f.fields_for :line_items` (no block) renders each sub-record's
+`remaining_fields`.
+## Overriding how a field type renders
+`f.field` renders through a partial named after the field's type —
+`_<type>_field.html.haml`, falling back to the generic `_field.html.haml`:
+```haml
+-# app/views/application/_string_field.html.haml  (app-wide for all string fields)
+-# app/views/admin/products/_string_field.html.haml  (this resource only)
+= field.wrapper do
+  = field.label
+  = field.input data: { controller: "autosize" }
+  = field.error
+```
+The `field` local is a `FieldBuilder`: `field.label` / `field.input` / `field.hint`
+/ `field.error` / `field.info` (the `FieldInfo`). Type names match the inference
+above: `string`, `text`, `integer`, `boolean`, `date`, `datetime`, `password`,
+`attachment`, `nested`, `belongs_to`, `has_many`, `json`.
+(`lib/cafe_car/inputs/` exists in the gem but is dormant — the live path is
+FieldBuilder + FieldInfo + these partials.)

data/skills/cafe_car/references/locales.md ADDED Viewed

@@ -0,0 +1,74 @@
+# Locales — all UI copy lives here
+Source: `config/locales/en.yml` in the gem. Owner rule: **no hardcoded UI strings
+in templates.** Every label, flash, confirm, hint, and button style resolves
+through I18n; the gem ships defaults and a host overrides by defining the same key
+in its own `config/locales/*.yml`.
+When adding UI (a bulk action, a button in an overridden partial, a nav icon), add
+its copy to the locale — don't inline the string.
+## The key map
+```yaml
+en:
+  # Action labels (bulk-action buttons, controls): en.<action>
+  publish: Publish
+  destroy: Delete
+  # Bulk-action button styles — a Button flag per action name
+  bulk_actions:
+    styles:
+      destroy: danger        # shipped default; add your own actions here
+  # Sidebar icons (Iconoir names), per controller
+  navigation:
+    icon:
+      products: box-iso
+  # Control links (show/edit/delete clusters): labels, confirms, disabled tooltips
+  controls:
+    confirm:
+      destroy: This %{Model} will be PERMANENTLY deleted. Are you sure?
+    disabled:
+      policy:
+        default: You don't have permission to %{action} this %{model}.
+  # Flash messages after CRUD actions
+  flashes:
+    create_html: "%{Model} created."
+    update_html: "%{Model} updated."
+    destroy_html: "%{Model} deleted."
+  # Dashboard metric tile labels (non-:all metrics)
+  metrics:
+    published: Published
+  # Per-field form copy: helpers.<kind>.<model>.<attribute>
+  helpers:
+    label:       { article: { title: Headline } }
+    hint:        { article: { summary: Shown on the index card. } }
+    placeholder: { article: { title: e.g. “Q3 results” } }
+    prompt:      { invoice: { client_id: Pick a client… } }
+  # Model & attribute names — standard Rails
+  activerecord:
+    models:
+      article: Post
+    attributes:
+      article:
+        title: Headline
+```
+Interpolations like `%{Model}`/`%{Models}`/`%{Action}` are provided (capitalized
+and lowercase variants).
+## Where they're read
+- Bulk-action bar: label `en.<name>`, style `bulk_actions.styles.<name>`, confirm
+  `helpers.bulk_confirm`.
+- Form fields: `helpers.label/hint/placeholder/autocomplete/prompt.<model>.<attr>`
+  (FieldInfo), falling back to `human_attribute_name`.
+- Attribute/column headers everywhere: `activerecord.attributes`.
+- Flashes: `flashes.<action>_html` via the presenter's `i18n`.
+- Chart/dashboard strings: `chart.*`, `dashboard.*`.

data/skills/cafe_car/references/navigation.md ADDED Viewed

@@ -0,0 +1,67 @@
+# Navigation and the dashboard
+Source: `lib/cafe_car/navigation.rb`, `app/views/application/_navigation.html.haml`
+and `_navigation_links.html.haml` (in the gem).
+## The sidebar is route-driven — there is no menu registry
+The sidebar lists every named `index` route in the app (Rails internals excluded),
+grouped by namespace (`admin/…` routes render under an "Admin" heading). So:
+- **Add a sidebar link:** add `resources :things` to the routes. That's it.
+- **Remove one:** don't draw an index route (`resources :things, except: :index`
+  or `only:` what you need).
+The current page's link highlights automatically (`current`/`ancestor` classes).
+## Icons come from the locale
+`navigation.icon.<controller_name>` maps a controller to an
+[Iconoir](https://iconoir.com) icon name:
+```yaml
+en:
+  navigation:
+    icon:
+      products: box-iso
+      invoices: page-flip
+```
+No key, no icon — the link still renders.
+## Customizing
+Override the partials like any other ([views.md](views.md)):
+- `app/views/application/_navigation.html.haml` — the whole sidebar (dashboard
+  link, route links, session link).
+- `app/views/application/_navigation_links.html.haml` — just the grouped route
+  list; the `navigation` helper exposes `navigation.groups` / `navigation.routes`.
+- A per-resource `_navigation.html.haml` changes (or, if empty, hides) the sidebar
+  for that resource's pages only.
+## The dashboard — opt in by writing one view
+No template, no dashboard: the route always exists, but it 404s and shows no nav
+link until the host writes `app/views/cafe_car/dashboard/show.html.haml`:
+```haml
+- title "Dashboard"
+= Page title: "Dashboard" do |page|
+  = page.Body do
+    .Dashboard
+      = metrics Article
+      = metric("Signups today") { User.where(created_at: Date.current.all_day).count }
+      = chart "New articles", model: Article, x: :created_at, by: :month
+```
+- `metrics(Model)` — one count tile per scope named in the model policy's
+  `permitted_metrics` (`:all` = whole relation). Policy-driven; the default choice.
+- `metric("Label") { … }` — one tile with whatever the block returns.
+- `chart "Title", model:, x:, by:` — the inline-SVG bar chart, bucketing over the
+  `x` date column at `:day`/`:week`/`:month`. Column names are validated against
+  the policy's date columns — never raw SQL.
+It's a plain view: add headings, your own partials, anything between tiles. Once
+the file exists a Dashboard link appears at the top of the sidebar.

data/skills/cafe_car/references/policies.md ADDED Viewed

@@ -0,0 +1,112 @@
+# Policies — the source of truth
+Source: `lib/cafe_car/policy.rb` and `app/policies/cafe_car/application_policy.rb`
+in the gem. The host's `ApplicationPolicy` subclasses `CafeCar::ApplicationPolicy`;
+each model gets a `<Model>Policy` (standard Pundit naming).
+The policy declares, the UI renders. Before overriding a view, check whether the
+change is really a policy change — usually it is.
+## Action predicates
+All default to `false` (deny). `new?` follows `create?`, `edit?` follows `update?`.
+```ruby
+class ArticlePolicy < ApplicationPolicy
+  def index?   = true
+  def show?    = object.published? || edit?
+  def create?  = true
+  def update?  = user.admin? || object.author_id == user.id
+  def destroy? = !object.published?
+end
+```
+`object` is the record (or the class, on collection checks); `user` is the current
+user. Predicates gate controller actions, and the default views hide/disable
+controls the policy denies — a denied Edit link renders disabled with a
+locale-driven tooltip, not hidden by hand.
+## Visible rows: `Scope#resolve`
+```ruby
+class Scope < Scope
+  def resolve = user.admin? ? scope.all : scope.where(owner: user)
+end
+```
+Every index, CSV export, chart, bulk action, and typeahead feed passes through this
+— restricting here restricts everywhere. The base `Scope#resolve` raises until you
+define it.
+## Editable fields: `permitted_attributes`
+```ruby
+def permitted_attributes = %i[name price description category_id]
+```
+Drives both strong parameters *and* the default form (it renders exactly these
+fields, in this order). Vary by record state or action:
+```ruby
+def permitted_attributes
+  if object.try(:new_record?) || me?
+    %i[name email avatar password password_confirmation]
+  else
+    %i[name email avatar]
+  end
+end
+def permitted_attributes_for_create = %i[name email owner_id]  # per-action variant
+```
+Nested records permit `<assoc>_attributes` the Rails way (with `:id` + `:_destroy`
+for `allow_destroy`):
+```ruby
+def permitted_attributes
+  [ :number, :issued_on, :paid,
+    line_items_attributes: [ :id, :_destroy, *policy(LineItem).permitted_attributes ] ]
+end
+```
+## Displayed fields (derived — usually leave alone)
+- `attributes.displayable` — what show pages/tables/JSON/CSV display: permitted
+  keys ∪ columns, with foreign keys folded into their associations and
+  Rails-parameter-filtered columns (passwords, tokens) removed.
+- `attributes.editable` — what the form renders, derived from `permitted_attributes`.
+- `title_attribute` — the record's display name; defaults to the first displayable
+  attribute. Override when wrong: `def title_attribute = :number`.
+- `logo_attribute` — the attachment used as avatar/card image; defaults to the
+  first listable attachment.
+## Bulk actions: `permitted_bulk_actions`
+Default `%i[destroy]`. A custom action is three conventional pieces — no
+registration anywhere:
+```ruby
+# app/models/article.rb — the behavior
+def publish! = update!(published_at: Time.zone.now)
+# app/policies/article_policy.rb — the authorization + the list
+def publish? = !object.published?
+def permitted_bulk_actions = %i[publish destroy]
+```
+The index toolbar renders a button per listed action (label from the locale key
+`en.publish`, style from `bulk_actions.styles.publish` — see
+[locales.md](locales.md)). On submit, each selected record is checked against
+`publish?` individually — unauthorized rows are skipped, never bulk-bypassed — then
+receives `publish!`. Return `[]` to offer no bulk actions.
+## Dashboard metrics: `permitted_metrics`
+Default `[]`. Names of model scopes (`:all` = whole relation) rendered as count
+tiles by the `metrics Article` dashboard helper:
+```ruby
+def permitted_metrics = %i[all published]
+```
+See [navigation.md](navigation.md) for the dashboard itself.