ruby_ui_scaffold 0.1.0

data/lib/generators/ruby_ui_scaffold/install/install_generator.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "ruby_ui_scaffold/component_resolver"
+require "ruby_ui_scaffold/component_installer"
+
+module RubyUiScaffold
+  module Generators
+    # One-shot installer that wires up the prerequisites every scaffold needs
+    # on a fresh Rails app: the ruby_ui gem, phlex, ruby_ui, and the BASE set
+    # of components every generated scaffold uses (index/show/form shell).
+    #
+    # Column/flag-specific components (badge, checkbox, textarea, combobox,
+    # select, date_picker, data_table) are NOT installed here — the scaffold
+    # generator installs those on demand, so apps only carry what they use.
+    #
+    # Invoked as: `bin/rails g ruby_ui_scaffold:install`
+    #
+    # Every step is idempotent — re-running the installer is safe and only
+    # touches what's actually missing.
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::RubyUiScaffold::ComponentInstaller
+
+      desc "Install the ruby_ui gem, phlex, ruby_ui, and the base scaffold components."
+
+      def check_phlex_rails_gem
+        return if Gem.loaded_specs.key?("phlex-rails")
+
+        say "\n  ❌  The `phlex-rails` gem isn't bundled in this app.", :red
+        say "      ruby_ui_scaffold declares it as a runtime dependency — running", :red
+        say "      `bundle install` should pull it in. If you've excluded it via", :red
+        say "      Bundler groups, add it back and retry:\n", :red
+        say %(          gem "phlex-rails"), :cyan
+        say "          bundle install"
+        say "          bin/rails g ruby_ui_scaffold:install\n", :cyan
+        exit(1)
+      end
+
+      # Ensure the `ruby_ui` gem is available. Unlike `phlex-rails` (a declared
+      # runtime dependency of this gem), `ruby_ui` is distributed via GitHub and
+      # can't be a gemspec dependency — so on a fresh app it usually isn't
+      # bundled yet. Rather than abort, add it to the Gemfile and `bundle
+      # install` automatically, then let the rest of the installer proceed:
+      # the subsequent `ruby_ui:install` / `ruby_ui:component` steps run in
+      # subprocesses (via run_rails_generator!) that boot with the freshly
+      # updated bundle, so they find the gem even though THIS process didn't
+      # load it. Idempotent — skips the Gemfile edit when an entry already
+      # exists, and does nothing at all once the gem loads.
+      def ensure_ruby_ui_gem
+        return if ruby_ui_loadable?
+
+        gemfile = File.join(destination_root, "Gemfile")
+        abort_ruby_ui_unavailable! unless File.exist?(gemfile)
+
+        if File.read(gemfile).match?(/^\s*gem\s+["']ruby_ui["']/)
+          say "\n  → ruby_ui is in the Gemfile but not bundled yet — running `bundle install`.", :cyan
+        else
+          say "\n  → ruby_ui gem not found — adding it to your Gemfile.", :cyan
+          gem "ruby_ui", github: "ruby-ui/ruby_ui", branch: "main", require: false
+        end
+
+        run_bundle_install!
+      end
+
+      def install_phlex
+        if File.exist?(File.join(destination_root, "app/views/base.rb"))
+          say "  ✓ phlex already installed (app/views/base.rb exists)", :green
+          return
+        end
+
+        say "\n  → Running `phlex:install`", :cyan
+        run_rails_generator!("phlex:install")
+      end
+
+      def install_ruby_ui
+        components_base = File.join(destination_root, "app/components/base.rb")
+        if File.exist?(components_base) && File.read(components_base).include?("RubyUI")
+          say "  ✓ ruby_ui already installed (Components::Base includes RubyUI)", :green
+          return
+        end
+
+        say "\n  → Running `ruby_ui:install`", :cyan
+        run_rails_generator!("ruby_ui:install")
+      end
+
+      # Install the BASE components every scaffold uses (the index/show/form
+      # shell), so a bare `:install` leaves the ground ready. We deliberately
+      # don't run `ruby_ui:component:all` — column/flag-specific components are
+      # installed on demand by the scaffold generator. `ruby_ui:component`
+      # resolves transitive dependencies itself (e.g. alert_dialog → button),
+      # so the BASE list only names what the scaffold references directly.
+      def install_base_components
+        missing = uninstalled_components(::RubyUiScaffold::ComponentResolver::BASE)
+
+        if missing.empty?
+          say "  ✓ Base scaffold components already installed", :green
+          return
+        end
+
+        say "\n  → Installing #{missing.size} base component(s) every scaffold uses", :cyan
+        missing.each do |component|
+          say "      • #{component}", :cyan
+          run_rails_generator!("ruby_ui:component", component)
+        end
+      end
+
+      # Tailwind v4 auto-detection misses `.rb` files by default, so the
+      # Phlex view + component class names never make it into the compiled
+      # stylesheet — meaning `mx-auto`, `max-w-prose`, etc. render with no
+      # effect. Inject explicit `@source` directives so Tailwind scans
+      # `app/views/**/*.rb` and `app/components/**/*.rb`. Idempotent.
+      def inject_tailwind_sources
+        css_path = File.join(destination_root, "app/assets/tailwind/application.css")
+        return unless File.exist?(css_path)
+
+        contents = File.read(css_path)
+        sources_to_add = []
+        sources_to_add << %(@source "../../views/**/*.rb";) unless contents.include?("../../views/**/*.rb")
+        sources_to_add << %(@source "../../components/**/*.rb";) unless contents.include?("../../components/**/*.rb")
+        return if sources_to_add.empty?
+
+        say "\n  → Adding Tailwind @source directives for Phlex views/components", :cyan
+        inject_into_file css_path, after: /@import "tailwindcss";\n/ do
+          "\n" + sources_to_add.join("\n") + "\n"
+        end
+      end
+
+      def done
+        say "\n  ✅ ruby_ui_scaffold install complete.", :green
+        say "\n     Generate your first scaffold:\n", :cyan
+        say "         bin/rails g ruby_ui_scaffold MyModel name:string\n", :cyan
+      end
+
+      private
+
+      # No Gemfile to add ruby_ui to — fall back to the manual instructions.
+      def abort_ruby_ui_unavailable!
+        say "\n  ❌  The `ruby_ui` gem isn't available and no Gemfile was found to add it to.", :red
+        say "      Add it to your Gemfile, then bundle and retry:\n", :red
+        say %(          gem "ruby_ui", github: "ruby-ui/ruby_ui", branch: "main", require: false), :cyan
+        say "          bundle install"
+        say "          bin/rails g ruby_ui_scaffold:install\n", :cyan
+        exit(1)
+      end
+
+      def run_bundle_install!
+        say_status :run, "bundle install", :cyan
+        success = in_root { system("bundle", "install") }
+        return if success
+
+        say "\n  ❌  `bundle install` failed after adding ruby_ui to the Gemfile.", :red
+        say "      Resolve the error above, then re-run `bin/rails g ruby_ui_scaffold:install` —", :red
+        say "      it's idempotent, so anything already installed stays installed.", :yellow
+        exit(1)
+      end
+
+      # ruby_ui ships with `require: false` in the recommended Gemfile entry,
+      # so it may not be autoloaded yet — try requiring it before giving up.
+      def ruby_ui_loadable?
+        return true if defined?(::RubyUI)
+
+        require "ruby_ui"
+        true
+      rescue LoadError
+        false
+      end
+
+      # Shell-out to `bin/rails generate NAME [ARGS...]` and abort if the
+      # subprocess exits non-zero. We don't use Thor's `generate` action
+      # because its `abort_on_failure` doesn't reliably propagate when the
+      # failure originates inside the inner Rails command (e.g. Bundler
+      # bootstrap errors swallow the exit code). Without explicit checks,
+      # one bad step would silently cascade into dozens of follow-up
+      # failures with the same root cause.
+      def run_rails_generator!(name, *args)
+        cmd = ["bin/rails", "generate", name, *args].compact
+        say_status :run, cmd.join(" "), :cyan
+        success = in_root { system(*cmd) }
+        return if success
+
+        say "\n  ❌  `#{cmd.join(" ")}` failed (exit #{$?.exitstatus}).", :red
+        say "      Aborting ruby_ui_scaffold:install. Fix the error above and retry —", :red
+        say "      every step is idempotent, so what's already installed stays installed.", :yellow
+        exit(1)
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/rails/scaffold/scaffold_generator"
+
+module RubyUiScaffold
+  module Generators
+    # Entry point: `rails g ruby_ui_scaffold User name:string ...`
+    #
+    # Inherits the full scaffold pipeline from Rails (model, migration,
+    # resource route, tests, helper), but redirects the scaffold_controller
+    # hook to our subclass — which in turn redirects the template_engine
+    # hook to our Phlex views generator.
+    class RubyUiScaffoldGenerator < ::Rails::Generators::ScaffoldGenerator
+      # Override the auto-derived namespace ("ruby_ui_scaffold:ruby_ui_scaffold")
+      # to flat "ruby_ui_scaffold". This is critical because find_by_namespace
+      # iterates lookups in order — leaving the namespace at the nested form
+      # would cause `ruby_ui_scaffold:ruby_ui_scaffold` to shadow lookups for
+      # `ruby_ui_scaffold:scaffold` (our views generator) and `ruby_ui_scaffold:
+      # scaffold_controller` (our controller generator), creating silent
+      # recursion when those hooks fire.
+      namespace "ruby_ui_scaffold"
+
+      # Redirect scaffold_controller hook to our subclass. `as: :scaffold_controller`
+      # makes the find_by_namespace lookup resolve `ruby_ui_scaffold:scaffold_controller`
+      # (via its name:context form) instead of `ruby_ui_scaffold:ruby_ui_scaffold`.
+      remove_hook_for :scaffold_controller
+      hook_for :scaffold_controller, as: :scaffold_controller, required: true
+
+      # Wrap each generated view_template in `render(<ClassName>) do ... end`
+      # and emit `layout false` in the controller. Use when your app has a
+      # Phlex layout class (with `include Phlex::Rails::Layout`) that you
+      # want every scaffolded page to render inside.
+      class_option :phlex_layout, type: :string, default: nil, banner: "LayoutClass",
+        desc: "Wrap each generated view in `render(LayoutClass) do ... end` and skip the default Rails layout"
+
+      # When true, the index uses ruby_ui's `DataTable` (search, per-page,
+      # sortable headers, manual pagination) and the controller bakes in the
+      # params parsing + scope building. Default: plain `Table` (no toolbar,
+      # no pagination — controller just does Model.all).
+      class_option :datatable, type: :boolean, default: false,
+        desc: "Generate the index using ruby_ui DataTable (search + sort + pagination) instead of a plain Table"
+
+      # When true, the generated Phlex views use Literal's `prop` macros
+      # instead of explicit `def initialize` + `@ivar` assignments. Less
+      # boilerplate per view; runtime type-checking included. Also injects
+      # `extend Literal::Properties` into `app/components/base.rb` on first
+      # use (idempotent).
+      class_option :literal, type: :boolean, default: false,
+        desc: "Use Literal's `prop` macros instead of explicit `def initialize` blocks (https://literal.fun)"
+
+      # By default, generating a scaffold auto-runs the idempotent
+      # `ruby_ui_scaffold:install` when phlex/ruby_ui aren't detected yet, so
+      # the generated views work out of the box. Pass --skip-install to only
+      # print a warning instead (the pre-auto-install behavior).
+      class_option :skip_install, type: :boolean, default: false,
+        desc: "Don't auto-run `ruby_ui_scaffold:install` when phlex/ruby_ui aren't detected — only warn"
+
+      # Skip model/migration/model-test/fixtures generation (the whole `:orm`
+      # hook), regenerating only the controller, views, helper, and route.
+      # Intended for RE-RUNS against a model that already exists — e.g. to
+      # refresh the views after a template change, or to add `--datatable`
+      # without Rails creating a duplicate migration or clobbering the model.
+      #
+      # Implies `--force`: a re-run otherwise aborts on the controller's class
+      # collision check (the controller is already defined), and the point is
+      # to overwrite the regenerated files without per-file prompts. The model
+      # is never touched (its hook is skipped), so custom model code is safe —
+      # the mental model is "model = your code, controller/views = generated".
+      class_option :skip_model, type: :boolean, default: false,
+        desc: "Skip model/migration/fixtures and only regenerate controller/views/routes (implies --force; for re-runs)"
+
+      # --skip-model implies --force: a re-run otherwise aborts on the
+      # controller's class-collision check (the controller already exists), and
+      # the intent is to overwrite the regenerated controller/views. We inject
+      # "--force" into the RAW options before Thor parses them — not by mutating
+      # `options` afterward — because the controller/views sub-generators are
+      # invoked by re-parsing the original init options stored in Thor's
+      # `@_initializer` (see Thor::Invocation#_parse_initialization_options). A
+      # post-parse mutation of `options` never reaches them; a real flag does.
+      def initialize(args, local_options = {}, config = {})
+        local_options = imply_force(local_options) if skip_model_requested?(local_options)
+        super
+      end
+
+      # Command for the inherited `:orm` hook (model + migration + model test +
+      # fixtures). Thor generates it as `_invoke_from_option_orm`; we override
+      # it to no-op under --skip-model while leaving `options[:orm]` intact, so
+      # orm helpers and option propagation to the controller are unaffected.
+      def _invoke_from_option_orm
+        return if options[:skip_model]
+
+        super
+      end
+
+      private
+
+      # Detect --skip-model from the raw init options, which may be the CLI
+      # option-string array (the usual `rails g` path) or a pre-parsed hash
+      # (programmatic instantiation / tests).
+      def skip_model_requested?(local_options)
+        if local_options.is_a?(Array)
+          local_options.include?("--skip-model") || local_options.include?("--skip_model")
+        else
+          !!(local_options[:skip_model] || local_options["skip_model"])
+        end
+      end
+
+      # Add force to the raw options (array or hash) without duplicating it.
+      def imply_force(local_options)
+        if local_options.is_a?(Array)
+          local_options.include?("--force") ? local_options : local_options + ["--force"]
+        else
+          local_options.merge(force: true)
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require "rails/generators/resource_helpers"
+require "ruby_ui_scaffold/field_type_mapper"
+require "ruby_ui_scaffold/attribute_helpers"
+require "ruby_ui_scaffold/component_resolver"
+require "ruby_ui_scaffold/component_installer"
+
+module RubyUiScaffold
+  module Generators
+    # The "template engine" — generates the Phlex view classes
+    # for index, show, new, edit, and a shared form under the
+    # `Views::` namespace (matches the convention installed by
+    # `phlex:install`, which creates `Views::Base` and wires the
+    # `app/views/` autoloader).
+    #
+    # Invoked indirectly via `ruby_ui_scaffold:scaffold_controller`,
+    # which sets template_engine default to `ruby_ui_scaffold`.
+    class ScaffoldGenerator < ::Rails::Generators::NamedBase
+      include ::Rails::Generators::ResourceHelpers
+      include ::RubyUiScaffold::AttributeHelpers
+      include ::RubyUiScaffold::ComponentInstaller
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      class_option :api, type: :boolean, default: false
+      class_option :force_plural, type: :boolean, default: false
+      class_option :phlex_layout, type: :string, default: nil, banner: "LayoutClass",
+        desc: "Wrap each generated view in `render(LayoutClass) do ... end`"
+      class_option :datatable, type: :boolean, default: false,
+        desc: "Emit the DataTable index variant (search + sort + pagination) instead of a plain Table"
+      class_option :literal, type: :boolean, default: false,
+        desc: "Use Literal's `prop` macros instead of `def initialize` (https://literal.fun)"
+      class_option :skip_install, type: :boolean, default: false,
+        desc: "Don't auto-run `ruby_ui_scaffold:install` when phlex/ruby_ui aren't detected — only warn"
+
+      # Generator action — runs before view files are written. The generated
+      # views need phlex (`Views::Base`) and ruby_ui (`RubyUI` mixed into
+      # `Components::Base`); without them, requests 500 at runtime. When either
+      # is missing we auto-run the idempotent `ruby_ui_scaffold:install` so the
+      # scaffold works out of the box. Falls back to a non-blocking warning when
+      # auto-install isn't possible (no app `bin/rails`) or is opted out with
+      # `--skip-install`.
+      def preflight_checks
+        return if behavior == :revoke
+
+        ensure_phlex_and_ruby_ui_installed
+      end
+
+      def create_view_files
+        empty_directory File.join("app/views", controller_file_path)
+
+        # Index has two flavors: plain Table (default) or DataTable (--datatable).
+        # Both compile down to `app/views/<resource>/index.rb`.
+        index_template = options[:datatable] ? "index_data_table.rb.tt" : "index.rb.tt"
+        template index_template, File.join("app/views", controller_file_path, "index.rb")
+
+        %w[show new edit form].each do |view|
+          template "#{view}.rb.tt", File.join("app/views", controller_file_path, "#{view}.rb")
+        end
+      end
+
+      # Inject the Phlex helpers the scaffold-generated views rely on into
+      # `Components::Base`. `phlex:install` / `ruby_ui:install` create the
+      # file but only include `Phlex::Rails::Helpers::Routes` + RubyUI — the
+      # scaffold also needs `form_with`, `link_to`, `button_to`, `request`
+      # (for the form's "Back" link), and `lucide_icon`. When `--literal` is
+      # passed, also `extend
+      # Literal::Properties` so the generated views' `prop` macros resolve.
+      # Each line is added only if missing, so re-running is safe.
+      def inject_scaffold_helpers_into_components_base
+        return if behavior == :revoke
+
+        components_base = File.join(destination_root, "app/components/base.rb")
+        return unless File.exist?(components_base)
+
+        contents = File.read(components_base)
+
+        helpers = []
+        helpers << "  extend Literal::Properties" if options[:literal] && !contents.include?("Literal::Properties")
+        helpers << "  include Phlex::Rails::Helpers::FormWith" unless contents.include?("Phlex::Rails::Helpers::FormWith")
+        helpers << "  include Phlex::Rails::Helpers::LinkTo" unless contents.include?("Phlex::Rails::Helpers::LinkTo")
+        helpers << "  include Phlex::Rails::Helpers::ButtonTo" unless contents.include?("Phlex::Rails::Helpers::ButtonTo")
+        helpers << "  include Phlex::Rails::Helpers::Request" unless contents.include?("Phlex::Rails::Helpers::Request")
+        helpers << "  register_output_helper :lucide_icon" unless contents.include?("register_output_helper :lucide_icon")
+
+        return if helpers.empty?
+
+        inject_into_file components_base, after: /class Components::Base.*\n/ do
+          helpers.join("\n") + "\n"
+        end
+      end
+
+      # Install the ruby_ui components THIS scaffold references, on demand,
+      # after the views are written. The BASE set is already installed by
+      # `ruby_ui_scaffold:install`; here we add the column/flag-specific ones
+      # (badge, checkbox, textarea, combobox, select, date_picker, data_table)
+      # — but request the full set and skip whatever's already present, so it
+      # works whether or not `:install` ran first. Non-blocking: a component
+      # that fails to install just warns (the view files already exist). Gated
+      # like the auto-install: skipped on --skip-install or when there's no app
+      # `bin/rails` to drive `ruby_ui:component` (e.g. the test harness).
+      def install_required_components
+        return if behavior == :revoke
+        return if options[:skip_install] || !app_bin_rails?
+
+        needed = ::RubyUiScaffold::ComponentResolver.call(
+          attributes: attributes, datatable: options[:datatable]
+        )
+        missing = uninstalled_components(needed)
+        return if missing.empty?
+
+        say "\n  → Installing #{missing.size} ruby_ui component(s) this scaffold uses", :cyan
+        missing.each do |component|
+          say "      • #{component}", :cyan
+          install_ruby_ui_component(component)
+        end
+      end
+
+      private
+
+      # Shell out to `ruby_ui:component NAME` in a clean process (which boots
+      # with the current bundle and resolves the component's transitive deps).
+      # Warn-and-continue on failure — unlike the installer's abort, the views
+      # are already written, so a single missing component shouldn't tear down
+      # the run.
+      def install_ruby_ui_component(component)
+        ok = in_root { system("bin/rails", "generate", "ruby_ui:component", component) }
+        return if ok
+
+        say "  ⚠️  Couldn't install ruby_ui component `#{component}`.", :yellow
+        say "     Run `bin/rails g ruby_ui:component #{component}` manually.", :yellow
+      end
+
+      # Auto-run `ruby_ui_scaffold:install` when phlex/ruby_ui aren't set up.
+      # The installer is idempotent, so it's safe even if one of the two is
+      # already present. Falls back to a warning when opted out or when there's
+      # no app `bin/rails` to drive the installer (e.g. the generator test
+      # harness, or a non-standard app layout).
+      def ensure_phlex_and_ruby_ui_installed
+        return if phlex_installed? && ruby_ui_installed?
+
+        if options[:skip_install] || !app_bin_rails?
+          warn_missing_setup
+          return
+        end
+
+        missing = []
+        missing << "phlex" unless phlex_installed?
+        missing << "ruby_ui" unless ruby_ui_installed?
+        say "\n  → #{missing.join(" + ")} not detected — running `ruby_ui_scaffold:install` first.", :cyan
+        say "    (idempotent; pass --skip-install to only warn instead)\n", :cyan
+
+        run_install!
+      end
+
+      # Shell out to the installer in a clean process. We don't `invoke` it
+      # in-process because the installer calls `exit(1)` on unrecoverable
+      # errors (e.g. the ruby_ui gem isn't bundled) — a subprocess keeps that
+      # from tearing down the scaffold run.
+      def run_install!
+        installed = in_root { system("bin/rails", "generate", "ruby_ui_scaffold:install") }
+        return if installed && phlex_installed? && ruby_ui_installed?
+
+        say "\n  ⚠️  Auto-install didn't finish the setup. Generating the scaffold files", :yellow
+        say "     anyway — run `bin/rails g ruby_ui_scaffold:install` and resolve the", :yellow
+        say "     error above before booting the app.\n", :yellow
+      end
+
+      def warn_missing_setup
+        check_phlex_install
+        check_ruby_ui_install
+      end
+
+      # Warn (don't abort) if `phlex:install` hasn't been run. Without it,
+      # `Views::Base` doesn't exist and the autoloader isn't wired to resolve
+      # `Views::<Resource>::Index` from `app/views/<resource>/index.rb`.
+      def check_phlex_install
+        return if phlex_installed?
+
+        say "\n  ⚠️  phlex doesn't look installed (missing app/views/base.rb).", :yellow
+        say "     Before requests will succeed, run:\n", :yellow
+        say "         bin/rails g phlex:install\n", :cyan
+      end
+
+      # Warn (don't abort) if ruby_ui doesn't look installed. The generated
+      # views use components like `Table`, `Link`, `DropdownMenu` etc., which
+      # are mixed into Components::Base by `rails g ruby_ui:install`; without
+      # it, requests 500 with NoMethodError on the first component call.
+      def check_ruby_ui_install
+        return if ruby_ui_installed?
+
+        say "\n  ⚠️  ruby_ui doesn't look installed (missing app/components/base.rb or RubyUI mixin).", :yellow
+        say "     Before requests will succeed, run:\n", :yellow
+        say "         bin/rails g ruby_ui:install\n", :cyan
+      end
+
+      def phlex_installed?
+        File.exist?(File.join(destination_root, "app/views/base.rb"))
+      end
+
+      def ruby_ui_installed?
+        components_base = File.join(destination_root, "app/components/base.rb")
+        File.exist?(components_base) && File.read(components_base).include?("RubyUI")
+      end
+
+      # Whether there's an app `bin/rails` we can shell out to. Absent in the
+      # generator test harness (temp destination) and in any non-standard
+      # layout — in those cases we warn instead of attempting auto-install.
+      def app_bin_rails?
+        File.exist?(File.join(destination_root, "bin/rails"))
+      end
+
+      # Called from form.rb.tt to emit the ruby_ui input snippet for a given
+      # attribute. Handles multi-line snippets by indenting subsequent lines
+      # to match the caller's column.
+      def ruby_ui_input_for(attribute, indent: 6)
+        snippet = RubyUiScaffold::FieldTypeMapper.render(attribute, model_var: singular_table_name)
+        pad = " " * indent
+        lines = snippet.split("\n", -1)
+        return lines.first if lines.length == 1
+
+        ([lines.first] + lines[1..].map { |line| pad + line }).join("\n")
+      end
+
+      # Phlex view class namespace, e.g. "Users" or "Admin::Users".
+      def view_namespace
+        controller_class_name
+      end
+
+      # First-level segment for the link helper, e.g. "users" -> "user_path".
+      def show_path_helper(record_var)
+        "#{singular_route_name}_url(#{record_var})"
+      end
+
+      def index_path_helper
+        "#{plural_route_name}_url"
+      end
+
+      def new_path_helper
+        "new_#{singular_route_name}_url"
+      end
+
+      def edit_path_helper(record_var)
+        "edit_#{singular_route_name}_url(#{record_var})"
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_scaffold/scaffold/templates/edit.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Views::<%= controller_class_name %>::Edit < Views::Base
+<% if options[:literal] -%>
+  prop :<%= singular_table_name %>, <%= class_name %>
+<% else -%>
+  def initialize(<%= singular_table_name %>:)
+    @<%= singular_table_name %> = <%= singular_table_name %>
+  end
+<% end -%>
+
+  def view_template
+<% if options[:phlex_layout] -%>
+    render(<%= options[:phlex_layout] %>) do
+<% end -%>
+    # Outer scroll container — same pattern as the index. Without it,
+    # absolute-positioned popovers from Select/Combobox get clipped by
+    # ancestors that set `overflow: hidden`.
+    div(class: "h-dvh w-full overflow-y-auto") do
+      div(class: "mx-auto max-w-3xl px-4 sm:px-6 lg:px-8 py-8 space-y-6") do
+        h1(class: "text-2xl font-bold") { "Edit <%= human_name %>" }
+
+        render Views::<%= controller_class_name %>::Form.new(
+          <%= singular_table_name %>: @<%= singular_table_name %>,
+          url: <%= singular_route_name %>_path(@<%= singular_table_name %>),
+          method: "patch"
+        )
+      end
+    end
+<% if options[:phlex_layout] -%>
+    end
+<% end -%>
+  end
+end

data/lib/generators/ruby_ui_scaffold/scaffold/templates/form.rb.tt

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Views::<%= controller_class_name %>::Form < Views::Base
+<% if reference_associations.any? -%>
+  # Switch to ruby_ui Combobox (with search) when an associated table has more
+  # than this many rows. Below the threshold, a plain Select is rendered.
+  # Tune per-form by editing this constant.
+  COMBOBOX_THRESHOLD = 100
+
+<% end -%>
+<% if options[:literal] -%>
+  prop :<%= singular_table_name %>, <%= class_name %>
+  prop :url, String
+  prop :method, String
+<% else -%>
+  def initialize(<%= singular_table_name %>:, url:, method:)
+    @<%= singular_table_name %> = <%= singular_table_name %>
+    @url = url
+    @method = method
+  end
+<% end -%>
+
+  def view_template
+    form_with(model: @<%= singular_table_name %>, url: @url, method: @method, class: "flex flex-col gap-4 w-full max-w-prose mx-auto") do |form|
+<% attributes.each do |attribute| -%>
+      FormField do
+        FormFieldLabel(for: "<%= "#{singular_table_name}_#{attribute.column_name}" %>") do
+          "<%= attribute.human_name %>"
+        end
+
+        <%= ruby_ui_input_for(attribute, indent: 8) %>
+
+        FormFieldError do
+          @<%= singular_table_name %>.errors.messages_for(:<%= attribute.column_name %>).to_sentence
+        end
+      end
+
+<% end -%>
+      div(class: "flex items-center gap-2") do
+        Button(type: "submit", class: "gap-2") do
+          lucide_icon(@<%= singular_table_name %>.new_record? ? "plus" : "check", class: "size-4")
+          span { @<%= singular_table_name %>.new_record? ? "Create <%= human_name %>" : "Update <%= human_name %>" }
+        end
+        # Back to wherever the user came from; falls back to the index when
+        # there's no referer (direct navigation, stripped Referer header, ...).
+        Link(href: request&.referer || <%= plural_route_name %>_path, variant: "ghost") { "Back" }
+      end
+    end
+  end
+end