RubyGems - ruact - Versions diffs - 0.0.8 → 0.0.9 - Mend

ruact 0.0.8 → 0.0.9

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

Files changed (32) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9a45065af0d01daed8548084a9667fb066f9e8c19a685f99b0f101a8e825ca0
-  data.tar.gz: 99206ecd7d61a44b4cdfe52bb5b40b046f66e2938f7bf060e603b98ef17971b8
+  metadata.gz: f1722a96137257e2263f7aee2e2315c4a197f634fad94096da555de6d7a50af9
+  data.tar.gz: 34d485a11f2b0cf893770bddbf4c48fa757d908f0f24e0c64e03d2f612bd351f
 SHA512:
-  metadata.gz: d303e5aa55881c70b88a6a7f132450712c8f35adb7b00f0172d3503784dbe82b1373ae7ecc30db05a98832f2c2154134e49bbba43ba403497cdc61b90401b91a
-  data.tar.gz: 8b8fcc40cca7167dece277333fdd56562a62800d150af0be85a50033fc6a2ea3dc8aeebf7650dbb220891f73a843a80d2b0becd1f1d7483b4a2afa6af8a1404e
+  metadata.gz: 770a14ec78795d73afed6bc044f2616167e5cd4a6b173489ad9c8e8c1df893534b54e77f5515e59a3fecbd54a4d2763eaaa3a920cbf40fc7594922e7e831a912
+  data.tar.gz: 41fc153c5d7470df08b7ca02b2c2da2a2ae0c74c717186119ed2eaa4504b903da1cfab43754a21f738b40541afc4ed98534f05fdcf4e3ba3c317f963b351b27b

data/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.0.9] - 2026-08-12
+### Added
+- **`rails generate ruact:install --shadcn` — the `--shadcn` scaffold path now has a working setup.** `ruact:scaffold --shadcn` emits components dressed in Tailwind classes, but nothing in ruact ever wired Tailwind, so the generated CRUD rendered **unstyled**: the classes had nothing to resolve against. Worse, the documented next step did not work either — shadcn's own CLI **refuses to initialize** in a ruact app, aborting with *"No Tailwind CSS configuration found"* and *"Could not find valid path aliases"*, because a fresh ruact app ships neither Tailwind nor a `tsconfig.json`.
+  The new flag emits exactly those prerequisites, each verified against the real shadcn CLI: `app/javascript/styles/globals.css` (the Tailwind entry shadcn appends its design tokens to, and points `components.json` at), a `tsconfig.json` carrying the `@/*` → `app/javascript/*` alias (the bundled Vite plugin already registers the same alias for the *bundler*; this is what makes it resolve for *TypeScript*, and therefore for shadcn's probe and your editor), `app/assets/builds/` with the compiled stylesheet gitignored, the `build:css` script, and a `css` process in `Procfile.dev` so `bin/dev` rebuilds the stylesheet alongside Rails and Vite.
+  It then **prints** the two `npx shadcn` commands instead of running them — they hit the network, and `shadcn init` is interactive, so automating them is neither safe (the scaffold generator's "never auto-run npx/npm" rule) nor possible. The printed `init` line pins **`--base radix`**, which is the part nobody would guess: current shadcn defaults to **Base UI**, while the components `ruact:scaffold --shadcn` generates import **Radix** primitives — accepting the default gets you a component library the scaffold cannot use. The printed `add` list is the complete primitive superset, pinned by a spec as a superset of whatever a given resource narrows to, so the two generators cannot drift.
+  **The default (agnostic) path is untouched** — no Tailwind, no `tsconfig.json`, and a byte-identical `package.json` and `Procfile.dev`, all pinned by specs.
+  Verified end to end twice from `rails new`: the generated CRUD renders as a styled shadcn table with the `useQuery` search filtering rows live. Note that shadcn's CLI is currently **4.x** while `shadcn_compatible_versions` defaults to `[1, 2]`, so the scaffold's version pre-flight emits its (non-blocking) warning; the generated components do work against 4.x.
+### Fixed
+- **A ruact page can now carry your app's CSS — the Rails layout owns the document.** `ruact_render` rendered the view with `layout: false` and then wrapped the Flight payload in a hardcoded HTML shell whose `<head>` holds only `charset`, `viewport`, the CSRF meta tag and the title `Rails RSC`. That shell has **no stylesheet slot and never uses your layout**, so `stylesheet_link_tag` — and with it favicons, fonts, analytics and every `<head>`-writing gem — could not reach a ruact-rendered page **at all**. The visible consequence: `rails generate ruact:scaffold --shadcn` emitted components whose Tailwind classes had nothing to resolve against, so the generated CRUD was **unstyled by construction**; the docs' instruction to put shadcn theme variables in `app/assets/stylesheets/application.css` pointed at a file that provably never reached the browser; and Epic 12 (`ruact_meta` → tags in `<head>`) had no surface to write into. The default agnostic scaffold was affected too — it renders plain semantic HTML and only *looked* acceptable because browsers style a bare `<table>`.
+  A non-Flight HTML response is now rendered **through the host app's own layout**, with the React root's bootstrap tags supplied by the layout's `<%= ruact_js_assets %>` call (which, called with no argument, picks up the render's Flight payload). The Flight wire shape (`text/x-component`) is untouched — this only changes the full document a browser gets on a normal navigation.
+  Controlled by the new **`Ruact.config.layout`** — `false` by default, `true` (or a layout name) to opt in. `rails generate ruact:install` now writes **both halves of that opt-in in the same run**: `config.layout = true` in the generated initializer, and `<%= ruact_js_assets %>` next to the React root in your layout.
+  **The default is `false`, so an existing app is untouched until it opts in** — not because ruact detects anything, but because it does not look. An earlier cut of this change tried to infer whether your layout was ready by inspecting it; three review rounds each found another template shape that fooled the inference (a mention in a comment, a commented-out call, a trim-mode comment), and each wrong answer decided how every page in the app rendered. "Does this template call this method?" is not a question pattern-matching can answer reliably, so it is no longer asked. One explicit line beats a clever guess for a setting this load-bearing. (`:auto` is rejected with a message naming its replacement, so an initializer carrying it forward cannot be silently reinterpreted.)
+  Once opted in, a layout that cannot mount the app is a configuration error rather than a silent blank page: ruact checks the rendered document for both the assets block and a `<div id="root">`, raising in development/test and logging-and-degrading to the shell in production. A controller with no resolvable layout (API-shaped, or `layout false`) degrades quietly instead — that is a normal Rails choice, not a mistake.
+  **To migrate an existing app:** add `<%= ruact_js_assets %>` next to the `<div id="root"></div>` in `app/views/layouts/application.html.erb`, or re-run `rails generate ruact:install` (which now injects both, and adds only the missing call to a layout that already has the root — tolerating single quotes, extra attributes and a same-line marker, and telling you loudly if it cannot find the root div rather than reporting a success it did not perform). `rails ruact:doctor` reports the half-migrated state as a **warning** naming the one-line fix — where it previously reported a root-only layout as a pass.
+  **Known limitation:** a ruact view is rendered in its own pass (it produces the component tree), so `content_for` declared *inside the view* does not reach the layout. Set document metadata from the controller.
+  `rails ruact:doctor` reports the two halves separately, because they are different fixes: a layout missing the root or the helper **fails**, and a ready layout with `config.layout = false` **warns** and names the setting.
 ## [0.0.8] - 2026-07-11
 ### Changed
@@ -192,6 +224,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CI matrix** — GitHub Actions: RSpec across Ruby 3.2 × 3.3 × Rails 7.0 × 7.1 × 7.2 × 8.0; RuboCop; YARD docs; memory benchmark; E2E system tests against React 19.0.0 and 19.x (Capybara + Cuprite); non-blocking React@next job with auto-issue on failure.
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.7...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.9...HEAD
+[0.0.9]: https://github.com/luizcg/ruact/releases/tag/v0.0.9
+[0.0.8]: https://github.com/luizcg/ruact/releases/tag/v0.0.8
 [0.0.7]: https://github.com/luizcg/ruact/releases/tag/v0.0.7
 [0.0.6]: https://github.com/luizcg/ruact/releases/tag/v0.0.6

data/lib/generators/ruact/install/install_generator.rb CHANGED Viewed

@@ -12,7 +12,10 @@ module Ruact
     # Performs the following actions:
     # 1. Creates config/initializers/ruact.rb
     # 2. Injects `include Ruact::Controller` into ApplicationController
-    # 3. Injects the React root div into app/views/layouts/application.html.erb
+    # 3. Injects the React root div AND `ruact_js_assets` into
+    #    app/views/layouts/application.html.erb, so the app's own layout owns
+    #    the document (and its `<head>` — stylesheets, fonts, meta — reaches a
+    #    ruact page). See Ruact::Configuration#layout.
     # 4. Creates app/javascript/components/.keep
     # 5. Creates vite.config.js (or shows manual instructions if one exists)
     # 6. Creates package.json (react/react-dom/vite/@vitejs/plugin-react) so a
@@ -25,6 +28,10 @@ module Ruact
     #    verification commands in context by default (Story 15.1, FR105).
     # 9. Runs `npm install` so JavaScript dependencies are ready (FR101);
     #    skippable via --skip-npm.
+    # 10. With `--shadcn`: also emits the prerequisites shadcn's own CLI refuses
+    #    to initialize without (a Tailwind entry + a `tsconfig.json` import
+    #    alias), wires the `css` build process, and prints the two `npx shadcn`
+    #    commands it deliberately does not run.
     #
     # Story 14.2 (FR104) — the generator no longer writes a bootstrap entry into
     # the user's tree. ruact's React entry is served as the virtual module
@@ -48,8 +55,32 @@ module Ruact
                    default: false,
                    desc: "Skip running npm install (for CI or non-npm package managers)"
+      # Prepares the app for the `ruact:scaffold --shadcn` path. shadcn's own
+      # CLI refuses to initialize without BOTH Tailwind and a TypeScript import
+      # alias, and a ruact app has neither — it ships no Tailwind and no
+      # `tsconfig.json` at all. That left `--shadcn` scaffolding into an app
+      # where the generated components' classes resolved to nothing: markup with
+      # no styling. This flag emits exactly the prerequisites (verified against
+      # the real shadcn CLI) and then PRINTS the two `npx shadcn` commands
+      # rather than running them — they hit the network and `shadcn init` is
+      # interactive, so automating them is neither safe nor possible.
+      class_option :shadcn,
+                   type: :boolean,
+                   default: false,
+                   desc: "Also wire Tailwind + a TS import alias, the prerequisites for `ruact:scaffold --shadcn`"
+      # A fresh app gets the whole initializer. An app that ALREADY has one gets
+      # a surgical injection instead of `template`'s overwrite prompt, which
+      # offered a bad choice on the one path that matters most — migrating an
+      # existing app: overwrite and lose every setting the app had
+      # (`strict_serialization`, `manifest_path`, the SGID defaults…), or skip
+      # and end up half-migrated, with the layout edited but `config.layout`
+      # still off and nothing saying so except `ruact:doctor`.
       def create_initializer
-        template "initializer.rb.tt", "config/initializers/ruact.rb"
+        path = Pathname(destination_root).join("config/initializers/ruact.rb")
+        return template "initializer.rb.tt", "config/initializers/ruact.rb" unless path.exist?
+        inject_layout_setting(path)
       end
       def inject_controller_concern
@@ -67,21 +98,93 @@ module Ruact
                          after: /class ApplicationController.*\n/
       end
+      # The layout owns the document: `stylesheet_link_tag`, favicons, fonts and
+      # every `<head>`-writing gem only reach a ruact page because Rails' own
+      # layout renders it (see `Ruact::Configuration#layout`). That requires TWO
+      # things in the layout — the React root, and `ruact_js_assets` to emit the
+      # bootstrap entry + this render's Flight payload. The other half of the
+      # opt-in is `config.layout = true`, which the generated initializer
+      # carries — a layout with the helper but the setting off (or the reverse)
+      # keeps rendering through ruact's built-in, CSS-less shell.
       def inject_layout_shell
         layout_file = "app/views/layouts/application.html.erb"
         return unless File.exist?(Pathname(destination_root).join(layout_file))
         content = File.read(Pathname(destination_root).join(layout_file))
-        if content.include?("ruact: root")
-          say_status "skip", "Rails RSC root already present in layout", :yellow
+        # A CALL, not a mention: `<%# TODO: add ruact_js_assets %>` used to read
+        # as "already present" here and skip the migration, leaving the app on
+        # ruact's CSS-less shell with the generator reporting success. Shared
+        # with the runtime so both agree on what "migrated" means.
+        # BOTH halves, not just the helper. A layout carrying `ruact_js_assets`
+        # with no `<div id="root"></div>` was skipped as "already present" — and
+        # since this generator also turns `config.layout` on, that app then
+        # raised at render time on a document React could not mount into.
+        if Ruact::LayoutSource.wired?(content) && Ruact::LayoutSource.root?(content)
+          say_status "skip", "ruact root + assets already present in layout", :yellow
           return
         end
+        # Migration path for an app installed before the layout owned the
+        # document: the root is already there, only the asset call is missing.
+        #
+        # The anchor matches the ROOT DIV itself rather than the marker-then-div
+        # pair, and tolerates the ways a real layout is written — single or
+        # double quotes, extra attributes, any attribute order, CRLF, and the
+        # marker on the same line. The earlier anchor required the exact emitted
+        # formatting, so a hand-edited layout silently matched nothing. The
+        # attribute boundary in `ROOT_ELEMENT` is what keeps `data-id="root"`
+        # from being mistaken for the mount point.
+        if Ruact::LayoutSource.root?(content)
+          return migrate_layout(layout_file,
+                                "\n    <%= ruact_js_assets %>",
+                                after: Ruact::LayoutSource::ROOT_ELEMENT,
+                                success: "added ruact_js_assets to the existing layout root")
+        end
+        # The mirror case: the helper is there but the mount target is not, so
+        # the root goes in just BEFORE the call (React needs the node in the
+        # document, and keeping the pair adjacent matches what a fresh install
+        # writes). Injecting the whole block instead would duplicate the helper.
+        if Ruact::LayoutSource.wired?(content)
+          return migrate_layout(layout_file,
+                                "<%# ruact: root %>\n    <div id=\"root\"></div>\n    ",
+                                before: Ruact::LayoutSource::ASSETS_CALL,
+                                success: "added the React root div next to the existing ruact_js_assets")
+        end
         inject_into_file layout_file,
-                         "\n    <%# ruact: root %>\n    <div id=\"root\"></div>\n",
+                         "\n    <%# ruact: root %>\n    <div id=\"root\"></div>\n    <%= ruact_js_assets %>\n",
                          before: "  </body>"
       end
+      # `--shadcn` only. Two files, both of them things shadcn's CLI checks for
+      # and refuses to proceed without ("No Tailwind CSS configuration found" /
+      # "Could not find valid path aliases"), verified against shadcn 4.x:
+      #
+      #   app/javascript/styles/globals.css — the Tailwind entry. shadcn appends
+      #     its design tokens here, which is why components.json points at it.
+      #   tsconfig.json — the `@/*` → `app/javascript/*` alias. The Vite plugin
+      #     already registers the same alias for the BUNDLER, so components
+      #     resolve at runtime today; this is what makes it resolve for
+      #     TypeScript (and therefore for shadcn's alias probe and your editor).
+      #
+      # Both are guarded: an app that already has them keeps its own.
+      def create_shadcn_prerequisites
+        return unless shadcn?
+        create_guarded_file "app/javascript/styles/globals.css", "globals.css.tt"
+        create_guarded_file "tsconfig.json", "tsconfig.json.tt"
+        # Propshaft only serves directories that exist; the built stylesheet is
+        # generated, so the directory ships with a .keep and the artifact is
+        # gitignored (see append_gitignore_entries).
+        empty_directory "app/assets/builds"
+        create_file "app/assets/builds/.keep" unless
+          File.exist?(Pathname(destination_root).join("app/assets/builds/.keep"))
+        warn_unless_layout_links_builds
+      end
       def create_components_directory
         empty_directory "app/javascript/components"
         create_file "app/javascript/components/.keep" unless
@@ -106,6 +209,10 @@ module Ruact
           "app/javascript/.ruact/server-functions.ts",
           "tmp/cache/ruact/"
         ]
+        # The compiled stylesheet is a build artifact of globals.css, rebuilt by
+        # the Procfile's `css` process on every boot — same reasoning as the
+        # generated server-functions module above.
+        entries << "app/assets/builds/tailwind.css" if shadcn?
         # Substring matches (`existing.include?(entry)`) were unsafe — they
         # would skip "tmp/cache/ruact/" when the file already contained
         # "tmp/cache/ruact/some-cache.bin", leaving the directory itself
@@ -291,6 +398,8 @@ module Ruact
           say "  2. Start your app:           bin/dev"
         end
+        show_shadcn_next_steps if shadcn?
         say "\nThen add <MyComponent /> to any ERB view.\n"
         say "Note: re-run this generator after updating the ruact gem to refresh"
         say "the bundled Vite plugin path in vite.config.js."
@@ -299,6 +408,96 @@ module Ruact
       private
+      # `inject_into_file` prints "File unchanged!" and carries on when its
+      # anchor misses, so reporting success without checking would be a lie —
+      # and the app would keep rendering through ruact's CSS-less shell with no
+      # clue why. Compare the file around the call and only claim what happened.
+      def migrate_layout(layout_file, content, success:, **anchor)
+        path   = Pathname(destination_root).join(layout_file)
+        before = path.read
+        inject_into_file layout_file, content, **anchor
+        if path.read == before
+          warn_layout_migration_failed
+        else
+          say_status "update", success, :green
+        end
+      end
+      def inject_layout_setting(path)
+        content = path.read
+        if content.match?(/^\s*config\.layout\s*=/)
+          say_status "skip", "config.layout already set in config/initializers/ruact.rb", :yellow
+          return
+        end
+        unless content.match?(/Ruact\.configure\s+do\s*\|(\w+)\|/)
+          warn_initializer_not_injectable
+          return
+        end
+        inject_into_file "config/initializers/ruact.rb",
+                         LAYOUT_SETTING_SNIPPET,
+                         after: /Ruact\.configure\s+do\s*\|\w+\|\n/
+        say_status "update", "set config.layout = true (your layout renders ruact pages)", :green
+      end
+      # The compiled stylesheet still has to be REQUESTED. Rails 8's default
+      # layout links `stylesheet_link_tag :app`, which Propshaft expands over
+      # every stylesheet on the load path — so `app/assets/builds/tailwind.css`
+      # is picked up with no further wiring (verified against a generated app:
+      # the rendered `<head>` carries `/assets/tailwind-<digest>.css`).
+      #
+      # A layout that instead links stylesheets BY NAME never asks for it, and
+      # the failure is silent: Tailwind builds fine, Propshaft serves it fine,
+      # and the page is simply unstyled. Warn rather than edit — which
+      # stylesheets a layout links is the app's business.
+      def warn_unless_layout_links_builds
+        layout_path = Pathname(destination_root).join("app/views/layouts/application.html.erb")
+        return unless layout_path.exist?
+        content = layout_path.read
+        return unless content.include?("stylesheet_link_tag")
+        return if content.match?(/stylesheet_link_tag\s+:app\b/) || content.include?("tailwind")
+        say_status "notice", "your layout links stylesheets by name — add the built one:", :yellow
+        say ""
+        say "      <%= stylesheet_link_tag \"tailwind\" %>"
+        say ""
+        say "  `stylesheet_link_tag :app` (the Rails 8 default) would pick up"
+        say "  app/assets/builds/tailwind.css on its own; a named link does not,"
+        say "  and the page would render unstyled with no error."
+        say ""
+      end
+      # The generator does NOT run these: `shadcn init` is interactive (it
+      # prompts for a component library and a preset) and both commands hit the
+      # network. What it CAN do is spell them exactly, which is the part nobody
+      # guesses: current shadcn defaults to **Base UI**, while ruact's generated
+      # components import **Radix** primitives — accepting the default gives you
+      # a component library the scaffold cannot use. Hence the explicit
+      # `--base radix`.
+      #
+      # The component list is ruact's own authoritative set
+      # (ScaffoldGenerator#required_shadcn_components), derived from the
+      # templates' imports, so the two generators cannot drift.
+      def show_shadcn_next_steps
+        say ""
+        say "shadcn prerequisites are in place (Tailwind entry, tsconfig alias, css process)."
+        say "Two commands remain — they are interactive and hit the network, so run them yourself:"
+        say ""
+        say "  npx shadcn@latest init --base radix"
+        say "  npx shadcn@latest add #{shadcn_add_list}"
+        say ""
+        say "  (--base radix matters: shadcn now defaults to Base UI, but the components"
+        say "   `ruact:scaffold --shadcn` generates import Radix primitives.)"
+        say "  (init also asks you to pick a style preset — any of them works.)"
+        say ""
+        say "Then scaffold a resource:"
+        say "  bin/rails generate ruact:scaffold Post title:string body:text --shadcn"
+      end
       # Story 15.1 — the exact marker tokens delimiting the ruact-managed
       # section of AGENTS.md. For a prose file the only safe idempotency key is
       # an explicit marker pair (`append_gitignore_entries`-style exact-line
@@ -463,6 +662,66 @@ module Ruact
       # Story 14.6 — a valid, lowercase npm "name" for the generated package.json,
       # derived from the app directory. npm names must be lowercase and contain
       # only URL-safe characters; anything else collapses to a hyphen.
+      # Kept verbatim in step with the `initializer.rb.tt` template's own
+      # `config.layout` block, so a migrated app and a fresh one end up reading
+      # the same thing.
+      LAYOUT_SETTING_SNIPPET = <<~RUBY
+        # Render ruact pages through this app's own layout, so the document `<head>`
+        # is yours: stylesheets, favicons, fonts and any gem that writes into
+        # `<head>` reach a ruact page. Requires the layout to call
+        # `<%= ruact_js_assets %>` (this generator adds it next to the React root).
+        config.layout = true
+      RUBY
+      private_constant :LAYOUT_SETTING_SNIPPET
+      # The initializer exists but is not the shape we know how to edit (someone
+      # rewrote it, or wrapped the configure call). Never guess at it — say what
+      # to add, so the app cannot end up half-migrated in silence.
+      def warn_initializer_not_injectable
+        say_status "skip", "could not find the Ruact.configure block to update", :red
+        say ""
+        say "  Add this line inside `Ruact.configure` in config/initializers/ruact.rb:"
+        say ""
+        say "      config.layout = true"
+        say ""
+        say "  Without it ruact keeps using its built-in shell, which carries no"
+        say "  stylesheet — your app's CSS will not reach a ruact-rendered page."
+        say ""
+      end
+      def shadcn?
+        options[:shadcn]
+      end
+      # Printed when the layout carries the ruact marker but the anchor found no
+      # root div to inject after. Silence would be the dangerous outcome: the app
+      # keeps rendering through ruact's CSS-less built-in shell, and nothing ever
+      # says why.
+      def warn_layout_migration_failed
+        say_status "skip", "could not locate the React root div in the layout", :red
+        say ""
+        say "  ruact could not add `ruact_js_assets` automatically. Add it by hand,"
+        say "  just after the root div in app/views/layouts/application.html.erb:"
+        say ""
+        say "      <div id=\"root\"></div>"
+        say "      <%= ruact_js_assets %>"
+        say ""
+        say "  Without it your app's CSS cannot reach a ruact-rendered page."
+        say ""
+      end
+      # The superset the scaffold generator narrows per resource. Loaded lazily
+      # (and only under `--shadcn`) so a plain install never pays for the
+      # scaffold generator's load, and so a failure to reach it degrades to the
+      # literal list rather than aborting an otherwise-successful install.
+      def shadcn_add_list
+        require_relative "../scaffold/scaffold_shadcn_preflight"
+        ScaffoldGenerator::ShadcnPreflight::ALL_SHADCN_COMPONENTS.join(" ")
+      rescue StandardError
+        "button input textarea switch select label badge table alert-dialog dropdown-menu"
+      end
       def app_package_name
         base = File.basename(File.expand_path(destination_root))
         sanitized = base.downcase.gsub(/[^a-z0-9._-]/, "-").squeeze("-").gsub(/\A-+|-+\z/, "")

data/lib/generators/ruact/install/templates/Procfile.dev.tt CHANGED Viewed

@@ -1,2 +1,5 @@
 web: bin/rails server -p 3000
 vite: npm run dev
+<% if shadcn? -%>
+css: npx @tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --watch
+<% end -%>

data/lib/generators/ruact/install/templates/globals.css.tt ADDED Viewed

@@ -0,0 +1,20 @@
+/* Tailwind entry — the SOURCE, not the asset the browser gets.
+ *
+ * Built into app/assets/builds/tailwind.css by the `css` process in
+ * Procfile.dev, which Propshaft then serves and the layout links:
+ *
+ *   this file ──build──> app/assets/builds/tailwind.css
+ *             ──Propshaft──> /assets/tailwind-<digest>.css
+ *             ──stylesheet_link_tag in app/views/layouts──> the page
+ *
+ * `npx shadcn init` appends its design tokens (the CSS variables the
+ * components reference by name) below this import — that is why
+ * components.json points its `tailwind.css` at this file.
+ */
+@import "tailwindcss";
+/* Tailwind v4 declares its class scan here instead of in a config file.
+   Components carry most of the classes; the ERB views carry the page-level
+   ones, so both paths are needed. */
+@source "../components";
+@source "../../views";

data/lib/generators/ruact/install/templates/initializer.rb.tt CHANGED Viewed

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 Ruact.configure do |config|
+  # Render ruact pages through your app's own layout, so the document `<head>`
+  # is yours: `stylesheet_link_tag`, favicons, fonts, analytics and any gem that
+  # writes into `<head>` all reach a ruact page. Requires the layout to call
+  # `<%%= ruact_js_assets %>` (this generator adds it next to the React root).
+  #
+  # Set to false to use ruact's built-in minimal shell instead — it has no
+  # stylesheet slot, so your app's CSS will NOT reach a ruact-rendered page.
+  config.layout = true
   # Path to the react-client-manifest.json generated by the Vite plugin.
   # Defaults to Rails.root.join("public/react-client-manifest.json").
   # config.manifest_path = Rails.root.join("public", "react-client-manifest.json")

data/lib/generators/ruact/install/templates/package.json.tt CHANGED Viewed

@@ -4,7 +4,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build"
+    "build": "vite build"<% if shadcn? %>,
+    "build:css": "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"<% end %>
   },
   "dependencies": {
     "react": "^19.0.0",
@@ -12,6 +13,11 @@
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.4",
+<% if shadcn? -%>
+    "@tailwindcss/cli": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "tw-animate-css": "^1.0.0",
+<% end -%>
     "vite": "^6.0.7"
   }
 }

data/lib/generators/ruact/install/templates/tsconfig.json.tt ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["app/javascript/*"]
+    }
+  },
+  "include": ["app/javascript/**/*.ts", "app/javascript/**/*.tsx"]
+}

data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb CHANGED Viewed

@@ -47,6 +47,16 @@ module Ruact
         # List/DeleteDialog primitives. EVERY entry is a plain `npx shadcn add`
         # primitive — there is NO `data-table` recipe and NO `@tanstack/react-table`
         # dependency (Story 10.2b removed the engine; the List is a plain `table`).
+        # The COMPLETE primitive set — the union of everything any generated
+        # resource can import. `#required_shadcn_components` NARROWS this per
+        # resource (the input-family entries depend on the attribute types),
+        # but `ruact:install --shadcn` runs before any resource exists, so it
+        # prints this superset. A spec pins the narrowed list as a subset of
+        # this one, so the two cannot drift apart.
+        ALL_SHADCN_COMPONENTS = %w[
+          button input textarea switch select label badge table alert-dialog dropdown-menu
+        ].freeze
         def required_shadcn_components
           components = ["button"]
           components << "input"    if form_uses_input?

data/lib/ruact/configuration.rb CHANGED Viewed

@@ -24,6 +24,7 @@ module Ruact
       signed_global_id_default_purpose
       signed_global_id_default_expires_in
       shadcn_compatible_versions
+      layout
     ].freeze
     # @!attribute [r] manifest_path
@@ -135,6 +136,47 @@ module Ruact
     #     suppress the warning — the documented "override" path.
     #   @example Allow shadcn v3 once you have verified it
     #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3] }
+    #
+    # @!attribute [r] layout
+    #   @return [Boolean, String] Which document wrapper a ruact page's HTML
+    #     response is rendered into. The Flight response shape
+    #     (`text/x-component`) is never affected — this is only about the
+    #     full-document render a browser gets on a normal navigation.
+    #
+    #     - `false` (default) — render the gem's built-in minimal shell.
+    #     - `true` — render through the controller's normal Rails layout.
+    #     - a String — render through that named layout (e.g. `"ruact"`).
+    #
+    #     The layout path exists because the document `<head>` belongs to the
+    #     host app: `stylesheet_link_tag`, favicons, fonts, analytics and any
+    #     `<head>`-writing gem only reach the page when Rails' own layout owns
+    #     the document. The built-in shell carries no stylesheet slot, so under
+    #     the `false` default a ruact page renders with no app CSS at all —
+    #     which is why `rails generate ruact:install` writes `config.layout =
+    #     true` into the generated initializer and adds `<%= ruact_js_assets %>`
+    #     to your layout in the same run.
+    #
+    #     **This setting is deliberately explicit — there is no auto-detection.**
+    #     ruact used to try to infer whether your layout was ready by inspecting
+    #     it. Deciding that reliably means answering "does this template call
+    #     this method?", which cannot be done by pattern-matching a template
+    #     language: three review rounds each found another shape that fooled it
+    #     (a mention in a comment, a commented-out call, a trim-mode comment),
+    #     and each wrong answer governed how every page in the app rendered.
+    #     One explicit line is worth more than a clever guess here.
+    #
+    #     A layout is ready when it calls `<%= ruact_js_assets %>` (which emits
+    #     the React root's bootstrap entry tags and the per-render Flight
+    #     payload) next to a `<div id="root"></div>`. If it does not, ruact says
+    #     so loudly in development rather than serving a blank page, and
+    #     `rails ruact:doctor` reports it.
+    #   @note A ruact view is rendered in its own pass (it produces the component
+    #     tree), so `content_for` declared inside the view does NOT reach the
+    #     layout. Set document metadata from the controller instead.
+    #   @example Let your layout own the document (what ruact:install writes)
+    #     Ruact.configure { |c| c.layout = true }
+    #   @example Use a dedicated layout for ruact pages only
+    #     Ruact.configure { |c| c.layout = "ruact" }
     ATTRIBUTES.each do |attr|
       attr_reader attr
@@ -188,6 +230,7 @@ module Ruact
         @signed_global_id_default_purpose = nil
         @signed_global_id_default_expires_in = nil
         @shadcn_compatible_versions = [1, 2]
+        @layout = false
       end
     end
@@ -249,7 +292,37 @@ module Ruact
       when :query_route_prefix      then validate_query_route_prefix!(value)
       when :query_parent_controller then validate_query_parent_controller!(value)
       when :shadcn_compatible_versions then validate_shadcn_compatible_versions!(value)
+      when :layout                     then validate_layout!(value)
+      end
+    end
+    # The value selects a render strategy by identity (`true` / `false`) or
+    # names a layout (String). Anything else would otherwise be treated as "not
+    # false" and reach `render_to_string(layout: <value>)`, where a Symbol
+    # layout name or a stray nil surfaces as a confusing first-request 500
+    # instead of a boot-time error. `nil` is rejected on purpose: "no layout" is
+    # spelled `false`, so a nil left over from a conditional in the initializer
+    # is a mistake, not a silent shell fallback.
+    def validate_layout!(value)
+      return if [true, false].include?(value)
+      return if value.is_a?(String) && !value.empty?
+      # `:auto` is rejected BY NAME because it used to be the default. An app
+      # carrying it forward from an older initializer must be told it is gone,
+      # not have it silently reinterpreted as "some truthy value".
+      if value == :auto
+        raise Ruact::ConfigurationError,
+              "Ruact::Configuration#layout no longer supports :auto — it inferred whether your " \
+              "layout was ready by inspecting it, which could not be done reliably. " \
+              "Set `true` to render through your app's layout (make sure it calls " \
+              "`<%= ruact_js_assets %>`), or `false` for ruact's built-in shell."
       end
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#layout must be true, false, or a non-empty String layout name; " \
+            "got #{value.inspect} (#{value.class.name}). " \
+            "true renders through your app's layout (which must call ruact_js_assets); " \
+            "false uses ruact's built-in shell."
     end
     def validate_max_upload_bytes!(value)