ruact 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 962dae09686957b84e9e34d12809714978e95e6392265b7fd7f64a7028dd86f5
-  data.tar.gz: ecad09e13bcc52fe30bff4ece70e14527e0c501166d2d487625c9a92ada3a2fd
+  metadata.gz: '048ef204d79fa3c03ff9ab08c43e5d9d1fc1f42c0e92c7cf7311b510bc879b0a'
+  data.tar.gz: 67fdef7b25ac3ac2ea552eed361a45a62710bf28145ae7892d0e1f46f462aa47
 SHA512:
-  metadata.gz: 87a00a254896d68831e62bb892932c29b0668628232757f692b22c00f1a188de0db7d2ba9600e199e6f46aa1997b73ebe7fed0e6ef193a6d4b060b7fc410b2cf
-  data.tar.gz: f90d5ba0da42e90e7031cff6d93ce648229655a5eea726a8572664354291aa974254f5696596a339942dedf7630506292618c48323a70cf7302c247eae7cb6b3
+  metadata.gz: cd6d63eaaa47a7cde090700c44ba53fe8cf9b29d82cc05ce2f672b98b01dd83dd82cb046b109cd47a328594344b1950f21d75fee5338870a0df5be438e86843e
+  data.tar.gz: 44b2880d6879617b00adc9a8ae070a1f722e147a782592c4b527e98dbe9af42d925f45c68daca3272df28a95c7a0c89d762164bf205c9da2dbf195e142e8e88d

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.14] - 2026-10-02
+
+### Fixed
+
+- **Scaffolding a second resource stopped the app from booting.** Every `rails generate ruact:scaffold` wrote a query with a method named `search`. Query names share one namespace: each name gets one `GET /q/<name>` route and one export of `@/.ruact/server-functions`. So the second resource drew `ruact_query_search` again, and Rails refused to load the routes with "Invalid route name, already in use: 'ruact_query_search'", a route the app never wrote. The scaffold now names the method after the resource: `PostsQuery#search_posts`, served at `GET /q/searchPosts` and imported as `searchPosts`. Two query classes that define the same method — or one query class mounted twice — now raise `Ruact::ConfigurationError` naming the query, the path and the fix. The new name can meet one thing the bare `search` could not: a custom collection action named `search` on the same controller (`post :search, on: :collection`) also derives `searchPosts`, and boot stops with ruact's name-collision error, which points to `ruact_function_name` to rename one. Apps scaffolded before this release keep their `search` and work as they are. The first scaffold of a *new* resource in such an app no longer collides with it.
+
+- **`rails generate ruact:install --shadcn` on an app that already had ruact installed left Tailwind out, then said the setup was in place.** That is the order Getting Started gives: install ruact first, add shadcn later. On the second run `package.json` and `Procfile.dev` already existed, so the generator skipped both. Tailwind was never declared and the `css` process was never added. `npx shadcn@latest init` then stopped with "No Tailwind CSS configuration found", right after the generator had printed that the prerequisites were in place. Under `--shadcn` the generator now adds what is missing to both files: the Tailwind `devDependencies` and the `build:css` script in `package.json`, the `css` process in `Procfile.dev`. It keeps every version and script you already declare; `package.json` is rewritten as 2-space JSON when something is added. When it cannot complete the setup, it says the setup is not in place and names what to do: a `package.json` it cannot parse, a Tailwind older than 4, or a `Procfile.dev` that already runs a `css` process or another Tailwind watcher — such as tailwindcss-rails' `bin/rails tailwindcss:watch`, which compiles its own entry rather than the `globals.css` shadcn writes its theme into. Without `--force`, `rails destroy ruact:install --shadcn` leaves an existing `package.json` in place.
+
+- **Under `--shadcn`, `bin/dev` stopped as soon as it started when no terminal was attached.** The `css` process ran `@tailwindcss/cli --watch`, which stops watching and exits 0 when its input closes. Foreman then stops Rails and Vite as well. A coding agent, CI, Docker or an IDE task runner starts `bin/dev` without a terminal, so the app was gone before its first request, with no error in the output. The process now runs with `--watch=always`. To fix an app generated before this release, change `--watch` to `--watch=always` on the `css:` line of `Procfile.dev`.
+
+- **The `ruact:scaffold --shadcn` pre-flight printed `npx shadcn@latest init` without `--base radix`.** The current shadcn defaults to Base UI, but the components the scaffold generates import Radix. An app set up from that message got components whose imports do not resolve. The message now prints `--base radix`, as the install generator already did.
+
+- **Two generator messages linked to pages that do not exist.** The unknown-attribute-type error and the shadcn version warning pointed at a documentation path inside this repository, where no such file exists. They now link to ruact.dev.
+
+### Changed
+
+- **The scaffold's list prop is named after the resource.** `<CommentList posts={rows} />` was a leftover from the reference app the templates came from, and every resource got a `posts` prop. It is now `<CommentList comments={rows} />`, `<BlogPostList blogPosts={rows} />`, and so on. Inside the component the prop is bound to a fixed local, so a model whose plural is one of the List's own names (`Row`) or one a module cannot declare (`Argument`) still compiles. A `Post` scaffold's view is unchanged.
+
+- **shadcn 4 is in the default `shadcn_compatible_versions`** (now `[1, 2, 4]`). It is the current major, so every app that followed the setup steps saw `ruact:scaffold --shadcn` warn that its shadcn was not tested. shadcn 4 was run end to end with this release: `init --base radix`, the full `add` list, `ruact:scaffold --shadcn`, and the form, table and delete dialog checked in a browser.
+
 ## [0.0.13] - 2026-09-27
 
 ### Added
@@ -356,7 +376,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.13...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.14...HEAD
+[0.0.14]: https://github.com/luizcg/ruact/releases/tag/v0.0.14
 [0.0.13]: https://github.com/luizcg/ruact/releases/tag/v0.0.13
 [0.0.12]: https://github.com/luizcg/ruact/releases/tag/v0.0.12
 [0.0.11]: https://github.com/luizcg/ruact/releases/tag/v0.0.11

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

@@ -152,6 +152,24 @@ module Ruact
         say ""
       end
 
+      # What `--shadcn` adds to package.json and Procfile.dev. One source for the
+      # templates (fresh install) and the merge below (an app that already has
+      # both files), so the two paths cannot drift.
+      SHADCN_DEV_DEPENDENCIES = {
+        "@tailwindcss/cli" => "^4.0.0",
+        "tailwindcss" => "^4.0.0",
+        "tw-animate-css" => "^1.0.0"
+      }.freeze
+      SHADCN_BUILD_CSS_SCRIPT =
+        "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"
+      # `--watch=always`, not `--watch`: Tailwind stops watching when stdin
+      # closes, and it does exit 0, so foreman then stops Rails and Vite with it.
+      # stdin is closed whenever bin/dev runs without a terminal (a coding agent,
+      # CI, Docker, an IDE task runner), which made the whole app go down in silence.
+      SHADCN_CSS_PROCESS =
+        "css: npx @tailwindcss/cli -i app/javascript/styles/globals.css " \
+        "-o app/assets/builds/tailwind.css --watch=always"
+
       # `--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:
@@ -256,10 +274,18 @@ module Ruact
       # imports it by the absolute `Ruact.vite_plugin_path` and it uses only
       # `node:` builtins. Guarded like vite.config.js: an existing package.json
       # is left untouched (the app may already have one) unless --force.
+      #
+      # Under `--shadcn` an existing package.json is not skipped but COMPLETED:
+      # adding shadcn to an app that already ran the install is the documented
+      # path (Getting Started step 7 onward), and skipping here left Tailwind
+      # undeclared, so `shadcn init` aborted with "No Tailwind CSS configuration
+      # found" right after this generator said the prerequisites were in place.
       def create_package_json
         package_json_file = Pathname(destination_root).join("package.json")
 
         if package_json_file.exist? && !options[:force]
+          return merge_shadcn_package_json(package_json_file) if shadcn?
+
           say_status "skip", "package.json already exists — ensure it has react, react-dom, " \
                              "vite and @vitejs/plugin-react (re-run with --force to overwrite)", :yellow
           return
@@ -279,7 +305,12 @@ module Ruact
       # OWNED by ruact: see `install_foreman_launcher`. `bin/dev` is made
       # executable.
       def create_launch_files
-        create_guarded_file "Procfile.dev", "Procfile.dev.tt"
+        procfile = Pathname(destination_root).join("Procfile.dev")
+        if procfile.exist? && !options[:force] && shadcn?
+          append_shadcn_css_process(procfile)
+        else
+          create_guarded_file "Procfile.dev", "Procfile.dev.tt"
+        end
         install_foreman_launcher
         # Ensure bin/dev is executable whether we just wrote it or it pre-existed
         # (a skipped, already-foreman launcher should still be runnable).
@@ -612,7 +643,13 @@ module Ruact
       # 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)."
+        if shadcn_gaps.empty?
+          say "shadcn prerequisites are in place (Tailwind entry, tsconfig alias, css process)."
+        else
+          say_status "attention", "shadcn prerequisites are NOT all in place:", :red
+          shadcn_gaps.each { |gap| say "  - #{gap}" }
+          say "Fix these first, then run the two commands below."
+        end
         say "Two commands remain — they are interactive and hit the network, so run them yourself:"
         say ""
         say "  npx shadcn@latest init --base radix"
@@ -890,6 +927,12 @@ module Ruact
         options[:shadcn]
       end
 
+      # Prerequisites `--shadcn` could not put in place. Non-empty means
+      # show_shadcn_next_steps must not say "in place".
+      def shadcn_gaps
+        @shadcn_gaps ||= []
+      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
@@ -901,6 +944,74 @@ module Ruact
         "button input textarea switch select label badge table alert-dialog dropdown-menu"
       end
 
+      # Adds the shadcn devDependencies and the build:css script to an existing
+      # package.json. Never overwrites a key the app already has (its own
+      # Tailwind version wins). The file is re-serialized with 2-space JSON
+      # when something is added. An unparseable file is left alone, loudly.
+      def merge_shadcn_package_json(path)
+        # `create_file … force: true` would DELETE the whole file under
+        # `rails destroy`; this merge has nothing to undo.
+        return if behavior == :revoke
+
+        pkg = JSON.parse(path.read.delete_prefix("\uFEFF"))
+        raise JSON::ParserError, "top level is #{pkg.class}, not an object" unless pkg.is_a?(Hash)
+
+        dev = (pkg["devDependencies"] ||= {})
+        scripts = (pkg["scripts"] ||= {})
+        flag_tailwind_below_v4(dev["tailwindcss"] || pkg.dig("dependencies", "tailwindcss"))
+        added = SHADCN_DEV_DEPENDENCIES.reject { |name, _| dev.key?(name) || pkg.dig("dependencies", name) }
+        dev.merge!(added)
+        add_script = !scripts.key?("build:css")
+        scripts["build:css"] = SHADCN_BUILD_CSS_SCRIPT if add_script
+
+        if added.empty? && !add_script
+          say_status "identical", "package.json (Tailwind already declared)", :blue
+          return
+        end
+
+        create_file "package.json", "#{JSON.pretty_generate(pkg)}\n", force: true, verbose: false
+        say_status "update", "package.json (+ #{(added.keys + (add_script ? ['build:css'] : [])).join(', ')})", :green
+      rescue JSON::ParserError => e
+        shadcn_gaps << "package.json could not be parsed (#{e.message.lines.first.strip}) — add " \
+                       "#{SHADCN_DEV_DEPENDENCIES.keys.join(', ')} to devDependencies and a " \
+                       "\"build:css\" script (#{SHADCN_BUILD_CSS_SCRIPT}) yourself"
+      end
+
+      # globals.css is written for Tailwind 4 (`@import "tailwindcss"`). An app
+      # pinned to an older major keeps its version, and the setup is not in place.
+      def flag_tailwind_below_v4(version)
+        major = version.to_s[/\d+/]
+        return if major.nil? || major.to_i >= 4
+
+        shadcn_gaps << "package.json pins tailwindcss #{version}; app/javascript/styles/globals.css " \
+                       "and shadcn's current components need Tailwind 4"
+      end
+
+      # Appends the Tailwind watch process to an existing Procfile.dev, unless a
+      # process already builds globals.css. A different `css:` process, or
+      # another Tailwind watcher (tailwindcss-rails' compiles its own entry into
+      # the same app/assets/builds/tailwind.css), cannot be appended next to: it
+      # is reported as a gap, never silently accepted. Comment lines are ignored.
+      def append_shadcn_css_process(path)
+        content = path.read
+        code = content.lines.reject { |line| line.lstrip.start_with?("#") }
+
+        if code.any? { |line| line.include?("app/javascript/styles/globals.css") }
+          say_status "identical", "Procfile.dev (already builds globals.css)", :blue
+          return
+        end
+
+        if (clash = code.find { |line| line.match?(/\A\s*css\s*:/) || line.include?("tailwind") })
+          shadcn_gaps << "Procfile.dev already runs `#{clash.strip}`, which does not build " \
+                         "app/javascript/styles/globals.css — replace it with: #{SHADCN_CSS_PROCESS}"
+          return
+        end
+
+        separator = content.empty? || content.end_with?("\n") ? "" : "\n"
+        append_to_file "Procfile.dev", "#{separator}#{SHADCN_CSS_PROCESS}\n", verbose: false
+        say_status "update", "Procfile.dev (+ css process)", :green
+      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

@@ -1,5 +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
+<%= SHADCN_CSS_PROCESS %>
 <% end -%>

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

@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build"<% if shadcn? %>,
-    "build:css": "@tailwindcss/cli -i app/javascript/styles/globals.css -o app/assets/builds/tailwind.css --minify"<% end %>
+    "build:css": "<%= SHADCN_BUILD_CSS_SCRIPT %>"<% end %>
   },
   "dependencies": {
     "react": "^19.0.0",
@@ -14,9 +14,9 @@
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.4",
 <% if shadcn? -%>
-    "@tailwindcss/cli": "^4.0.0",
-    "tailwindcss": "^4.0.0",
-    "tw-animate-css": "^1.0.0",
+<% SHADCN_DEV_DEPENDENCIES.each do |name, version| -%>
+    "<%= name %>": "<%= version %>",
+<% end -%>
 <% end -%>
     "vite": "^6.0.7"
   }

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

@@ -107,7 +107,7 @@ module Ruact
 
       SUPPORTED_TYPES = TYPE_MAP.keys.freeze
 
-      # Column types the `search` query's case-insensitive LIKE scope spans —
+      # Column types the search query's case-insensitive LIKE scope spans —
       # matching numeric/date/boolean columns by substring is meaningless.
       SEARCHABLE_COLUMN_TYPES = %w[string text].freeze
 
@@ -121,7 +121,7 @@ module Ruact
       REFERENCE_OPTIONS_LIMIT = 100
 
       # Documentation anchor referenced by the unknown-type error message (AC4).
-      DOCS_POINTER = "https://github.com/luizcg/ruact/blob/main/website/docs/api/scaffold.md#attribute-types"
+      DOCS_POINTER = "https://ruact.dev/docs/api/scaffold.html#attribute-types"
 
       # Story 10.5 (AC1, AC2, AC4) — the shadcn/ui dependency PRE-FLIGHT: detect
       # the host's shadcn state (complete / missing / partial) and either proceed
@@ -191,7 +191,7 @@ module Ruact
       end
 
       # AC5 — the client-driven read path. Emits the resource query
-      # (`<Plural>Query < ApplicationQuery` with a `search(q:)` method) in BOTH
+      # (`<Plural>Query < ApplicationQuery` with a `search_<plural>(q:)` method) in BOTH
       # `.tsx` and `.jsx` modes (the query is server-side Ruby; the language flag
       # only governs the React component). The `ApplicationQuery` base is created
       # idempotently — `ruact:install` does NOT ship it, and a second scaffold in
@@ -205,13 +205,13 @@ module Ruact
         template "queries/application_query.rb.tt", application_query
       end
 
-      # AC5 — mount the resource query so its `search` method becomes the named
-      # GET route the codegen exports as `search` (consumed by `useQuery`).
+      # AC5 — mount the resource query so its `search_<plural>` method becomes the
+      # named GET route the codegen exports as `search<Plural>` (consumed by `useQuery`).
       # Idempotent on re-run: guard on the drawn `ruact_queries <Plural>Query`
       # line first (sibling of {#add_resource_route}'s `resources :posts` guard).
       def add_query_route
         routes_file = Pathname(destination_root).join("config/routes.rb")
-        if routes_file.exist? && routes_file.read.match?(/^\s*ruact_queries\s+#{Regexp.escape(query_class_name)}\b/)
+        if routes_file.exist? && query_already_mounted?(routes_file.read)
           say_status "skip", "ruact_queries #{query_class_name} already routed", :yellow
           return
         end
@@ -406,17 +406,44 @@ module Ruact
 
         # The read-side query class — PLURAL, mirroring the golden `PostsQuery`
         # (file `posts_query.rb`) and Zeitwerk's path↔constant rule. Mounted via
-        # `ruact_queries <Plural>Query`; its `search` method becomes `GET /q/search`.
+        # `ruact_queries <Plural>Query`; its search method becomes `GET /q/searchPosts`.
         def query_class_name
           "#{class_name.pluralize}Query"
         end
 
-        # The JS import alias for the query's `search` accessor. The codegen
-        # exports a generic `search` (from `<Plural>Query#search`); the component
-        # aliases it `search<Plural>` to avoid a bare-`search` collision — exactly
-        # as the golden does (`search as searchPosts`).
+        # True when a `ruact_queries` line already lists this exact class —
+        # alone or among others, ignoring a trailing comment and not mistaking
+        # `Legacy::PostsQuery` or `BlogPostsQuery` for `PostsQuery`.
+        def query_already_mounted?(routes)
+          class_ref = /(?<![:\w])#{Regexp.escape(query_class_name)}\b/
+          routes.each_line.any? do |line|
+            code = line.sub(/#.*/, "")
+            code.match?(/\A\s*ruact_queries\b/) && code.match?(class_ref)
+          end
+        end
+
+        # The query's search method, named after the resource (`search_posts`).
+        # Query names share ONE namespace — one `GET /q/<name>` route and one
+        # export of `@/.ruact/server-functions` per name — so a bare `search`
+        # was free for the first resource and broke the boot on the second
+        # (`ruact_query_search` drawn twice).
+        def query_search_method
+          "search_#{plural_table_name}"
+        end
+
+        # The accessor the codegen exports for {#query_search_method}
+        # (`searchPosts`); the List imports it under this name, unaliased.
         def js_search_alias
-          "search#{class_name.pluralize}"
+          Ruact::ServerFunctions::NameBridge.to_js_identifier(query_search_method)
+        end
+
+        # The List's collection prop, named after the resource (`posts`,
+        # `comments`, `blogPosts`) rather than fixed to the golden's `posts`.
+        # The List binds it to a fixed local (`initialRows`), so a model whose
+        # plural matches one of the List's own names (`Row` → `rows`) or one a
+        # module cannot declare (`Argument` → `arguments`) still compiles.
+        def js_collection_prop
+          plural_table_name.camelize(:lower)
         end
 
         # The columns the search `LIKE` scope spans — string/text only (a

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

@@ -20,7 +20,7 @@ module Ruact
         # Documentation anchor for the shadcn dependency pre-flight: how to set
         # up shadcn, and how to override the version-compat warning.
         SHADCN_DOCS_POINTER =
-          "https://github.com/luizcg/ruact/blob/main/website/docs/api/scaffold.md#shadcnui-setup"
+          "https://ruact.dev/docs/guides/shadcn-ui.html#shadcn-versions"
 
         # The pre-flight body (the {ScaffoldGenerator#check_shadcn_setup} Thor
         # command delegates here). Detect the host's shadcn state, surface the
@@ -141,9 +141,10 @@ module Ruact
           <<~MSG.chomp
             ruact:scaffold — shadcn/ui is not set up in this app yet.
             The generated components import from @/components/ui/*, which does not exist.
-            Set up shadcn/ui first, then re-run this generator:
+            Set up shadcn/ui first (--base radix: the components import Radix primitives,
+            and shadcn now defaults to Base UI), then re-run this generator:
 
-              npx shadcn@latest init
+              npx shadcn@latest init --base radix
               #{shadcn_add_command(required_shadcn_components)}
 
             No files were written (no partial state). Advanced: pass --skip-shadcn-check

data/lib/generators/ruact/scaffold/templates/components/List.tsx.tt

@@ -16,7 +16,7 @@
 // small GENERATED client-side sort. There is NO table-engine dependency: the
 // scaffold stays dep-free (no react-table runtime), matching the dep-free
 // Form and the native date inputs. The collection arrives as a SERVER-RENDERED
-// prop (`posts`); there is no client query for the initial render. A query only
+// prop (`<%= js_collection_prop %>`); there is no client query for the initial render. A query only
 // enters when the *client* drives the read: the search box calls
 // useQuery(<%= js_search_alias %>, { q }) and swaps in filtered rows as you type.
 // Per-row delete drives a controlled <%= class_name %>DeleteDialog (DELETE
@@ -30,7 +30,7 @@
 // freshly scaffolded app will not resolve these until 10.5 lands; that is
 // expected (the end-to-end live demo is Story 10.7).
 import { useState } from "react";
-import { search as <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
+import { <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
 import { <%= class_name %>DeleteDialog } from "./<%= class_name %>DeleteDialog";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -52,11 +52,11 @@ import {
 
 type <%= class_name %>Row = { <%= ts_row_fields %> };
 
-// FR100 — opt-in call-site contract: `posts` is required. The index view passes
-// `<<%= class_name %>List posts={rows} />` (satisfied); a call site that omits it
+// FR100 — opt-in call-site contract: `<%= js_collection_prop %>` is required. The index view passes
+// `<<%= class_name %>List <%= js_collection_prop %>={rows} />` (satisfied); a call site that omits it
 // fails at preprocess time, not as a silent `undefined` in the browser.
 export const __ruactContract = {
-  props: { posts: "required" },
+  props: { <%= js_collection_prop %>: "required" },
 };
 <% end -%>
 
@@ -208,9 +208,9 @@ function RowActions({ record, onDeleted }<% if typescript? %>: {
 }
 
 export function <%= class_name %>List({
-  posts = [],
+  <%= js_collection_prop %>: initialRows = [],
   emptyLabel = "No <%= plural_name %> yet — create one.",
-}<% if typescript? %>: { posts?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
+}<% if typescript? %>: { <%= js_collection_prop %>?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
   const [q, setQ] = useState("");
   const searching = q.trim().length > 0;
 
@@ -229,7 +229,7 @@ export function <%= class_name %>List({
   // the box is idle and we fall back to the server-rendered rows.
   const { data: searchData, loading: searchLoading } = useQuery<% if typescript? %><<%= class_name %>Row[]><% end %>(<%= js_search_alias %>, { q: q.trim() });
 
-  const source = searching ? searchData ?? [] : posts;
+  const source = searching ? searchData ?? [] : initialRows;
   const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
   // Always sort a COPY — never mutate the prop/source array.
   const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;

data/lib/generators/ruact/scaffold/templates/components/agnostic/List.tsx.tt

@@ -8,7 +8,7 @@
 // <%= class_name %> list — a DESIGN-SYSTEM-AGNOSTIC table (Story 14.4 / FR103). The
 // default scaffold ships plain, native HTML elements styled by the browser /
 // Rails-default CSS — NO shadcn/ui, NO Tailwind, NO table-engine dependency. The
-// collection arrives as a SERVER-RENDERED prop (`posts`); there is no client query
+// collection arrives as a SERVER-RENDERED prop (`<%= js_collection_prop %>`); there is no client query
 // for the initial render. A query only enters when the *client* drives the read:
 // the search box calls useQuery(<%= js_search_alias %>, { q }) and swaps in filtered rows as
 // you type. Per-row delete drives a controlled <%= class_name %>DeleteDialog (DELETE
@@ -18,17 +18,17 @@
 // sort/pagination is Phase-3 territory. (The richer shadcn DataTable styling is
 // the opt-in `--shadcn` path — Story 14.5.)
 import { useState } from "react";
-import { search as <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
+import { <%= js_search_alias %>, destroy<%= class_name %>, useQuery } from "@/.ruact/server-functions";
 import { <%= class_name %>DeleteDialog } from "./<%= class_name %>DeleteDialog";
 <% if typescript? -%>
 
 type <%= class_name %>Row = { <%= ts_row_fields %> };
 
-// FR100 — opt-in call-site contract: `posts` is required. The index view passes
-// `<<%= class_name %>List posts={rows} />` (satisfied); a call site that omits it
+// FR100 — opt-in call-site contract: `<%= js_collection_prop %>` is required. The index view passes
+// `<<%= class_name %>List <%= js_collection_prop %>={rows} />` (satisfied); a call site that omits it
 // fails at preprocess time, not as a silent `undefined` in the browser.
 export const __ruactContract = {
-  props: { posts: "required" },
+  props: { <%= js_collection_prop %>: "required" },
 };
 <% end -%>
 
@@ -146,9 +146,9 @@ function RowActions({ record, onDeleted }<% if typescript? %>: {
 }
 
 export function <%= class_name %>List({
-  posts = [],
+  <%= js_collection_prop %>: initialRows = [],
   emptyLabel = "No <%= plural_name %> yet — create one.",
-}<% if typescript? %>: { posts?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
+}<% if typescript? %>: { <%= js_collection_prop %>?: <%= class_name %>Row[]; emptyLabel?: string }<% end %>) {
   const [q, setQ] = useState("");
   const searching = q.trim().length > 0;
 
@@ -167,7 +167,7 @@ export function <%= class_name %>List({
   // the box is idle and we fall back to the server-rendered rows.
   const { data: searchData, loading: searchLoading } = useQuery<% if typescript? %><<%= class_name %>Row[]><% end %>(<%= js_search_alias %>, { q: q.trim() });
 
-  const source = searching ? searchData ?? [] : posts;
+  const source = searching ? searchData ?? [] : initialRows;
   const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
   // Always sort a COPY — never mutate the prop/source array.
   const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;

data/lib/generators/ruact/scaffold/templates/queries/query.rb.tt

@@ -3,7 +3,7 @@
 # Read side of the CRUD. Each public instance method becomes one named GET
 # route when mounted with `ruact_queries <%= query_class_name %>`:
 #
-#   GET /q/search  → <%= query_class_name %>#search(q:)  → useQuery(<%= js_search_alias %>, { q })  (list search box)
+#   GET /q/<%= js_search_alias %>  → <%= query_class_name %>#<%= query_search_method %>(q:)  → useQuery(<%= js_search_alias %>, { q })  (list search box)
 #
 # NOTE: there is deliberately NO whole-list query — the index list is
 # server-rendered as props (see <%= controller_class_name %>Controller#index). A query is only the
@@ -14,7 +14,7 @@ class <%= query_class_name %> < ApplicationQuery
   # is what justifies a query — the result depends on live client input, not on
   # what the server already had. Rows are the SAME shape the index serializes, so
   # the search results and the server-rendered props are interchangeable.
-  def search(q:)
+  def <%= query_search_method %>(q:)
     term = q.to_s.strip
     scope =
 <% if searchable_attributes.empty? -%>

data/lib/generators/ruact/scaffold/templates/views/index.html.erb.tt

@@ -3,4 +3,4 @@
     Flight payload: no client query, no loading flash. The ivar is serialized to
     plain row hashes here in the view (no as_json on the model). %>
 <%% rows = @<%= plural_name %>.map { |<%= singular_name %>| <%= serialized_row(singular_name) %> } %>
-<<%= class_name %>List posts={rows} />
+<<%= class_name %>List <%= js_collection_prop %>={rows} />

data/lib/ruact/configuration.rb

@@ -73,7 +73,7 @@ module Ruact
     #     a stream-safety guarantee — Rack's multipart parser will still buffer
     #     bodies up to its own limits before the guard rejects. For very large
     #     uploads route through Active Storage Direct Upload or a presigned S3
-    #     URL; see `website/docs/api/server-actions.md` "File uploads" section.
+    #     URL; see https://ruact.dev/docs/api/server-actions.html, "File uploads".
     #   @example Raise the limit to 25 MB
     #     Ruact.configure { |c| c.max_upload_bytes = 25 * 1024 * 1024 }
     #   @example Disable the gem-side guard (reverse proxy owns the cap)
@@ -132,11 +132,13 @@ module Ruact
     #     host `package.json`) that is NOT in this list, it emits a warning
     #     (never a hard stop) that the generated components may import from
     #     outdated `@/components/ui/*` paths. Must be a non-empty Array of
-    #     Integers. Default `[1, 2]` (the majors tested at gem-release time).
+    #     Integers. Default `[1, 2, 4]` (the majors tested at gem-release time;
+    #     4 was run end to end on 2026-10-01: init --base radix, the full add
+    #     list, scaffold --shadcn, form/table/dialog in a browser).
     #     A dev who has manually verified a newer major adds it here to
     #     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] }
+    #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3, 4] }
     #
     # @!attribute [r] layout
     #   @return [Boolean, String] Which document wrapper a ruact page's HTML
@@ -250,7 +252,7 @@ module Ruact
         @query_parent_controller = "ApplicationController"
         @signed_global_id_default_purpose = nil
         @signed_global_id_default_expires_in = nil
-        @shadcn_compatible_versions = [1, 2]
+        @shadcn_compatible_versions = [1, 2, 4]
         @layout = false
         @layout_stylesheets = [:app]
       end

data/lib/ruact/routing.rb

@@ -24,9 +24,9 @@ module Ruact
   # The path segment reuses {Ruact::ServerFunctions::NameBridge} verbatim
   # (D4): `def search_users` → `GET /q/searchUsers`, named
   # `ruact_query_searchUsers`. Invalid or JS-reserved method names raise
-  # {Ruact::ConfigurationError} at route-draw time; two query classes mounting
-  # the same method name collide on the route NAME / path and fail Rails' own
-  # duplicate checks — both are loud boot failures, never request-time
+  # {Ruact::ConfigurationError} at route-draw time, and so do two query
+  # classes mounting the same method name (they would collide on the route
+  # name and on the export) — both are loud boot failures, never request-time
   # surprises.
   #
   # The generated dispatch controller PRESERVES the query class's namespace
@@ -56,11 +56,29 @@ module Ruact
 
         query_class.public_instance_methods(false).each do |query_method|
           js_identifier = ServerFunctions::NameBridge.to_js_identifier(query_method)
-          mapper.get("#{prefix}/#{js_identifier}",
-                     to: "#{target}##{query_method}",
-                     as: :"ruact_query_#{js_identifier}")
+          begin
+            mapper.get("#{prefix}/#{js_identifier}",
+                       to: "#{target}##{query_method}",
+                       as: :"ruact_query_#{js_identifier}")
+          rescue ArgumentError => e
+            raise unless e.message.include?("already in use")
+
+            raise_query_name_taken!(query_class, query_method, "#{prefix}/#{js_identifier}")
+          end
         end
       end
+
+      # Rails' own message ("Invalid route name, already in use") names a route
+      # the app never wrote. Name the query, the method and the way out.
+      def raise_query_name_taken!(query_class, query_method, path)
+        raise Ruact::ConfigurationError,
+              "#{query_class}##{query_method} cannot be mounted: GET #{path} is already mounted " \
+              "in these routes — by another query class that also defines `#{query_method}`, or " \
+              "by `ruact_queries #{query_class}` appearing twice. Query names share one namespace " \
+              "(one route and one export of @/.ruact/server-functions per name): remove the " \
+              "duplicate mount, or rename one of the methods (the scaffold names its search " \
+              "after the resource: search_posts, search_comments)."
+      end
     end
   end
 end

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.13"
+  VERSION = "0.0.14"
 end

data/vendor/javascript/vite-plugin-ruact/tsconfig.scaffold-agnostic.json

@@ -1,6 +1,6 @@
 {
   "//": "Story 14.4 (AC5) — type-check the GENERATED design-system-AGNOSTIC `<Model>{List,Form,DeleteDialog}.tsx` fixtures in ISOLATION against an ambient stub (type-tests/scaffold/agnostic/ambient.d.ts) that declares ONLY React + @/.ruact/server-functions and NO @/components/ui/* module. A stray shadcn import would fail to resolve → the typecheck goes red, proving the agnostic default needs zero design-system resolution. Mirrors tsconfig.scaffold.json (the shadcn isolated typecheck), but scoped to the agnostic subdir so the two ambient stubs never merge. Run via `npm run typecheck`.",
-  "//noImplicitAny": "Relaxed ONLY here: native-element event handler params (e.g. `onChange={(e) => …}`) get no contextual type from the permissive ambient `JSX.IntrinsicElements` (no @types/react / lib:dom). The load-bearing types — PostRow, the typed `search` accessor (FR99), the required `posts` prop, the controlled DeleteDialog contract — are all EXPLICITLY annotated and stay fully checked under `strict`.",
+  "//noImplicitAny": "Relaxed ONLY here: native-element event handler params (e.g. `onChange={(e) => …}`) get no contextual type from the permissive ambient `JSX.IntrinsicElements` (no @types/react / lib:dom). The load-bearing types — PostRow, the typed `searchPosts` accessor (FR99), the required `posts` prop, the controlled DeleteDialog contract — are all EXPLICITLY annotated and stay fully checked under `strict`.",
   "compilerOptions": {
     "strict": true,
     "noImplicitAny": false,

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/PostList.tsx

@@ -18,7 +18,7 @@
 // freshly scaffolded app will not resolve these until 10.5 lands; that is
 // expected (the end-to-end live demo is Story 10.7).
 import { useState } from "react";
-import { search as searchPosts, destroyPost, useQuery } from "@/.ruact/server-functions";
+import { searchPosts, destroyPost, useQuery } from "@/.ruact/server-functions";
 import { PostDeleteDialog } from "./PostDeleteDialog";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -194,7 +194,7 @@ function RowActions({ record, onDeleted }: {
 }
 
 export function PostList({
-  posts = [],
+  posts: initialRows = [],
   emptyLabel = "No posts yet — create one.",
 }: { posts?: PostRow[]; emptyLabel?: string }) {
   const [q, setQ] = useState("");
@@ -215,7 +215,7 @@ export function PostList({
   // the box is idle and we fall back to the server-rendered rows.
   const { data: searchData, loading: searchLoading } = useQuery<PostRow[]>(searchPosts, { q: q.trim() });
 
-  const source = searching ? searchData ?? [] : posts;
+  const source = searching ? searchData ?? [] : initialRows;
   const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
   // Always sort a COPY — never mutate the prop/source array.
   const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostList.tsx

@@ -13,7 +13,7 @@
 // sort/pagination is Phase-3 territory. (The richer shadcn DataTable styling is
 // the opt-in `--shadcn` path — Story 14.5.)
 import { useState } from "react";
-import { search as searchPosts, destroyPost, useQuery } from "@/.ruact/server-functions";
+import { searchPosts, destroyPost, useQuery } from "@/.ruact/server-functions";
 import { PostDeleteDialog } from "./PostDeleteDialog";
 
 type PostRow = { id: number; title: string | null; body: string | null; published: boolean | null; views: number | null; published_on: string | null; published_at: string | null; author_id: number | null };
@@ -139,7 +139,7 @@ function RowActions({ record, onDeleted }: {
 }
 
 export function PostList({
-  posts = [],
+  posts: initialRows = [],
   emptyLabel = "No posts yet — create one.",
 }: { posts?: PostRow[]; emptyLabel?: string }) {
   const [q, setQ] = useState("");
@@ -160,7 +160,7 @@ export function PostList({
   // the box is idle and we fall back to the server-rendered rows.
   const { data: searchData, loading: searchLoading } = useQuery<PostRow[]>(searchPosts, { q: q.trim() });
 
-  const source = searching ? searchData ?? [] : posts;
+  const source = searching ? searchData ?? [] : initialRows;
   const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
   // Always sort a COPY — never mutate the prop/source array.
   const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/ambient.d.ts

@@ -53,10 +53,10 @@ declare module "@/.ruact/server-functions" {
   // FR88/FR99 wire union — the only param value type a query accessor accepts.
   type Wire = string | number | boolean | null;
 
-  // The codegen exports a generic `search` from `<Plural>Query#search(q:)`,
-  // typed from the declared `(q:)` kwarg (Story 13.4). The List aliases it
-  // `search<Plural>`.
-  export const search: (params: { q: Wire }) => Promise<unknown>;
+  // The codegen exports `searchPosts` from `PostsQuery#search_posts(q:)`,
+  // typed from the declared `(q:)` kwarg (Story 13.4). The scaffold names the
+  // query after the resource: query names share one namespace.
+  export const searchPosts: (params: { q: Wire }) => Promise<unknown>;
 
   // Action accessors the generated Form imports. Actions are NOT typed by FR99
   // (only queries are — Story 13.4 decision A), so the accessors take a loose

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/ambient.d.ts

@@ -39,10 +39,10 @@ declare module "@/.ruact/server-functions" {
   // FR88/FR99 wire union — the only param value type a query accessor accepts.
   type Wire = string | number | boolean | null;
 
-  // The codegen exports a generic `search` from `<Plural>Query#search(q:)`,
-  // typed from the declared `(q:)` kwarg (Story 13.4). The List aliases it
-  // `search<Plural>`.
-  export const search: (params: { q: Wire }) => Promise<unknown>;
+  // The codegen exports `searchPosts` from `PostsQuery#search_posts(q:)` —
+  // the scaffold names the query after the resource, because query names
+  // share one namespace across every query class.
+  export const searchPosts: (params: { q: Wire }) => Promise<unknown>;
 
   // Action accessors the generated Form imports (Story 10.3). Actions are NOT
   // typed by FR99 (only queries are — Story 13.4 decision A), so the accessors

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri