cafe_car 0.2.1 → 0.3.0

data/skills/cafe_car/references/presenters.md

@@ -0,0 +1,76 @@
+# Presenters — how values render
+
+Source: `app/presenters/cafe_car/presenter.rb` in the gem, plus per-type presenters
+alongside it (`CurrencyPresenter`, `DatePresenter`, `RecordPresenter`,
+`ActiveRecord::RelationPresenter`, `ActiveStorage::AttachmentPresenter`, …).
+
+`present(value)` (aliased `p` in views) wraps anything in a presenter and returns
+an html-safe object. Records render as a linked preview (logo + title); dates,
+currency, rich text, attachments, and collections each render through their type's
+presenter.
+
+## How a presenter is chosen
+
+The value's ancestor chain is walked and the first `<Ancestor>Presenter` constant
+found wins — a host `InvoicePresenter` beats the gem's `RecordPresenter` by
+existing; nothing is registered. Force a type with `as:`:
+
+```ruby
+present(@invoice)                    # InvoicePresenter, else RecordPresenter
+present(record.total, as: :currency) # CurrencyPresenter
+```
+
+Note: constants the gem defines under `CafeCar::` (e.g. `CafeCar::StringPresenter`)
+resolve engine-first — a same-named top-level constant does *not* shadow them.
+Override per model (`ProductPresenter`) or per ancestor the gem doesn't claim.
+
+## Writing one
+
+```ruby
+# app/presenters/invoice_presenter.rb
+class InvoicePresenter < CafeCar::Presenter
+  show :total, as: :currency          # render this attribute through a type
+  show :number, -> { "#%03d" % _1 }   # or through a lambda
+
+  def title = show(:number)           # what links/cards/breadcrumbs call this record
+end
+```
+
+`show` class macros set per-attribute rendering defaults used everywhere the
+attribute appears — tables, show pages, cards.
+
+## The instance API (used inside overridden views)
+
+In view code, `present(@article)` (or the `object` local in `_grid_item`) gives:
+
+```ruby
+p = present(@article)
+p.title                    # policy.title_attribute, rendered
+p.logo(size: :icon)        # policy.logo_attribute as an image
+p.show(:author)            # one attribute's value, presented
+p.attribute(:author)       # labeled Field (label + value)
+p.attributes(:a, :b)       # several labeled fields; no args = all displayable
+p.remaining_attributes     # displayable minus already-shown
+p.associations             # labeled fields for displayable associations
+p.timestamps               # created_at/updated_at etc.
+p.controls                 # the show/edit/delete control links
+p.href                     # canonical path, nil if not routable
+p.object                   # the underlying record (for url helpers etc.)
+```
+
+## Linking to related objects
+
+`show`/`preview` of an associated record is already a link to it. For explicit
+links use the helpers:
+
+```ruby
+href_for(record)          # path to the record in the current namespace
+link(record).show         # LinkBuilder: policy-aware link (disabled when denied)
+link(record).edit
+link(record).destroy      # turbo DELETE with locale-driven confirm
+link(model).index
+link(model.new).new
+```
+
+`link(...)` renders disabled-with-tooltip when the policy denies the action —
+prefer it over hand-written `link_to` so authorization stays visible in the UI.

data/skills/cafe_car/references/turbo.md

@@ -0,0 +1,53 @@
+# Turbo Streams and live sync
+
+Source: `app/views/cafe_car/application/*.turbo_stream.haml` and
+`app/views/application/_head.html.haml` (in the gem).
+
+This is a big reason not to hand-roll admin pages: the defaults carry Turbo 8
+morph behavior you'd otherwise rebuild.
+
+## What ships by default
+
+- Every CafeCar page sets `turbo-refresh-method: morph` and
+  `turbo-refresh-scroll: preserve` (the `_head` partial), so refreshes patch the
+  DOM in place — scroll position, open popovers, and form state survive.
+- Create/update/destroy respond to `turbo_stream` with a page refresh
+  (`turbo_stream.refresh`), which morphs. Update also removes the record's modal
+  if it was edited in one.
+- Every show page subscribes to its record: `turbo_stream_from(object)` is in the
+  default show template.
+
+## Cross-client live sync is a one-line host opt-in
+
+The subscription is only useful if the model broadcasts. Add Rails'
+`broadcasts_refreshes` to the model:
+
+```ruby
+class Invoice < ApplicationRecord
+  broadcasts_refreshes
+end
+```
+
+Now any save/destroy — from another browser, a job, the console — morph-refreshes
+every open show page for that record. Requires a working ActionCable/Solid Cable
+setup in the host, as with any Turbo broadcast.
+
+## Customizing
+
+Override the turbo_stream response per resource like any view
+([views.md](views.md)):
+
+```haml
+-# app/views/admin/products/update.turbo_stream.haml
+= turbo_stream.refresh request_id: nil
+= turbo_stream.append "audit_log", partial: "audit_entry", locals: { product: @product }
+```
+
+Keep the `refresh` line unless you're deliberately replacing morphing with targeted
+streams.
+
+## Don't break it
+
+When writing custom views for a CafeCar resource, keep `turbo_stream_from(object)`
+on detail pages and don't strip the `_head` meta tags — hand-rolled pages that drop
+these are how admins lose live updates.

data/skills/cafe_car/references/views.md

@@ -0,0 +1,96 @@
+# Views and the override system
+
+This is the crux of CafeCar: the gem ships default templates; a host replaces any
+one of them by dropping a same-named file. You delete view files, you don't write
+folders of them.
+
+## The two engine view roots
+
+- `app/views/application/` (in the gem) — **shared partials**: `_table`, `_grid`,
+  `_form`, `_show`, `_search`, `_navigation`, … Resolved through normal controller
+  prefix fallback (every host controller inherits `ApplicationController`).
+- `app/views/cafe_car/application/` (in the gem) — **action templates and
+  turbo_stream responses**: `index.html.haml`, `show.html.haml`, `new`, `edit`,
+  `create/update/destroy.turbo_stream.haml`.
+
+## Precedence (first match wins)
+
+1. `app/views/<controller_path>/…` in the host — one resource
+   (e.g. `app/views/admin/products/_grid_item.html.haml`)
+2. `app/views/application/…` in the host — app-wide partial override
+3. `app/views/cafe_car/application/…` in the host — app-wide action-template override
+4. the gem's defaults
+
+Start by copying the gem's default (`cd "$(bundle show cafe_car)"`) and trimming.
+Most defaults are 1–10 lines — the composition happens in helpers and policies, so
+overrides stay small.
+
+## The key overridable partials
+
+| Partial | Renders |
+|---|---|
+| `_index` | index body: toolbar (search + bulk bar), the current view, pagination |
+| `_table` | the table: `table_for` with select/logo/title/remaining/timestamps/controls columns |
+| `_grid` / `_grid_item` | card grid; `_grid_item` is one card |
+| `_show` | show-page body: remaining attributes + associations |
+| `_form` / `_fields` | the form card; `_fields` is just `f.remaining_fields` |
+| `_field`, `_<type>_field` | one form field (see [forms.md](forms.md)) |
+| `_controls` | the show/edit/delete link cluster on rows and cards |
+| `_search` | the index search box |
+| `_bulk_actions` | the bulk-action button bar (defaults to looping the policy's list) |
+| `_navigation`, `_navigation_links` | the sidebar (see [navigation.md](navigation.md)) |
+| `_index_actions` | index toolbar right side: view toggles, CSV, New button |
+| `_head` | the `<head>`: meta, stylesheets, importmap |
+| `_alerts`, `_errors`, `_empty`, `_submit` | flash messages, form errors, empty state, submit row |
+
+## Worked example: buttons on the grid cards
+
+The gem's whole `_grid_item.html.haml`:
+
+```haml
+= Card title: object.title, image: object.logo(href: object), actions: object.controls
+```
+
+`object` is a presenter. To add a field and a custom button for one resource:
+
+```haml
+-# app/views/admin/products/_grid_item.html.haml
+= Card title: object.title, image: object.logo(href: object), actions: object.controls do |card|
+  = card.Section object.show(:price)
+  = card.Foot do
+    = button_to t(:restock), restock_admin_product_path(object.object), class: ui.Button(:primary).class_name
+```
+
+(`object.object` is the record; a custom member action needs its own route +
+controller action today. The button label goes in the locale.) Drop the same file
+in `app/views/application/` to change every resource's card.
+
+## Worked example: a bespoke index
+
+```haml
+-# app/views/articles/index.html.haml — replaces the whole action template
+= Page :slim, :center do |page|
+  = page.Body do
+    - @articles.each do |article|
+      %article
+        %h2= p article
+        %p= article.summary
+    = paginate @articles
+```
+
+Full control, and you keep the layout, filtering, pagination, and helpers. Prefer
+overriding the smallest partial that's wrong (`_grid_item`, not `index`).
+
+## Turbo_stream templates
+
+Per-resource turbo responses override the same way:
+`app/views/admin/products/update.turbo_stream.haml` replaces the default
+morph-refresh response for that resource. See [turbo.md](turbo.md).
+
+## Design rules (owner-set, hold to them)
+
+- Configuration happens **in views and partials** (plus the policy) — never invent
+  a config DSL or initializer registry.
+- **All copy in locales** — no hardcoded UI strings in templates
+  ([locales.md](locales.md)).
+- **No global CSS** — styles belong to components ([components.md](components.md)).

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cafe_car
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jeff Peterson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -192,17 +192,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
-description: CafeCar is a Rails engine that extends the view layer to render complete
-  index, show, new, and edit interfaces straight from your models, with no boilerplate
-  required. Sensible defaults cover authorization, presenters, filtering, sorting,
-  pagination, and Hotwire-ready forms, and every default can be overridden application-wide
-  or per model. Batteries included for admin panels, internal tools, and rapid prototyping.
+description: 'CafeCar is a composable view extension for Rails: it renders complete
+  index, show, new, and edit interfaces straight from your models, with no DSL and
+  no boilerplate. Every index ships with keyword search, URL-based filtering and sorting,
+  pagination, and one-click CSV export. Authorization runs on Pundit with attribute-level
+  permissions; forms and Turbo Stream (Hotwire) responses render automatically. Every
+  default can be overridden application-wide or per model with ordinary Rails. It
+  makes admin panels, internal tools, and back-office apps on Rails 8 trivial.'
 email:
 - jeff@yak.sh
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude-plugin/marketplace.json"
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -212,18 +215,21 @@ files:
 - app/assets/stylesheets/actiontext.css
 - app/assets/stylesheets/application.css
 - app/assets/stylesheets/cafe_car.css
+- app/assets/stylesheets/cafe_car/chart.css
 - app/assets/stylesheets/cafe_car/code/base16-dark.css
 - app/assets/stylesheets/cafe_car/code/base16-light.css
+- app/assets/stylesheets/cafe_car/dashboard.css
+- app/assets/stylesheets/cafe_car/filters.css
 - app/assets/stylesheets/cafe_car/pagination.css
 - app/assets/stylesheets/cafe_car/themes/cool.css
 - app/assets/stylesheets/cafe_car/themes/cool2.css
 - app/assets/stylesheets/cafe_car/themes/defaults.css
-- app/assets/stylesheets/cafe_car/themes/warm-dark.css
 - app/assets/stylesheets/cafe_car/themes/warm.css
 - app/assets/stylesheets/cafe_car/tooltips.css
 - app/assets/stylesheets/cafe_car/trix.css
 - app/assets/stylesheets/cafe_car/utility.css
 - app/assets/stylesheets/iconoir.css
+- app/assets/stylesheets/tom-select.css
 - app/assets/stylesheets/ui/Alert.css
 - app/assets/stylesheets/ui/Article.css
 - app/assets/stylesheets/ui/Button.css
@@ -250,11 +256,13 @@ files:
 - app/assets/stylesheets/ui/Table.css
 - app/assets/stylesheets/ui/components.css
 - app/controllers/cafe_car/application_controller.rb
+- app/controllers/cafe_car/dashboards_controller.rb
 - app/controllers/cafe_car/examples_controller.rb
 - app/controllers/cafe_car/sessions_controller.rb
 - app/controllers/concerns/cafe_car/authentication.rb
 - app/javascript/application.js
 - app/javascript/cafe_car.js
+- app/javascript/tom-select.complete.min.js
 - app/models/cafe_car/session.rb
 - app/policies/cafe_car/application_policy.rb
 - app/policies/cafe_car/session_policy.rb
@@ -286,20 +294,28 @@ files:
 - app/ui/cafe_car/ui/layout.rb
 - app/ui/cafe_car/ui/page.rb
 - app/views/application/_actions.html.haml
+- app/views/application/_active_filters.html.haml
 - app/views/application/_alerts.html.haml
 - app/views/application/_aside.html.haml
+- app/views/application/_belongs_to_filter.html.haml
 - app/views/application/_body.html.haml
+- app/views/application/_boolean_filter.html.haml
+- app/views/application/_bulk_actions.html.haml
+- app/views/application/_chart.html.haml
 - app/views/application/_controls.html.haml
 - app/views/application/_debug.html.haml
 - app/views/application/_empty.html.haml
+- app/views/application/_enum_filter.html.haml
 - app/views/application/_errors.html.haml
 - app/views/application/_field.html.haml
 - app/views/application/_fields.html.haml
+- app/views/application/_filter.html.haml
 - app/views/application/_filters.html.haml
 - app/views/application/_footer.html.haml
 - app/views/application/_form.html.haml
 - app/views/application/_grid.html.haml
 - app/views/application/_grid_item.html.haml
+- app/views/application/_has_many_filter.html.haml
 - app/views/application/_head.html.haml
 - app/views/application/_index.html.haml
 - app/views/application/_index_actions.html.haml
@@ -308,10 +324,13 @@ files:
 - app/views/application/_nested_field.html.haml
 - app/views/application/_notes.html.haml
 - app/views/application/_popup.html.haml
-- app/views/application/_search.html.haml
+- app/views/application/_range_filter.html.haml
+- app/views/application/_scope_filter.html.haml
 - app/views/application/_show.html.haml
+- app/views/application/_string_filter.html.haml
 - app/views/application/_submit.html.haml
 - app/views/application/_table.html.haml
+- app/views/application/_text_filter.html.haml
 - app/views/cafe_car/application/create.turbo_stream.haml
 - app/views/cafe_car/application/destroy.turbo_stream.haml
 - app/views/cafe_car/application/edit.html.haml
@@ -321,6 +340,8 @@ files:
 - app/views/cafe_car/application/new.turbo_stream.haml
 - app/views/cafe_car/application/show.html.haml
 - app/views/cafe_car/application/update.turbo_stream.haml
+- app/views/cafe_car/dashboard/_chart.html.haml
+- app/views/cafe_car/dashboard/_metric.html.haml
 - app/views/cafe_car/examples/_example.html.haml
 - app/views/cafe_car/examples/_index.html.haml
 - app/views/cafe_car/examples/_index_actions.html.haml
@@ -362,8 +383,8 @@ files:
 - lib/cafe_car/active_record.rb
 - lib/cafe_car/application_responder.rb
 - lib/cafe_car/attributes.rb
-- lib/cafe_car/auto_resolver.rb
 - lib/cafe_car/caching.rb
+- lib/cafe_car/chart_builder.rb
 - lib/cafe_car/component.rb
 - lib/cafe_car/context.rb
 - lib/cafe_car/controller.rb
@@ -388,11 +409,19 @@ files:
 - lib/cafe_car/href_builder.rb
 - lib/cafe_car/informable.rb
 - lib/cafe_car/input_builder.rb
-- lib/cafe_car/inputs/association_builder.rb
+- lib/cafe_car/inputs/association_input.rb
 - lib/cafe_car/inputs/base_input.rb
-- lib/cafe_car/inputs/belongs_to_builder.rb
+- lib/cafe_car/inputs/boolean_input.rb
+- lib/cafe_car/inputs/date_input.rb
+- lib/cafe_car/inputs/datetime_input.rb
+- lib/cafe_car/inputs/file_input.rb
+- lib/cafe_car/inputs/nested_input.rb
+- lib/cafe_car/inputs/number_input.rb
 - lib/cafe_car/inputs/password_input.rb
+- lib/cafe_car/inputs/rich_text_input.rb
+- lib/cafe_car/inputs/select_input.rb
 - lib/cafe_car/inputs/string_input.rb
+- lib/cafe_car/inputs/text_area_input.rb
 - lib/cafe_car/link_builder.rb
 - lib/cafe_car/model.rb
 - lib/cafe_car/model_info.rb
@@ -419,6 +448,8 @@ files:
 - lib/cafe_car/ui.rb
 - lib/cafe_car/version.rb
 - lib/cafe_car/visitors.rb
+- lib/generators/cafe_car/agents/USAGE
+- lib/generators/cafe_car/agents/agents_generator.rb
 - lib/generators/cafe_car/controller/USAGE
 - lib/generators/cafe_car/controller/controller_generator.rb
 - lib/generators/cafe_car/controller/templates/controller.rb.tt
@@ -439,8 +470,19 @@ files:
 - lib/generators/cafe_car/sessions/sessions_generator.rb
 - lib/generators/cafe_car/sessions/templates/create_sessions.rb.tt
 - lib/tasks/cafe_car_tasks.rake
-- lib/tasks/holdco_tasks.rake
-- lib/tasks/templates/tasks_header.md
+- lib/tasks/demo.rake
+- llms.txt
+- skills/cafe_car/SKILL.md
+- skills/cafe_car/references/components.md
+- skills/cafe_car/references/controllers.md
+- skills/cafe_car/references/filtering.md
+- skills/cafe_car/references/forms.md
+- skills/cafe_car/references/locales.md
+- skills/cafe_car/references/navigation.md
+- skills/cafe_car/references/policies.md
+- skills/cafe_car/references/presenters.md
+- skills/cafe_car/references/turbo.md
+- skills/cafe_car/references/views.md
 homepage: https://craft-concept.github.io/cafe_car
 licenses:
 - MIT
@@ -468,6 +510,7 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Auto-generate CRUD admin UI for your Rails models, with sensible overridable
-  defaults.
+summary: A composable view extension for Rails — render index, show, new, and edit
+  straight from your models, with keyword search, filtering, CSV export, and Pundit
+  authorization, then override any default with ordinary Rails.
 test_files: []

data/app/assets/stylesheets/cafe_car/themes/warm-dark.css

@@ -1,29 +0,0 @@
-@import url(defaults.css);
-
-:root {
-  --blue: rgb(35, 175, 208);
-
-  --input: #1e1e1d;
-  --background: #191918;
-  --button: #333;
-
-  --color: #e7e3dc;
-  --dim: #6c7a91;
-
-  --card: #222221;
-  --border: #2A2A28;
-  --hover: rgb(42, 42, 40);
-  --shadow: rgba(0, 0, 0, 0.2);
-}
-
-body {
-  scrollbar-color: rgb(73, 72, 70) rgb(25, 25, 24);
-}
-
-.Card, .Table {
-  border: 0;
-}
-
-.Table_Head {
-  background-color: var(--card);
-}

data/app/views/application/_search.html.haml

@@ -1,6 +0,0 @@
-= form_with url: "", method: :get, class: "search" do |f|
-  - dot_params.each do |key, value|
-    = hidden_field_tag key, value
-  = hidden_field_tag :sort, params[:sort] if params[:sort].present?
-  = f.search_field :q, value: search_term, placeholder: t(:search, scope: :helpers, default: "Search")
-  = f.button "Search", name: nil

data/lib/cafe_car/auto_resolver.rb

@@ -1,49 +0,0 @@
-module CafeCar
-  module AutoResolver
-    def auto_resolve!(mod)
-      mod.instance_eval <<~RUBY, __FILE__, __LINE__
-        def const_missing(name)
-          super
-        rescue NameError
-          CafeCar.define(self, name) or raise
-        end
-      RUBY
-    end
-
-    def define(mod, name)
-      case name.to_s
-      when /^\w+Controller$/
-        TOPLEVEL_BINDING.eval <<~RUBY, __FILE__, __LINE__
-          class #{mod.name}::#{name} < CafeCar[:ApplicationController]
-            include CafeCar::Controller
-            cafe_car
-            self
-          end
-        RUBY
-      when /^\w+Policy$/
-        TOPLEVEL_BINDING.eval <<~RUBY, __FILE__, __LINE__
-          class #{mod.name}::#{name} < CafeCar[:ApplicationPolicy]
-            def admin? = Rails.env.development?
-
-            def index?   = admin?
-            def show?    = admin?
-            def create?  = admin?
-            def update?  = admin?
-            def destroy? = admin?
-
-            def permitted_attributes
-              model.info.fields.names.then do |names|
-                [*model.primary_key].reverse.map(&:to_sym) & names | names
-              end
-            end
-
-            class Scope < Scope
-              def resolve = scope.all
-            end
-            self
-          end
-        RUBY
-      end
-    end
-  end
-end

data/lib/cafe_car/inputs/association_builder.rb

@@ -1,6 +0,0 @@
-module CafeCar
-  module Inputs
-    class AssociationBuilder < InputBuilder
-    end
-  end
-end

data/lib/cafe_car/inputs/belongs_to_builder.rb

@@ -1,6 +0,0 @@
-module CafeCar
-  module Inputs
-    class BelongsToBuilder < AssociationBuilder
-    end
-  end
-end