diff --git a/.okf/architecture/flat-namespace.md b/.okf/architecture/flat-namespace.md new file mode 100644 index 0000000..2649a33 --- /dev/null +++ b/.okf/architecture/flat-namespace.md @@ -0,0 +1,34 @@ +--- +type: Decision +title: Flat `ruby_ui_scaffold` namespace for the entry generator +description: The entry generator forces namespace "ruby_ui_scaffold" because the auto-derived nested form shadows the sub-generator lookups and causes silent recursion. +tags: [generators, rails-internals] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: entry + title: RubyUiScaffoldGenerator + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb +--- + +# Decision + +`RubyUiScaffoldGenerator` declares `namespace "ruby_ui_scaffold"` explicitly.[^entry] + +# Why + +Rails would auto-derive `ruby_ui_scaffold:ruby_ui_scaffold` from the file path. +`find_by_namespace` tries candidate names in order, and that nested name would +match first when the hooks look up `ruby_ui_scaffold:scaffold` and +`ruby_ui_scaffold:scaffold_controller` — the entry generator would invoke +itself instead of the sub-generator, recursing **silently**.[^entry] + +The same reason explains `as: :scaffold_controller` on the controller hook in the +[Generator chain](/architecture/generator-chain.md): it steers lookup to the +`name:context` form. + +# Consequences + +Do not remove or rename the `namespace` call. A regression shows up as the +scaffold never reaching the controller/views, not as an error. diff --git a/.okf/architecture/generator-chain.md b/.okf/architecture/generator-chain.md new file mode 100644 index 0000000..28358c0 --- /dev/null +++ b/.okf/architecture/generator-chain.md @@ -0,0 +1,58 @@ +--- +type: Component +title: Generator chain +description: How one `rails g ruby_ui_scaffold` fans out through three cooperating generators that subclass and selectively redirect Rails' own scaffold pipeline. +tags: [generators, rails-internals] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: entry + title: RubyUiScaffoldGenerator + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb + - id: controller + title: ScaffoldControllerGenerator + resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb + - id: views + title: ScaffoldGenerator (views) + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb +--- + +# Overview + +The core trick is **hook redirection**: rather than reimplementing scaffold, the +gem subclasses Rails' generators and swaps exactly two hooks. + +``` +rails g ruby_ui_scaffold User name:string + └─ RubyUiScaffoldGenerator (< Rails ScaffoldGenerator) namespace "ruby_ui_scaffold" + ├─ :orm hook → model, migration, model test, fixtures (inherited; no-op under --skip-model) + ├─ resource route, helper, tests (inherited) + └─ :scaffold_controller hook, as: :scaffold_controller + └─ ScaffoldControllerGenerator (< Rails ScaffoldControllerGenerator) + ├─ controller.rb.tt | controller_data_table.rb.tt + └─ :template_engine hook, as: :scaffold, default "ruby_ui_scaffold" + └─ ScaffoldGenerator (< NamedBase) → Phlex views + components +``` + +1. The entry generator removes the inherited `scaffold_controller` hook and + re-adds it with `as: :scaffold_controller` so lookup resolves + `ruby_ui_scaffold:scaffold_controller`.[^entry] Details: + [Entry generator](/generators/entry-generator.md). +2. The controller generator does the same for `template_engine` + (`as: :scaffold`), so `ruby_ui_scaffold:scaffold` runs instead of + `erb:scaffold`; the hook is skipped under `--api`.[^controller] Details: + [Controller generator](/generators/controller-generator.md). +3. The views generator is the "template engine": preflight, Phlex views, + helper injection into `Components::Base`, then on-demand component + install.[^views] Details: [Views generator](/generators/views-generator.md). + +# What makes it fragile + +Three non-obvious constraints hold the chain together, each its own decision: + +- the entry generator's namespace must be flat — [Flat namespace](/architecture/flat-namespace.md); +- the Railtie must not require generator classes, while the entry file must + eagerly require its sub-generators — [Lazy generator loading](/architecture/lazy-generator-loading.md); +- options reach sub-generators by re-parsing the original CLI args — + [Option propagation](/architecture/option-propagation.md). diff --git a/.okf/architecture/index.md b/.okf/architecture/index.md new file mode 100644 index 0000000..0ca6cac --- /dev/null +++ b/.okf/architecture/index.md @@ -0,0 +1,6 @@ +# Architecture + +* [Generator chain](generator-chain.md) - How one `rails g ruby_ui_scaffold` fans out through three cooperating generators via hook redirection. +* [Flat `ruby_ui_scaffold` namespace](flat-namespace.md) - Why the entry generator forces a flat namespace. +* [Lazy generator loading](lazy-generator-loading.md) - Railtie sets defaults only; entry file eager-requires sub-generators. +* [Option propagation](option-propagation.md) - Flags reach sub-generators by re-parsing raw CLI args. diff --git a/.okf/architecture/lazy-generator-loading.md b/.okf/architecture/lazy-generator-loading.md new file mode 100644 index 0000000..86d765a --- /dev/null +++ b/.okf/architecture/lazy-generator-loading.md @@ -0,0 +1,58 @@ +--- +type: Decision +title: Lazy generator loading — Railtie sets defaults only, entry file eager-requires sub-generators +description: The Railtie must never require generator classes (it would freeze Rails' :orm hook to false), while the entry generator must require its sub-generators (Rails loads only the first matching file). +tags: [rails-internals, generators, regression] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: railtie + title: Railtie + resource: ../../lib/ruby_ui_scaffold/railtie.rb + - id: entry + title: RubyUiScaffoldGenerator (require block) + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb + - id: railtie-test + title: test/railtie_test.rb + resource: ../../test/railtie_test.rb + - id: changelog + title: CHANGELOG 0.1.1 — Fixed + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/CHANGELOG.md +--- + +# Decision + +Two rules that look contradictory but are both load-bearing: + +1. **`Railtie#generators` only sets an option default** — + `Rails::Generators.options[:ruby_ui_scaffold][:template_engine] = "ruby_ui_scaffold"` — + and requires **no** generator class.[^railtie] +2. **The entry generator file eagerly requires** the controller and views + sub-generators.[^entry] + +# Why rule 1 + +Rails runs every railtie's `generators` block *before* +`Rails::Generators.configure!`. `hook_for` / `class_option` freeze defaults at +class-definition time, so requiring our generators there loads Rails' +`ScaffoldGenerator → ModelGenerator` early and freezes `:orm` as `false`. Result: +`rails g ruby_ui_scaffold` — and even plain `rails g model` in any app with the +gem bundled — silently generates no model or migration.[^railtie] This shipped +in 0.1.0 and was fixed in 0.1.1.[^changelog] + +# Why rule 2 + +Rails' hook lookup requires only the **first** existing candidate file. For the +views hook that is the entry file itself, so without the eager require +`scaffold/scaffold_generator.rb` never loads and Rails prints +`ruby_ui_scaffold [not found]`.[^entry] This is safe because the entry file is +itself loaded lazily, after `configure!`. + +# Guard + +`test/railtie_test.rb` boots a minimal app **in a subprocess** through the real +`load_generators` path and asserts `ModelGenerator`'s `:orm` default and the +resolved scaffold class.[^railtie-test] It cannot run in-process because +`test_helper` already loads every generator — see +[Test harness](/testing/test-harness.md). diff --git a/.okf/architecture/option-propagation.md b/.okf/architecture/option-propagation.md new file mode 100644 index 0000000..dfab600 --- /dev/null +++ b/.okf/architecture/option-propagation.md @@ -0,0 +1,52 @@ +--- +type: Pitfall +title: Option propagation down the hook chain +description: Sub-generators receive options by Thor re-parsing the original init args, so flags must be declared where they are read and mutations of `options` never propagate. +tags: [generators, rails-internals, flags] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T15:00:00Z +sources: + - id: entry + title: RubyUiScaffoldGenerator#initialize + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb + - id: controller + title: ScaffoldControllerGenerator class_options + resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb + - id: views + title: ScaffoldGenerator class_options + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb +--- + +# Overview + +When a hook fires, Thor invokes the sub-generator by **re-parsing the original +init options** stored in `@_initializer` (`Thor::Invocation#_parse_initialization_options`). +Two consequences: + +- A flag only has a value in a generator that declares it as a `class_option`. +- Mutating `options` after parse in a parent never reaches the children. That is + why `--skip-model` injects `--force` into the **raw** args in `initialize` + ([Skip-model](/generators/skip-model.md)).[^entry] + +# Current declarations + +| Flag | Entry | Controller | Views | Read by | +|---|---|---|---|---| +| `--datatable` | yes | yes | yes | controller + views | +| `--phlex_layout` | yes | yes | yes | controller (`layout false`) + views | +| `--literal` | yes | **no** | yes | views only | +| `--skip_install` | yes | yes (pass-through only) | yes | views | +| `--skip_model` | yes | no | no | entry only | + +Sources: [^entry] [^controller] [^views] + +# Rule + +**Declare a flag on every generator that reads it, and on the entry generator so +the CLI accepts it.** `--literal` is not declared on the controller generator and +still works, because the views generator re-parses the raw args itself. +Adding it to the controller would be harmless and keep +`rails g ruby_ui_scaffold:scaffold_controller --help` honest. + +See [Generator flags](/generators/flags.md) for what each flag does. diff --git a/.okf/generators/auto-install.md b/.okf/generators/auto-install.md new file mode 100644 index 0000000..66bb477 --- /dev/null +++ b/.okf/generators/auto-install.md @@ -0,0 +1,35 @@ +--- +type: Decision +title: Scaffold auto-runs the installer in a subprocess +description: When phlex or ruby_ui isn't detected, the views generator shells out to `bin/rails g ruby_ui_scaffold:install` instead of invoking it in-process, and degrades to a warning when it can't. +tags: [install, generators] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: views + title: ScaffoldGenerator#ensure_phlex_and_ruby_ui_installed / run_install! + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb +--- + +# Decision + +`preflight_checks` in the [Views generator](/generators/views-generator.md) +runs the idempotent [Install generator](/generators/install-generator.md) via +`system("bin/rails", "generate", "ruby_ui_scaffold:install")`.[^views] + +# Why a subprocess + +The installer calls `exit(1)` on unrecoverable errors. In-process `invoke` +would let that tear down the whole scaffold run; a subprocess contains it, and +the scaffold continues writing files with a yellow warning.[^views] + +# When it only warns (never aborts) + +- `--skip-install` is passed, or +- there is no app `bin/rails` to drive it — notably the generator test harness, + which writes into `test/tmp/`. + +The same gate (`--skip-install` / no `bin/rails`) applies to on-demand +component install ([Component resolution](/runtime/component-resolution.md)), +which is why generator tests never shell out.[^views] diff --git a/.okf/generators/controller-generator.md b/.okf/generators/controller-generator.md new file mode 100644 index 0000000..e2fde0a --- /dev/null +++ b/.okf/generators/controller-generator.md @@ -0,0 +1,40 @@ +--- +type: Component +title: Controller generator (ScaffoldControllerGenerator) +description: Subclass of Rails' scaffold_controller that renders Phlex view classes instead of ERB and redirects the template_engine hook to the gem's views generator. +resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb +tags: [generators, datatable] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: controller + title: scaffold_controller_generator.rb + resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb + - id: dt-template + title: controller_data_table.rb.tt + resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/templates/controller_data_table.rb.tt +--- + +# Overview + +Overrides `create_controller_files` to pick `controller.rb.tt` or +`controller_data_table.rb.tt` by `--datatable`, and re-hooks +`template_engine` with `as: :scaffold, default: "ruby_ui_scaffold"` (skipped +when `--api`).[^controller] It requires the views generator directly so a +standalone `rails g ruby_ui_scaffold:scaffold_controller` also resolves the +hook — the same first-match lookup issue described in +[Lazy generator loading](/architecture/lazy-generator-loading.md). + +# Generated controller shape + +- Actions render `::Views::::Index.new(...)` etc. — fully qualified to + avoid clashing with ERB siblings ([View conventions](/views/view-conventions.md)). +- `--phlex_layout` emits `layout false`. +- Failed create/update render the New/Edit view with + `ActionDispatch::Constants::UNPROCESSABLE_CONTENT`, and `set_*` uses + `params.expect` — both Rails 8-era APIs inherited from the Rails template.[^dt-template] + +The DataTable variant's query building is described in +[Index variants](/views/index-variants.md). Which columns participate comes from +[Attribute helpers](/runtime/attribute-helpers.md). diff --git a/.okf/generators/entry-generator.md b/.okf/generators/entry-generator.md new file mode 100644 index 0000000..bd4462d --- /dev/null +++ b/.okf/generators/entry-generator.md @@ -0,0 +1,30 @@ +--- +type: Component +title: Entry generator (RubyUiScaffoldGenerator) +description: The `rails g ruby_ui_scaffold` entry point — subclasses Rails' ScaffoldGenerator, forces a flat namespace, redirects the controller hook and owns the CLI flags. +resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb +tags: [generators, flags] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: entry + title: ruby_ui_scaffold_generator.rb + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb +--- + +# Responsibilities + +- Inherits model/migration/route/test/helper generation from + `Rails::Generators::ScaffoldGenerator`.[^entry] +- `namespace "ruby_ui_scaffold"` — see [Flat namespace](/architecture/flat-namespace.md). +- `remove_hook_for :scaffold_controller` + `hook_for :scaffold_controller, as: + :scaffold_controller, required: true` — hands off to the + [Controller generator](/generators/controller-generator.md).[^entry] +- Declares every user-facing flag ([Generator flags](/generators/flags.md)). +- Eager-requires its sub-generators — see + [Lazy generator loading](/architecture/lazy-generator-loading.md). +- Implements `--skip-model` by overriding the Thor-generated + `_invoke_from_option_orm` — see [Skip-model](/generators/skip-model.md). + +Its position in the pipeline is drawn in [Generator chain](/architecture/generator-chain.md). diff --git a/.okf/generators/flags.md b/.okf/generators/flags.md new file mode 100644 index 0000000..14e3769 --- /dev/null +++ b/.okf/generators/flags.md @@ -0,0 +1,29 @@ +--- +type: Reference +title: Generator flags +description: What each `rails g ruby_ui_scaffold` flag changes in the generated output and where it is implemented. +tags: [flags, datatable, generators] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: readme + title: README — Optional flags + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md + - id: entry + title: class_option declarations + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb +--- + +# Flags + +| Flag | Effect | Details | +|---|---|---| +| `--datatable` | Index uses ruby_ui `DataTable` (search, per-page, sortable headers, pagination); controller gains `SORTABLE_COLUMNS` + param parsing + scope building | [Index variants](/views/index-variants.md) | +| `--literal` | Views use Literal `prop` macros instead of `def initialize`; injects `extend Literal::Properties` into `Components::Base` | [View conventions](/views/view-conventions.md) | +| `--phlex_layout=Class` | Each `view_template` wraps its body in `render(Class) do ... end`; controller gets `layout false` | [View conventions](/views/view-conventions.md) | +| `--skip-install` | Never auto-run the installer or component install — only warn | [Auto-install](/generators/auto-install.md) | +| `--skip-model` | Skip the `:orm` hook; implies `--force` | [Skip-model](/generators/skip-model.md) | + +Declared on the entry generator;[^entry] the README is the authoritative user-facing spec for these;[^readme] how they +travel between generators is in [Option propagation](/architecture/option-propagation.md). diff --git a/.okf/generators/index.md b/.okf/generators/index.md new file mode 100644 index 0000000..2828e14 --- /dev/null +++ b/.okf/generators/index.md @@ -0,0 +1,10 @@ +# Generators + +* [Entry generator](entry-generator.md) - `rails g ruby_ui_scaffold` entry point. +* [Controller generator](controller-generator.md) - Phlex-rendering controller and template_engine redirect. +* [Views generator](views-generator.md) - The template engine: views, helper injection, component install. +* [Install generator](install-generator.md) - Idempotent one-shot installer. +* [Generator flags](flags.md) - What each flag changes. +* [Skip-model](skip-model.md) - Re-runs that regenerate controller/views only, implying --force. +* [Auto-install](auto-install.md) - Scaffold runs the installer in a subprocess, or warns. +* [ruby_ui gem ownership](ruby-ui-gem-ownership.md) - ruby_ui belongs to the host Gemfile; installer adds it on demand. diff --git a/.okf/generators/install-generator.md b/.okf/generators/install-generator.md new file mode 100644 index 0000000..8826d09 --- /dev/null +++ b/.okf/generators/install-generator.md @@ -0,0 +1,41 @@ +--- +type: Component +title: Install generator +description: Idempotent one-shot installer — ensures the ruby_ui gem, runs phlex:install and ruby_ui:install, installs the BASE component set and adds Tailwind @source directives. +resource: ../../lib/generators/ruby_ui_scaffold/install/install_generator.rb +tags: [install, ruby_ui, phlex, generators] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: install + title: install_generator.rb + resource: ../../lib/generators/ruby_ui_scaffold/install/install_generator.rb +--- + +# Steps + +1. `check_phlex_rails_gem` — abort with instructions if `phlex-rails` isn't bundled. +2. `ensure_ruby_ui_gem` — if `ruby_ui` can't be required, add + `gem "ruby_ui", "~> 1.6", require: false` to the Gemfile (unless an entry + exists) and `bundle install` — see [ruby_ui gem ownership](/generators/ruby-ui-gem-ownership.md). +3. `install_phlex` / `install_ruby_ui` — skipped when already present. +4. `install_base_components` — `ComponentResolver::BASE` minus what's present + ([Component resolution](/runtime/component-resolution.md)). +5. `inject_tailwind_sources` — adds `@source "../../views/**/*.rb"` and + `../../components/**/*.rb` to `app/assets/tailwind/application.css`.[^install] + +# Non-obvious choices + +- **Shells out via `run_rails_generator!`, not Thor's `generate`.** Thor's + `abort_on_failure` doesn't reliably propagate exit codes from the inner Rails + command (e.g. Bundler bootstrap errors), so one bad step would cascade into + dozens of identical failures. The helper checks `system`'s result and + `exit(1)`s.[^install] +- **Subprocesses see a gem this process never loaded.** After step 2 edits the + Gemfile, each later `bin/rails generate` boots fresh with the new bundle — + which is why the auto-add works even when the installer itself runs as a + subprocess of the scaffold.[^install] +- **Tailwind v4 doesn't scan `.rb`** by default, so classes used only in Phlex + views would be purged and render with no effect.[^install] +- Deliberately does **not** run `ruby_ui:component:all`. diff --git a/.okf/generators/ruby-ui-gem-ownership.md b/.okf/generators/ruby-ui-gem-ownership.md new file mode 100644 index 0000000..11295d6 --- /dev/null +++ b/.okf/generators/ruby-ui-gem-ownership.md @@ -0,0 +1,37 @@ +--- +type: Decision +title: ruby_ui is owned by the host app's Gemfile +description: ruby_ui is not a gemspec dependency; the installer adds it from RubyGems (~> 1.6, require false) when missing instead of aborting, while phlex-rails stays a declared dependency. +tags: [install, ruby_ui, compatibility] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: install + title: InstallGenerator#ensure_ruby_ui_gem + resource: ../../lib/generators/ruby_ui_scaffold/install/install_generator.rb + - id: changelog + title: CHANGELOG 0.1.1 — Changed + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/CHANGELOG.md +--- + +# Decision + +`ruby_ui` is left to the host app's Gemfile so the app controls its version and +group, as ruby_ui's own docs recommend. When it isn't loadable, the installer +writes `gem "ruby_ui", "~> 1.6", require: false` and runs `bundle install` +rather than aborting.[^install] + +# Details + +- `~> 1.6`: 1.6 is the oldest ruby_ui release the generated views and component + set were verified against.[^install] Since 0.1.1 it comes from RubyGems rather + than tracking GitHub `main`; existing GitHub entries in a Gemfile are detected + (regex on `gem "ruby_ui"`) and left alone.[^changelog] +- `require: false` means the gem may not be loaded yet, so + `ruby_ui_loadable?` tries `require "ruby_ui"` before concluding it's absent.[^install] +- Asymmetry on purpose: `phlex-rails` is the gem's **own** runtime dependency, so + the installer aborts with instructions instead of editing the Gemfile — + auto-editing our own dependency would be odd. + +Part of the [Install generator](/generators/install-generator.md). diff --git a/.okf/generators/skip-model.md b/.okf/generators/skip-model.md new file mode 100644 index 0000000..c6c4dd9 --- /dev/null +++ b/.okf/generators/skip-model.md @@ -0,0 +1,34 @@ +--- +type: Decision +title: --skip-model re-runs regenerate controller and views only, implying --force +description: --skip-model no-ops the inherited :orm hook and injects --force into the raw CLI args, so a re-run overwrites controller/views without touching the user's model. +tags: [generators, flags, rails-internals] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T15:00:00Z +sources: + - id: entry + title: RubyUiScaffoldGenerator#initialize / _invoke_from_option_orm + resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb + - id: readme + title: README — --skip-model + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md +--- + +# Mental model + +**Model = your code (never touched); controller/views = generated (overwritten).** +Use it to refresh views after a template change or to switch to +`--datatable` without a duplicate migration.[^readme] + +# Mechanism + +- Overrides the Thor-generated `_invoke_from_option_orm` to return early. This + skips model, migration, model test and fixtures while leaving `options[:orm]` + intact, so ORM helpers and controller-hook propagation still work.[^entry] +- Implies `--force`, because a re-run otherwise aborts on the controller's + class-collision check. It is injected into the **raw** init args in + `initialize` (array or hash form), not by mutating `options` afterwards — + sub-generators re-parse the raw args and would never see a post-parse + mutation ([Option propagation](/architecture/option-propagation.md)).[^entry] + diff --git a/.okf/generators/views-generator.md b/.okf/generators/views-generator.md new file mode 100644 index 0000000..2e555e3 --- /dev/null +++ b/.okf/generators/views-generator.md @@ -0,0 +1,39 @@ +--- +type: Component +title: Views generator (ScaffoldGenerator — the template engine) +description: Emits the Phlex view classes, auto-installs phlex/ruby_ui when missing, injects required helpers into Components::Base and installs the ruby_ui components the scaffold uses. +resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb +tags: [generators, phlex, ruby_ui, install] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: views + title: scaffold_generator.rb + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb +--- + +# Steps, in order + +| Thor action | What it does | +|---|---| +| `preflight_checks` | If `app/views/base.rb` (phlex) or `RubyUI` in `app/components/base.rb` is missing, shell out to `ruby_ui_scaffold:install`; else warn — see [Auto-install](/generators/auto-install.md) | +| `create_view_files` | `index` (Table or DataTable variant), `show`, `new`, `edit`, `form` under `app/views//` | +| `inject_scaffold_helpers_into_components_base` | Adds missing `FormWith`, `LinkTo`, `ButtonTo`, `Request` helpers, `register_output_helper :lucide_icon`, and `extend Literal::Properties` under `--literal` | +| `install_required_components` | `ruby_ui:component NAME` for each missing component — see [Component resolution](/runtime/component-resolution.md) | + +All actions are no-ops on `behavior == :revoke` (`rails destroy`).[^views] + +# Why the helper injection exists + +`phlex:install` / `ruby_ui:install` create `Components::Base` with only +`Routes` + `RubyUI`. The scaffold's views additionally call `form_with`, +`link_to`, `button_to`, `request` (the form's Back link uses the referer) and +`lucide_icon`; without the injection they raise at render time. Each line is +guarded by a `contents.include?` check, so re-runs are idempotent.[^views] + +# Form inputs + +`form.rb.tt` calls `ruby_ui_input_for(attribute, indent:)`, which delegates to +[Field type mapper](/runtime/field-type-mapper.md) and re-indents multi-line +snippets to the template's column. diff --git a/.okf/index.md b/.okf/index.md new file mode 100644 index 0000000..aec79a3 --- /dev/null +++ b/.okf/index.md @@ -0,0 +1,19 @@ +--- +okf_version: "0.2" +--- + +# ruby_ui_scaffold knowledge bundle + +Architecture, decisions and pitfalls of the `ruby_ui_scaffold` gem. The README +remains the user-facing spec of generated output; this bundle records the *why*. + +* [ruby_ui_scaffold](overview.md) - What the gem is, its entry points, dependencies and where truth lives. + +# Areas + +* [Architecture](architecture/) - The generator chain and the Rails-internals constraints holding it together. +* [Generators](generators/) - Entry, controller, views and install generators, flags and their decisions. +* [Runtime library](runtime/) - Field mapping, attribute rules, component resolution and load-order decisions. +* [Seeding](seeding/) - The `ruby_ui_scaffold:seed` command and its value inference. +* [Views](views/) - Conventions and index variants of the generated Phlex views. +* [Testing](testing/) - Test harness and CI matrix. diff --git a/.okf/log.md b/.okf/log.md new file mode 100644 index 0000000..495f480 --- /dev/null +++ b/.okf/log.md @@ -0,0 +1,6 @@ +# Update Log + +## 2026-11-13 +* **Update**: CLAUDE.md corrected to match the code on `--literal` declarations and `--skip-model`'s raw-args `--force` injection; divergence notes removed from [Option propagation](/architecture/option-propagation.md) and [Skip-model](/generators/skip-model.md). +* **Creation**: initial bundle derived from the gem source at v0.1.1 — architecture (generator chain, namespace, lazy loading, option propagation), generators, runtime library, seeding, views and testing. See [overview](/overview.md). +* **Note**: two places where CLAUDE.md and the code disagree are recorded in [Option propagation](/architecture/option-propagation.md) (`--literal` isn't declared on the controller generator) and [Skip-model](/generators/skip-model.md) (`--force` is injected into raw args, not merged into `options`). diff --git a/.okf/overview.md b/.okf/overview.md new file mode 100644 index 0000000..11db53c --- /dev/null +++ b/.okf/overview.md @@ -0,0 +1,55 @@ +--- +type: Project +title: ruby_ui_scaffold +description: Rails plugin gem providing a drop-in replacement for `rails g scaffold` that emits Phlex views wired to ruby_ui components, plus a Faker-based seed command. +resource: https://github.com/jacksonpires/ruby_ui_scaffold +tags: [phlex, ruby_ui, compatibility] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: readme + title: README.md (authoritative user-facing spec) + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md + - id: gemspec + title: ruby_ui_scaffold.gemspec + resource: ../ruby_ui_scaffold.gemspec + - id: changelog + title: CHANGELOG.md + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/CHANGELOG.md +--- + +# Overview + +`ruby_ui_scaffold` gives a Rails app two entry points: + +| Entry point | Kind | Concept | +|---|---|---| +| `rails g ruby_ui_scaffold MODEL field:type ...` | generator chain | [Generator chain](/architecture/generator-chain.md) | +| `rails g ruby_ui_scaffold:install` | one-shot installer | [Install generator](/generators/install-generator.md) | +| `rails ruby_ui_scaffold:seed MODEL` | Rails command (not a generator) | [Seed command](/seeding/seed-command.md) | + +The scaffold inherits the whole Rails scaffold pipeline (model, migration, route, +tests, helper) and replaces only the controller and view layer with Phlex +classes under `Views::`.[^readme] The repo is the gem source, not a host app: +there is no `bin/rails`, and behavior is exercised through Rails' generator +test harness — see [Test harness](/testing/test-harness.md). + +# Dependencies + +Runtime dependencies are `railties >= 7.1`, `phlex-rails >= 2.0`, `literal`, +`faker` and `lucide-rails`; Ruby `>= 3.2`.[^gemspec] `ruby_ui` is deliberately +**not** a gemspec dependency — the host app owns it, and the installer adds it to +the Gemfile on demand ([decision](/generators/ruby-ui-gem-ownership.md)). The +top-level require pulls the transitive Railties in on purpose +([decision](/runtime/transitive-railtie-requires.md)). + +Ruby 3.2 is the floor because Phlex 2.x already needs it; 0.1.1 raised it from +3.1, which could not actually install.[^changelog] The supported Ruby × Rails +matrix is enforced by CI ([Test harness](/testing/test-harness.md)). + +# Where truth lives + +- Generated-output spec (type → component table, seed heuristics, flags): README.[^readme] +- Release history: CHANGELOG (Keep a Changelog, SemVer, pre-1.0).[^changelog] +- *Why* things are shaped the way they are: this bundle. diff --git a/.okf/runtime/attribute-helpers.md b/.okf/runtime/attribute-helpers.md new file mode 100644 index 0000000..66db480 --- /dev/null +++ b/.okf/runtime/attribute-helpers.md @@ -0,0 +1,27 @@ +--- +type: Component +title: Attribute helpers +description: Shared mixin deciding which scaffold attributes are sortable, searchable, and eager-loadable belongs_to references. +resource: ../../lib/ruby_ui_scaffold/attribute_helpers.rb +tags: [datatable, generators] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: helpers + title: attribute_helpers.rb + resource: ../../lib/ruby_ui_scaffold/attribute_helpers.rb +--- + +# Rules + +| Helper | Includes | Excludes | Used for | +|---|---|---|---| +| `sortable_columns` | everything else | text, rich_text, json/jsonb, binary, attachments, password_digest | `SORTABLE_COLUMNS` allowlist, sortable headers | +| `searchable_columns` | `:string` only | password_digest | `LOWER(col) LIKE :q` search; search box only rendered if non-empty | +| `reference_associations` | non-polymorphic `references` | polymorphic | `scope.includes(...)` and friendly labels in index/show | + +Mixed into both the [Controller generator](/generators/controller-generator.md) +and the [Views generator](/generators/views-generator.md) so controller and view +agree on the same column sets.[^helpers] The controller-side query is described +in [Index variants](/views/index-variants.md). diff --git a/.okf/runtime/component-resolution.md b/.okf/runtime/component-resolution.md new file mode 100644 index 0000000..a1bfd2a --- /dev/null +++ b/.okf/runtime/component-resolution.md @@ -0,0 +1,47 @@ +--- +type: Decision +title: On-demand ruby_ui component installation +description: The installer only installs a BASE shell set; each scaffold installs just the column/flag-specific components it references, skipping ones already present. +tags: [ruby_ui, install] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: resolver + title: component_resolver.rb + resource: ../../lib/ruby_ui_scaffold/component_resolver.rb + - id: installer + title: component_installer.rb + resource: ../../lib/ruby_ui_scaffold/component_installer.rb + - id: views + title: ScaffoldGenerator#install_required_components + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb +--- + +# Decision + +Apps should carry only the ruby_ui components they use, so neither generator +runs `ruby_ui:component:all`. + +- `ComponentResolver::BASE` — always used (index/show/form shell): `table link + button card typography dropdown_menu alert_dialog form input`. Installed by + the [Install generator](/generators/install-generator.md).[^resolver] +- `ComponentResolver.call(attributes:, datatable:)` adds: `data_table` for + `--datatable`; boolean → `badge checkbox`; text → `textarea`; date → + `date_picker`; non-polymorphic reference → `combobox select`.[^resolver] + Must stay consistent with [Field type mapper](/runtime/field-type-mapper.md). +- Lists **direct** references only; `ruby_ui:component` resolves transitive deps + itself per ruby_ui's `dependencies.yml` (e.g. date_picker → calendar + popover). + +# Load-bearing guard + +`component_installed?` checks `app/components/ruby_ui/` (dir or `.rb`). +Skipping present components is not an optimization: `ruby_ui:component` copies +without `--force`, so re-installing **prompts interactively and hangs** a +non-interactive subprocess.[^installer] + +# Failure policy differs by caller + +- Installer: abort on failure (`exit(1)`). +- Scaffold: **warn and continue** — the views are already written, so one missing + component shouldn't tear down the run. Gated like [Auto-install](/generators/auto-install.md).[^views] diff --git a/.okf/runtime/field-type-mapper.md b/.okf/runtime/field-type-mapper.md new file mode 100644 index 0000000..13e9efc --- /dev/null +++ b/.okf/runtime/field-type-mapper.md @@ -0,0 +1,54 @@ +--- +type: Component +title: Field type mapper +description: Maps a GeneratedAttribute to a ruby_ui form input, returned as a Ruby source snippet string for interpolation into form.rb.tt. +resource: ../../lib/ruby_ui_scaffold/field_type_mapper.rb +tags: [ruby_ui, phlex, forms] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: mapper + title: field_type_mapper.rb + resource: ../../lib/ruby_ui_scaffold/field_type_mapper.rb + - id: changelog + title: CHANGELOG 0.1.1 — Fixed + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/CHANGELOG.md + - id: readme + title: README — Type → ruby_ui component mapping + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md +--- + +# Contract + +`FieldTypeMapper.render(attribute, model_var:)` returns **source code**, not an +object. Multi-line snippets come back with no leading indentation; the caller +(`ruby_ui_input_for` in the [Views generator](/generators/views-generator.md)) +re-indents them.[^mapper] The full type → component table lives in the README;[^readme] +keep it in sync when changing output. + +# Dispatch order + +password_digest → attachment(s) → reference → `case type`. Order matters: a +`password_digest` or attachment must be caught before the type fallback.[^mapper] + +# Non-obvious mappings + +- **decimal** → value is `&.to_s`: Phlex 2 raises `Phlex::ArgumentError` on + `BigDecimal` attribute values; ActiveSupport makes `BigDecimal#to_s` plain + notation. Shipped as a crash in 0.1.0, fixed in 0.1.1.[^changelog] +- **time / datetime** → `strftime` into the HTML5 input formats. +- **date** → ruby_ui `DatePicker` with `selected_date:` and `label: nil` (the form + already emits `FormFieldLabel`).[^mapper] +- **boolean** → hidden `"0"` input + `Checkbox` value `"1"`, the Rails convention + so unchecking submits. +- **password** → value always `""` (never echo the digest). +- **references** → `Select` below `COMBOBOX_THRESHOLD` (100, a per-form constant in + `form.rb.tt`), searchable `Combobox` above it. Combobox's Stimulus controller + syncs its trigger label from the checked radio on connect; **Select's does + not**, so the current label is rendered inline and the item marked with + `aria_selected`.[^mapper] Labels fall back `name` → `title` → `display_name` → + `" "`. +- **polymorphic reference** → plain number `Input` with a TODO comment. + +Which components these imply is in [Component resolution](/runtime/component-resolution.md). diff --git a/.okf/runtime/index.md b/.okf/runtime/index.md new file mode 100644 index 0000000..3742290 --- /dev/null +++ b/.okf/runtime/index.md @@ -0,0 +1,6 @@ +# Runtime library + +* [Field type mapper](field-type-mapper.md) - Attribute → ruby_ui input snippet. +* [Attribute helpers](attribute-helpers.md) - Sortable, searchable and reference column rules. +* [On-demand component installation](component-resolution.md) - BASE set plus per-scaffold components; skip-if-present guard. +* [Transitive Railtie requires](transitive-railtie-requires.md) - Why the top-level require loads phlex-rails, literal and lucide-rails. diff --git a/.okf/runtime/transitive-railtie-requires.md b/.okf/runtime/transitive-railtie-requires.md new file mode 100644 index 0000000..b177434 --- /dev/null +++ b/.okf/runtime/transitive-railtie-requires.md @@ -0,0 +1,30 @@ +--- +type: Decision +title: Top-level require pulls in phlex-rails, literal and lucide-rails +description: lib/ruby_ui_scaffold.rb explicitly requires its dependencies so their Railties fire under Bundler.require; removing them breaks generated views and the seed command. +resource: ../../lib/ruby_ui_scaffold.rb +tags: [rails-internals, phlex] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: main + title: lib/ruby_ui_scaffold.rb + resource: ../../lib/ruby_ui_scaffold.rb +--- + +# Decision + +`require "phlex-rails"`, `"literal"` and `"lucide-rails"` at the top level, and +the Railtie only `if defined?(Rails::Railtie)`.[^main] + +# Why + +`Bundler.require` only requires gems listed in the host Gemfile, not transitive +dependencies. Without these explicit requires, helpers such as `lucide_icon` +aren't registered, generators like `phlex:install` / `ruby_ui:component` aren't +discoverable, and generated views and the [Seed command](/seeding/seed-command.md) +crash at runtime.[^main] + +Note the contrast with [Lazy generator loading](/architecture/lazy-generator-loading.md): +dependency gems are required eagerly, our own **generator classes** must not be. diff --git a/.okf/seeding/index.md b/.okf/seeding/index.md new file mode 100644 index 0000000..33f18dd --- /dev/null +++ b/.okf/seeding/index.md @@ -0,0 +1,5 @@ +# Seeding + +* [Seed command](seed-command.md) - `rails ruby_ui_scaffold:seed MODEL` options and behavior. +* [Seeder](seeder.md) - Preflight, retries and summary. +* [Value inference chain](value-inference-chain.md) - How each column's fake value is chosen. diff --git a/.okf/seeding/seed-command.md b/.okf/seeding/seed-command.md new file mode 100644 index 0000000..7b2653b --- /dev/null +++ b/.okf/seeding/seed-command.md @@ -0,0 +1,30 @@ +--- +type: Component +title: Seed command +description: "`rails ruby_ui_scaffold:seed MODEL [--count N] [--reset] [--dry-run]` — a Rails::Command (not a generator) that fills a model with realistic fake records." +resource: ../../lib/rails/commands/ruby_ui_scaffold/seed_command.rb +tags: [seeding] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: cmd + title: seed_command.rb + resource: ../../lib/rails/commands/ruby_ui_scaffold/seed_command.rb +--- + +# Overview + +A `Rails::Command::Base` discovered by **file-path convention** +(`lib/rails/commands/ruby_ui_scaffold/seed_command.rb` → `ruby_ui_scaffold:seed`), +so there is no registration code to look for.[^cmd] + +| Option | Default | Effect | +|---|---|---| +| `--count`, `-c` | 10 | records to create | +| `--reset` | false | `destroy_all` first | +| `--dry-run` | false | print one sample attribute hash, save nothing | + +It boots the app, constantizes MODEL, rejects non-ActiveRecord classes and turns +`SeederError` into a message + exit 1.[^cmd] The work is done by +[Seeder](/seeding/seeder.md) and [Value inference chain](/seeding/value-inference-chain.md). diff --git a/.okf/seeding/seeder.md b/.okf/seeding/seeder.md new file mode 100644 index 0000000..5f2f523 --- /dev/null +++ b/.okf/seeding/seeder.md @@ -0,0 +1,28 @@ +--- +type: Component +title: Seeder +description: Orchestrates N record creations with a required-parent preflight, up to 3 retries per record, progress output and a summary of validation failures. +resource: ../../lib/ruby_ui_scaffold/seeder.rb +tags: [seeding] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: seeder + title: seeder.rb + resource: ../../lib/ruby_ui_scaffold/seeder.rb +--- + +# Behavior + +- **Preflight**: every required (non-optional, non-polymorphic) `belongs_to` + target must already have rows, otherwise `SeederError` tells you to seed the + parent first. Seed order is the user's job (parents before children).[^seeder] +- **Retries**: each record gets `MAX_RETRIES = 3` fresh attribute sets before it + counts as skipped; this absorbs uniqueness collisions and random validation + misses without failing the run.[^seeder] +- **Output**: progress every 10 records, labelled by `name`/`title`/`display_name`/`email`; + the summary prints the first 3 distinct validation errors. + +Values come from the [Value inference chain](/seeding/value-inference-chain.md); +invoked by the [Seed command](/seeding/seed-command.md). diff --git a/.okf/seeding/value-inference-chain.md b/.okf/seeding/value-inference-chain.md new file mode 100644 index 0000000..efa4664 --- /dev/null +++ b/.okf/seeding/value-inference-chain.md @@ -0,0 +1,43 @@ +--- +type: Component +title: Value inference chain +description: How ValueGenerator picks a fake value per column — belongs_to FK, enum, inclusion validator, numericality validator, column-name heuristic, then type fallback. +resource: ../../lib/ruby_ui_scaffold/value_generator.rb +tags: [seeding] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: vg + title: value_generator.rb + resource: ../../lib/ruby_ui_scaffold/value_generator.rb + - id: readme + title: README — Seed command + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md +--- + +# Chain (first non-nil wins) + +1. **belongs_to FK** — random existing parent id; raises `SeederError` if none. +2. **enum** — random enum key. +3. **inclusion validator** — sample from `in:`/`within:`. +4. **numericality validator** — random within the declared bounds (integer/bigint/float/decimal only). +5. **column-name heuristic** — Faker by name (`email`, `*_email`, `first_name`, `city`, `slug`, `price`, …). +6. **type fallback** — Faker/random by SQL type.[^vg] + +Validations are consulted *before* name heuristics so seeded rows pass the +model's own rules. The full heuristic table is in the README — keep both in +sync.[^readme] + +# Skipped columns + +`id`, `created_at`, `updated_at`, `*_count` (counter caches), the STI +inheritance column, and polymorphic `*_type` columns.[^vg] + +# Gotchas + +- `password` / `password_digest` get the literal `"password123"`, relying on + `has_secure_password` to hash it. +- `Faker::...unique` is used for email/username/slug; long runs can exhaust + uniqueness, which surfaces as retries in [Seeder](/seeding/seeder.md). +- The class doc comment in `value_generator.rb` omits the numericality step; the `call` chain (and CLAUDE.md) include it. diff --git a/.okf/testing/index.md b/.okf/testing/index.md new file mode 100644 index 0000000..25ca6dd --- /dev/null +++ b/.okf/testing/index.md @@ -0,0 +1,3 @@ +# Testing + +* [Test harness and CI matrix](test-harness.md) - How the gem is tested without a host app. diff --git a/.okf/testing/test-harness.md b/.okf/testing/test-harness.md new file mode 100644 index 0000000..e7687c6 --- /dev/null +++ b/.okf/testing/test-harness.md @@ -0,0 +1,46 @@ +--- +type: Runbook +title: Test harness and CI matrix +description: How the gem is tested without a host app — Rails generator TestCase into test/tmp, a subprocess Railtie regression test, unit tests for pure modules, and a Ruby × Rails CI matrix. +tags: [testing, compatibility] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: ci + title: .github/workflows/ci.yml + resource: ../../.github/workflows/ci.yml + - id: railtie-test + title: test/railtie_test.rb + resource: ../../test/railtie_test.rb +--- + +# Run + +```bash +rake test # full suite (default task) +ruby -Itest -Ilib test/generators/scaffold_generator_test.rb # one file +ruby -Itest -Ilib test/generators/scaffold_generator_test.rb -n test_creates_view_files +BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle exec rake test # one Rails version +``` + +# Layout + +| Kind | Files | Note | +|---|---|---| +| Generator tests | `test/generators/*_test.rb` | `Rails::Generators::TestCase`, output in `test/tmp/` (gitignored, regenerated — not source); assert with `assert_file` + regex | +| Pure units | `field_type_mapper`, `component_resolver`, `value_generator`, `seeder` tests | no generator boot needed | +| Railtie regression | `test/railtie_test.rb` | runs in a **subprocess**[^railtie-test] | + +Because `test/tmp/` has no `bin/rails`, [Auto-install](/generators/auto-install.md) +and on-demand component install are skipped with warnings — tests never shell out. + +The Railtie test must be a subprocess because `test_helper` already loads every +generator class — exactly the state the test needs to avoid. See +[Lazy generator loading](/architecture/lazy-generator-loading.md).[^railtie-test] + +# CI + +GitHub Actions runs Ruby 3.2 / 3.3 / 3.4 / 4.0 × Rails 7.1 / 7.2 / 8.0 / 8.1, +`fail-fast: false`, selecting `gemfiles/rails_.gemfile` via `BUNDLE_GEMFILE`.[^ci] +Keep the README compatibility matrix in step with this. diff --git a/.okf/views/index-variants.md b/.okf/views/index-variants.md new file mode 100644 index 0000000..19fceb1 --- /dev/null +++ b/.okf/views/index-variants.md @@ -0,0 +1,43 @@ +--- +type: Component +title: Index variants — Table vs DataTable +description: The default index is a plain ruby_ui Table over Model.all; --datatable switches both index view and controller to search, sort and manual pagination. +tags: [datatable, ruby_ui] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: dt-ctrl + title: controller_data_table.rb.tt + resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/templates/controller_data_table.rb.tt + - id: dt-view + title: index_data_table.rb.tt + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/templates/index_data_table.rb.tt + - id: readme + title: README — --datatable / Index features + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md +--- + +# Default (`index.rb.tt` + `controller.rb.tt`) + +Plain `Table`; controller does `Model.all` (+ `.includes` for references); the +view takes one `:` kwarg. No toolbar, no pagination. + +# `--datatable` (`index_data_table.rb.tt` + `controller_data_table.rb.tt`) + +Controller, all values allowlisted or clamped:[^dt-ctrl] + +- `SORTABLE_COLUMNS` baked from [Attribute helpers](/runtime/attribute-helpers.md); + `params[:sort]` ignored unless listed, `direction` ∈ asc/desc. +- `per_page` clamped to 1..100 (default 10); `page` ≥ 1. +- Search: `LOWER(col) LIKE :q` OR-ed over string columns, bound parameter. +- Manual `limit`/`offset` + `total_count` — **no pagy/kaminari dependency**. + +View: `DataTableToolbar` (search + per-page), `DataTableSortHead` on sortable +columns, `DataTablePaginationBar`.[^dt-view] Search UI renders only if a string +column exists.[^readme] + +Selected by the [Controller generator](/generators/controller-generator.md) and +[Views generator](/generators/views-generator.md) independently, both from +`--datatable` — which is why that flag must reach both +([Option propagation](/architecture/option-propagation.md)). diff --git a/.okf/views/index.md b/.okf/views/index.md new file mode 100644 index 0000000..2195a81 --- /dev/null +++ b/.okf/views/index.md @@ -0,0 +1,4 @@ +# Views + +* [Generated view conventions](view-conventions.md) - Namespacing, layout, Literal props and UI patterns. +* [Index variants](index-variants.md) - Plain Table vs DataTable. diff --git a/.okf/views/view-conventions.md b/.okf/views/view-conventions.md new file mode 100644 index 0000000..80cc962 --- /dev/null +++ b/.okf/views/view-conventions.md @@ -0,0 +1,50 @@ +--- +type: Convention +title: Generated view conventions +description: Namespacing, layout wrapping, Literal props and UI patterns every generated Phlex view follows, with the reasons behind each. +tags: [phlex, ruby_ui, flags] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: index + title: index.rb.tt + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/templates/index.rb.tt + - id: form + title: form.rb.tt + resource: ../../lib/generators/ruby_ui_scaffold/scaffold/templates/form.rb.tt + - id: changelog + title: CHANGELOG 0.1.0 / 0.1.1 + resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/CHANGELOG.md +--- + +# Namespacing + +Views are `Views:::: < Views::Base` in `app/views//*.rb`, +matching `phlex:install` (which wires `app/views/` as the `Views::` root — no +extra autoload config). Controllers reference them as `::Views::...` so they +never resolve to an ERB sibling or a nested constant.[^index] + +# Flags in templates + +- `--literal` → `prop :users, _Any` / `prop :user, User` instead of + `def initialize` + ivars; runtime type-checked. +- `--phlex_layout=Class` → body wrapped in `render(Class) do ... end` and + controller `layout false`. Motivation: in dual-layout apps (ERB for guest + pages, Phlex for the dashboard) inheriting the default Rails layout loads the + wrong JS bundle and breaks Stimulus controllers.[^changelog] + +# UI patterns and why + +| Pattern | Why | +|---|---| +| Index body inside `div(class: "h-dvh w-full overflow-y-auto")` | Hosts with `body { overflow: hidden }` (fixed-sidebar dashboards) would otherwise not scroll[^index] | +| `Table(class: "table-fixed")` + `div.truncate` cells with `title:` | No horizontal overflow; full value on hover | +| Actions = `DropdownMenu(options: { strategy: "fixed" })` with Lucide `more-horizontal` trigger, no wrapper span | Wrapper elements stopped the dropdown toggle action from firing[^changelog] | +| Delete inside an `AlertDialog` + `form_with(method: :delete)` | No JS `confirm()` | +| Boolean `Badge(variant: :success / :outline)` — **symbols** | `RubyUI::Badge::COLORS` is symbol-keyed and doesn't `to_sym`; string variants rendered colorless (fixed 0.1.1)[^changelog] | +| Index `max-w-7xl`; show/new/edit `max-w-3xl`; form `max-w-prose` | Wide for tables, focused for single records | +| Form Back link → `request&.referer || index_path` | Return to where the user came from[^form] | + +Index flavours are in [Index variants](/views/index-variants.md); inputs in +[Field type mapper](/runtime/field-type-mapper.md). diff --git a/CLAUDE.md b/CLAUDE.md index 9dc91f2..c3cdc1f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,7 +33,7 @@ A single `rails g ruby_ui_scaffold User ...` fans out through three cooperating 1. **`RubyUiScaffoldGenerator`** (`lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb`) — subclasses Rails' `ScaffoldGenerator`, inheriting model/migration/route/test/helper generation for free. It does three critical things: - Forces `namespace "ruby_ui_scaffold"` (flat, not the auto-derived nested `ruby_ui_scaffold:ruby_ui_scaffold`). The nested form would shadow `find_by_namespace` lookups for our `:scaffold` and `:scaffold_controller` sub-generators and cause silent recursion. - Redirects the `scaffold_controller` hook to our subclass via `hook_for :scaffold_controller, as: :scaffold_controller`. - - `--skip-model`: skips the inherited `:orm` hook (model + migration + model test + fixtures) for re-runs, by overriding the Thor-generated command `_invoke_from_option_orm` to no-op (leaving `options[:orm]` intact, so orm helpers and controller-hook propagation are unaffected). It also implies `--force` (set in `initialize` via `self.options = options.merge(force: true)`) because a re-run otherwise aborts on the controller's class-collision check, and the intent is to overwrite the regenerated files. Model = user's code (never touched); controller/views = regenerated. + - `--skip-model`: skips the inherited `:orm` hook (model + migration + model test + fixtures) for re-runs, by overriding the Thor-generated command `_invoke_from_option_orm` to no-op (leaving `options[:orm]` intact, so orm helpers and controller-hook propagation are unaffected). It also implies `--force` because a re-run otherwise aborts on the controller's class-collision check, and the intent is to overwrite the regenerated files. `initialize` injects `--force` into the **raw** init options (CLI array or hash) *before* calling `super` — not by mutating `options` after parse — because the controller/views sub-generators are invoked by Thor re-parsing the original init args stored in `@_initializer`; a post-parse `options.merge(force: true)` would never reach them. Model = user's code (never touched); controller/views = regenerated. 2. **`ScaffoldControllerGenerator`** (`.../scaffold_controller/`) — subclasses Rails' controller generator, overrides its template to render Phlex view classes (`render ::Views::Users::Index.new(...)`) instead of ERB, and redirects the `template_engine` hook to `as: :scaffold` so **our** views generator runs instead of `erb:scaffold`. @@ -41,7 +41,7 @@ A single `rails g ruby_ui_scaffold User ...` fans out through three cooperating `Railtie#generators` (`lib/ruby_ui_scaffold/railtie.rb`) only sets `Rails::Generators.options[:ruby_ui_scaffold][:template_engine] = "ruby_ui_scaffold"` — it must **not** require any generator class. Rails runs `generators` blocks *before* `Rails::Generators.configure!`, and `hook_for`/`class_option` freeze option defaults at class-definition time: requiring generators there loads Rails' `ModelGenerator` early and freezes its `:orm` as `false`, silently skipping the model + migration (for plain `rails g model` too). Our classes are loaded lazily by Rails' namespace lookup instead. Because that lookup requires only the **first** existing candidate file, the entry generator (`ruby_ui_scaffold_generator.rb`) eagerly requires its sub-generators — otherwise the views hook resolves to the already-loaded entry file and reports `ruby_ui_scaffold [not found]`. `test/railtie_test.rb` guards both in a subprocess through the real `load_generators` path. -When editing any generator, the three `class_option` declarations (`--datatable`, `--literal`, `--phlex_layout`) must stay in sync across all three generators, since options propagate down the hook chain. +Options propagate down the hook chain by Thor re-parsing the original CLI args in each sub-generator, so a flag only has a value in a generator that declares it as a `class_option`. Rule: declare a flag on the entry generator (so the CLI accepts it) and on every generator that reads it. Current state: `--datatable` and `--phlex_layout` are declared on all three generators (both controller and views act on them); `--literal` is declared only on the entry and views generators — the controller doesn't read it, and the views generator still receives it from the raw args; `--skip_install` is on all three (pass-through only in the controller); `--skip_model` is entry-only. ### Templates @@ -75,3 +75,7 @@ When editing any generator, the three `class_option` declarations (`--datatable` - Generated Phlex views always live under the `Views::` module (matching `phlex:install`'s convention); controllers reference them fully-qualified (`::Views::...`) to avoid clashing with ERB siblings in `app/views/`. - `ScaffoldGenerator#preflight_checks` **auto-runs the idempotent `ruby_ui_scaffold:install`** (shelled out via `bin/rails generate`) when phlex/ruby_ui aren't detected, so generated views work out of the box. It falls back to a non-blocking **warning** (never aborts) when opted out via `--skip-install` or when there's no app `bin/rails` to drive it (e.g. the generator test harness). The shell-out — rather than in-process `invoke` — is deliberate: the installer calls `exit(1)` on unrecoverable errors, which a subprocess contains instead of tearing down the scaffold run. - The `README.md` is the authoritative user-facing spec for generated output (type→component mapping, seed heuristics, flag behavior). When changing generated output, keep README tables in sync. + +## Knowledge base (OKF) + +All knowledge about this gem — architecture, design decisions, conventions, and documentation — is recorded via **OKF** (Open Knowledge Format), using the `okf` skill. When you learn something non-obvious, make or change a design decision, or update behavior/documentation, capture or update it in the OKF bundle (`.okf/`) rather than leaving it only in conversation. Before answering questions about the gem, consult the OKF bundle first.