ruact 0.0.4 → 0.0.6

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "rails/generators/named_base"
+
+module Ruact
+  module Generators
+    class ScaffoldGenerator < Rails::Generators::NamedBase
+      # Story 10.5 — the shadcn/ui dependency pre-flight's read-only helpers:
+      # the authoritative add-list (derived from the templates' own import
+      # predicates), state detection (complete / missing / partial), the
+      # copy-pasteable guidance messages, and the best-effort version-compat
+      # read + warning. Extracted into its own module (mirrors the 10.3
+      # {FormHelpers} / 10.2 {ScaffoldAttribute} extractions) to keep
+      # {ScaffoldGenerator} within its class-length budget. Mixed in below the
+      # `no_tasks` boundary so these never register as Thor commands — only the
+      # public `check_shadcn_setup` task (in the generator) is a command.
+      module ShadcnPreflight
+        # 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"
+
+        # The pre-flight body (the {ScaffoldGenerator#check_shadcn_setup} Thor
+        # command delegates here). Detect the host's shadcn state, surface the
+        # version-compat warning, and ABORT before any write (via `raise
+        # Thor::Error`, like `assert_supported_attribute_types!`) when the setup
+        # is missing/partial — unless `--skip-shadcn-check`.
+        def run_shadcn_preflight!
+          warn_incompatible_shadcn_version
+
+          state = shadcn_setup_state
+          return if state == :complete
+          # --skip-shadcn-check writes anyway; detection still ran so the
+          # templates can emit the in-file banner (see {#shadcn_missing?}).
+          return if skip_shadcn_check?
+
+          raise Thor::Error, state == :missing ? missing_shadcn_message : partial_shadcn_message
+        end
+
+        # AC1/AC2/AC4/AC7 — the authoritative `@/components/ui/*` primitives the
+        # generated output imports, DERIVED from the templates' own predicates
+        # (the {FormHelpers} `form_uses_*?`) so it can never drift from the
+        # emitted import set. Ordered to match the documented single `add` line:
+        # `button` + the form-conditional input-family, then the always-present
+        # 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`).
+        def required_shadcn_components
+          components = ["button"]
+          components << "input"    if form_uses_input?
+          components << "textarea" if form_uses_textarea?
+          components << "switch"   if form_uses_switch?
+          components << "select"   if form_uses_select?
+          components.push("label", "badge", "table", "alert-dialog", "dropdown-menu")
+        end
+
+        # The `app/javascript/components/ui/` directory the `@/components/ui/*`
+        # alias maps to (consistent with `ruact:install`'s `app/javascript`
+        # convention), and shadcn's `components.json` config marker at app root.
+        def shadcn_ui_dir
+          Pathname(destination_root).join("app/javascript/components/ui")
+        end
+
+        def shadcn_config_path
+          Pathname(destination_root).join("components.json")
+        end
+
+        def shadcn_component_file(name)
+          shadcn_ui_dir.join("#{name}.tsx")
+        end
+
+        # The required primitives whose `ui/<name>.tsx` file is absent (drives the
+        # partial-setup "lists exactly which components are missing" guidance).
+        def missing_shadcn_components
+          required_shadcn_components.reject { |name| shadcn_component_file(name).exist? }
+        end
+
+        # Detection (memoized — the FS does not change during a run):
+        #   :complete = components.json present AND every required ui/<name>.tsx present
+        #   :missing  = no components.json (shadcn is not initialized) → guide to
+        #               `init` + the full `add`. A `components.json` is the
+        #               authoritative "shadcn is set up" marker; without it the
+        #               setup is incomplete even if a `components/ui/` dir exists
+        #               (so we never emit a bare/empty `add` for a config-less app).
+        #   :partial  = components.json present but some required primitive absent
+        #               → targeted `add` of exactly the missing pieces.
+        def shadcn_setup_state
+          @shadcn_setup_state ||= compute_shadcn_setup_state
+        end
+
+        def compute_shadcn_setup_state
+          return :missing unless shadcn_config_path.exist?
+          return :complete if missing_shadcn_components.empty?
+
+          :partial
+        end
+
+        def skip_shadcn_check?
+          options[:skip_shadcn_check]
+        end
+
+        # AC3 — true only when the developer bypassed the pre-flight with
+        # `--skip-shadcn-check` AND the setup is still incomplete, so the
+        # components emit the prominent in-file banner. Default/configured runs
+        # leave this false → the templates' default-path bytes are unchanged (the
+        # 10.1–10.4/10.2b `tsc` byte-equality fixtures stay valid without regen).
+        def shadcn_missing?
+          skip_shadcn_check? && shadcn_setup_state != :complete
+        end
+
+        # The single copy-pasteable `add` line for the given component list.
+        def shadcn_add_command(components)
+          "npx shadcn@latest add #{components.join(' ')}"
+        end
+
+        # AC3 — the `add` command for the in-file banner. Uses the detectably
+        # missing primitives, falling back to the full required list when none is
+        # missing (e.g. the `ui/*` files exist but `components.json` is absent →
+        # state `:missing`) so the banner NEVER prints a bare `npx shadcn add`.
+        def shadcn_banner_add_command
+          components = missing_shadcn_components
+          components = required_shadcn_components if components.empty?
+          shadcn_add_command(components)
+        end
+
+        # AC2 — missing setup: the full `init` + single `add <full list>` sequence
+        # (all plain `add`s; NO data-table recipe, NO @tanstack install line).
+        def missing_shadcn_message
+          <<~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:
+
+              npx shadcn@latest init
+              #{shadcn_add_command(required_shadcn_components)}
+
+            No files were written (no partial state). Advanced: pass --skip-shadcn-check
+            to generate anyway and manage @/components/ui/* yourself.
+          MSG
+        end
+
+        # AC4 — partial setup: the EXACT missing names + the targeted `add` (only
+        # the missing pieces). Never auto-run.
+        def partial_shadcn_message
+          missing = missing_shadcn_components
+          <<~MSG.chomp
+            ruact:scaffold — shadcn/ui is configured, but components the scaffold imports
+            are not installed yet:
+              #{missing.join(', ')}
+            Add them, then re-run this generator:
+
+              #{shadcn_add_command(missing)}
+
+            No files were written (no partial state). Advanced: pass --skip-shadcn-check
+            to generate anyway and manage @/components/ui/* yourself.
+          MSG
+        end
+
+        # AC6 — the host `package.json`, parsed best-effort (nil when absent or
+        # unparseable; a malformed file must not crash the generator).
+        def host_package_json
+          return @host_package_json if defined?(@host_package_json)
+
+          path = Pathname(destination_root).join("package.json")
+          @host_package_json = path.exist? ? safe_parse_json(path.read) : nil
+        end
+
+        def safe_parse_json(raw)
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          nil
+        end
+
+        # AC6 — best-effort installed shadcn version string: `shadcn` (current)
+        # or legacy `shadcn-ui`, from dependencies/devDependencies. nil when run
+        # via `npx` (no pin) → a soft note, not a warning.
+        def shadcn_version_string
+          pkg = host_package_json
+          return nil unless pkg.is_a?(Hash)
+
+          %w[dependencies devDependencies].each do |section|
+            deps = pkg[section]
+            next unless deps.is_a?(Hash)
+
+            raw = deps["shadcn"] || deps["shadcn-ui"]
+            return raw if raw
+          end
+          nil
+        end
+
+        # The MAJOR of the installed version (`"^2.1.0"` → 2, `">=1.0"` → 1).
+        def installed_shadcn_major
+          raw = shadcn_version_string
+          return nil unless raw
+
+          digits = raw.to_s.gsub(/[^0-9.]/, "").split(".").first
+          return nil if digits.nil? || digits.empty?
+
+          digits.to_i
+        end
+
+        # AC6 — warn (never abort) when the installed shadcn major is outside the
+        # tested set; a soft note when the version can't be determined.
+        def warn_incompatible_shadcn_version
+          major = installed_shadcn_major
+          if major.nil?
+            say_status "note",
+                       "could not determine the installed shadcn version (run via npx?); " \
+                       "skipping the version-compat check", :yellow
+            return
+          end
+
+          compatible = Ruact.config.shadcn_compatible_versions
+          return if compatible.include?(major)
+
+          say_status "warning",
+                     "shadcn v#{major} is not regression-tested with this ruact " \
+                     "(tested majors: #{compatible.join(', ')}); the generated code may import " \
+                     "from outdated @/components/ui/* paths. Align shadcn to a tested major, or add " \
+                     "#{major} via Ruact.configure { |c| c.shadcn_compatible_versions = " \
+                     "#{(compatible + [major]).sort.inspect} } in config/initializers/ruact.rb once " \
+                     "verified. See #{SHADCN_DOCS_POINTER}", :yellow
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+"use client";
+
+<% unless typescript? -%>
+// Generated with --javascript: this .jsx file forfeits the FR99 typed server
+// boundary and the FR100 call-site contract (both TS-only). Re-run without
+// --javascript for the typed .tsx variant.
+<% end -%>
+<% if shadcn_missing? -%>
+// ⚠️ GENERATED WITH --skip-shadcn-check — shadcn/ui is not fully set up.
+// The @/components/ui/* imports below will NOT resolve until you install them
+// (the Vite dev server fails the build with an import error — loud by design):
+//   <%= shadcn_banner_add_command %>
+// (If you have not set up shadcn at all, run `npx shadcn@latest init` first.)
+<% end -%>
+// <%= class_name %> delete confirmation — a CONTROLLED shadcn AlertDialog. The
+// PARENT owns `open` and provides `onConfirm`; this component owns only its local
+// submit/error state. `onConfirm` performs the destroy<%= class_name %> call (DELETE
+// /<%= plural_name %>/:id) and reports `{ ok, error? }`:
+//
+//   - on success the parent closes the dialog (in-list removal of the row, or the
+//     server-driven `$redirect` the runtime follows) — no URL is built here;
+//   - on failure the dialog STAYS OPEN and shows the message inline (the gem's
+//     structured-error shape: the exception message in development, the generic
+//     server message in production).
+//
+// There is no Rails `method=delete` fallback — the destroy<%= class_name %> action
+// is the only path. Cancel / Escape / outside-click close via `onOpenChange(false)`
+// without deleting; focus returns to the row's Delete trigger (Radix default —
+// the trigger is never unmounted while the dialog animates).
+import { useState } from "react";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+<% if typescript? -%>
+
+type <%= class_name %>Row = { <%= ts_row_fields %> };
+
+// FR100 — opt-in call-site contract. INERT for this component: it is rendered
+// only from <%= class_name %>List.tsx (JSX), never from an ERB `<Component>` tag,
+// so the 13.5 preprocess validator never runs against it. Retained for uniformity
+// with the List/Form.
+export const __ruactContract = {
+  props: { <%= singular_name %>: "required" },
+};
+<% end -%>
+
+export function <%= class_name %>DeleteDialog({
+  open,
+  onOpenChange,
+  <%= singular_name %>,
+  onConfirm,
+}<% if typescript? %>: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  <%= singular_name %>: <%= class_name %>Row;
+  onConfirm: () => Promise<{ ok: boolean; error?: string }>;
+}<% end %>) {
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<% if typescript? %><string | null><% end %>(null);
+
+  async function handleConfirm(event<% if typescript? %>: { preventDefault: () => void }<% end %>) {
+    // Keep the dialog open across the async destroy — Radix's AlertDialogAction
+    // would otherwise close it on click. The PARENT closes it (via onOpenChange)
+    // only after a successful delete; a failure leaves it open with the message.
+    event.preventDefault();
+    setError(null);
+    setSubmitting(true);
+    const res = await onConfirm();
+    setSubmitting(false);
+    if (!res.ok) {
+      setError(res.error ?? "Could not delete this <%= human_name.downcase %>");
+    }
+  }
+
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete “{String(<%= singular_name %>.<%= display_attribute %> ?? "")}”?</AlertDialogTitle>
+          <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+        </AlertDialogHeader>
+        {error && <p className="text-sm text-destructive">{error}</p>}
+        <AlertDialogFooter>
+          {/* Cancel gets default focus (Radix) — the safe choice is the default. */}
+          <AlertDialogCancel disabled={submitting}>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            onClick={handleConfirm}
+            disabled={submitting}
+            className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+          >
+            {submitting ? "Deleting…" : "Delete"}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

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

@@ -0,0 +1,212 @@
+"use client";
+
+<% unless typescript? -%>
+// Generated with --javascript: this .jsx file forfeits the FR99 typed server
+// boundary and the FR100 call-site contract (both TS-only). Re-run without
+// --javascript for the typed .tsx variant.
+<% end -%>
+<% if shadcn_missing? -%>
+// ⚠️ GENERATED WITH --skip-shadcn-check — shadcn/ui is not fully set up.
+// The @/components/ui/* imports below will NOT resolve until you install them
+// (the Vite dev server fails the build with an import error — loud by design):
+//   <%= shadcn_banner_add_command %>
+// (If you have not set up shadcn at all, run `npx shadcn@latest init` first.)
+<% end -%>
+// <%= class_name %> form — shared by `new` (initial == null) and `edit` (initial
+// == the serialized record). Each field renders the shadcn control mapped to its
+// attribute type (Input / Textarea / Switch / Select), labelled, with the FR98
+// server error surfaced inline beneath it. Submits through the v2 action
+// accessors: create<%= class_name %> (POST /<%= plural_name %>) or update<%= class_name %> (PATCH /<%= plural_name %>/:id). On
+// success the controller drives navigation SERVER-SIDE via `redirect_to`
+// (the `$redirect` the runtime follows) — there is no client URL building here.
+// On a validation failure the SAME response carries the FR98 attribute-keyed
+// `errors` map, surfaced inline per field (the client stays on the form).
+//
+// The `@/components/ui/*` primitives below are installed by Story 10.5; a freshly
+// scaffolded app will not resolve them until then (the live demo is Story 10.7).
+//
+// Client-side validation is intentionally NOT here — it is server-only with a
+// full round-trip (Story 10.6 adds the model-validation bridge). The controlled
+// `useState` keeps this dependency-free; to adopt rich client validation later,
+// swap the controlled state for react-hook-form's `useForm` + shadcn `<Form>` and
+// feed these same FR98 `errors` into `setError` per key (opt-in — not the default).
+import { useState<% if typescript? %>, type FormEvent<% end %> } from "react";
+import { create<%= class_name %>, update<%= class_name %> } from "@/.ruact/server-functions";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+<% if form_uses_input? -%>
+import { Input } from "@/components/ui/input";
+<% end -%>
+<% if form_uses_textarea? -%>
+import { Textarea } from "@/components/ui/textarea";
+<% end -%>
+<% if form_uses_switch? -%>
+import { Switch } from "@/components/ui/switch";
+<% end -%>
+<% if form_uses_select? -%>
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+<% end -%>
+<% if typescript? -%>
+
+type <%= class_name %>Row = { <%= ts_row_fields %> };
+
+// FR100 — opt-in call-site contract: `initial` is OPTIONAL (`new` omits it,
+// `edit` passes the serialized record); each `references` field adds an
+// optional `<name>Options` prop the new/edit views pass. A typo'd prop name
+// fails at preprocess time instead of silently arriving as `undefined`.
+export const __ruactContract = {
+  props: <%= form_contract_props %>,
+};
+<% end -%>
+
+export function <%= class_name %>Form({ <%= form_props_params.join(", ") %> }<% if typescript? %>: <%= form_props_type %><% end %>) {
+<% scaffold_attributes.each do |attr| -%>
+<% if attr.boolean? -%>
+  const [<%= attr.js_var %>, <%= attr.js_setter %>] = useState(Boolean(initial?.<%= attr.column_name %> ?? false));
+<% else -%>
+  // String-valued state: native/shadcn controls bind `string` (numbers + refs
+  // arrive on the row as numbers, so coerce here). The controller re-coerces.
+  const [<%= attr.js_var %>, <%= attr.js_setter %>] = useState(String(initial?.<%= attr.column_name %> ?? ""));
+<% end -%>
+<% end -%>
+  // FR98 — keyed { [attr]: string[] }; `{}` means "no errors" (always present).
+  const [errors, setErrors] = useState<% if typescript? %><Record<string, string[]>><% end %>({});
+  const [saving, setSaving] = useState(false);
+
+  async function handleSubmit(event<% if typescript? %>: FormEvent<% end %>) {
+    event.preventDefault();
+    setSaving(true);
+    setErrors({});
+
+    const payload = {
+<% scaffold_attributes.each do |attr| -%>
+      <%= attr.column_name %>: <%= attr.js_var %>,
+<% end -%>
+    };
+
+    // On success the server returns a `$redirect` and the runtime navigates
+    // away (the code below does not run); on a validation failure we get the
+    // keyed `errors` map back instead.
+    const result = (initial != null
+      ? await update<%= class_name %>({ id: initial.id, ...payload })
+      : await create<%= class_name %>(payload))<% if typescript? %> as { errors?: Record<string, string[]> } | null<% end %>;
+
+    setSaving(false);
+    if (result && result.errors) {
+      setErrors(result.errors);
+    }
+  }
+
+  const errorsFor = (attr<% if typescript? %>: string<% end %>) => errors[attr] ?? [];
+
+  return (
+    <form onSubmit={handleSubmit} className="mx-auto max-w-xl space-y-6 px-4 py-8">
+      <h1 className="text-2xl font-semibold tracking-tight">
+        {initial != null ? `Edit <%= human_name %> #${initial.id}` : "New <%= human_name %>"}
+      </h1>
+
+      {errorsFor("base").length > 0 && (
+        <div className="rounded-md border border-destructive/50 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+          <ul className="list-disc space-y-1 pl-4">
+            {errorsFor("base").map((message, i) => (
+              <li key={i}>{message}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+<% scaffold_attributes.each do |attr| -%>
+<% case attr.shadcn_control -%>
+<% when :switch -%>
+
+      <div className="space-y-2">
+        <div className="flex items-center gap-2">
+          <Switch
+            id="<%= attr.column_name %>"
+            checked={<%= attr.js_var %>}
+            onCheckedChange={<%= attr.js_setter %>}
+            disabled={saving}
+          />
+          <Label htmlFor="<%= attr.column_name %>"><%= attr.column_name.humanize %></Label>
+        </div>
+        {errorsFor("<%= attr.column_name %>").map((message, i) => (
+          <p key={i} className="text-sm text-destructive">{message}</p>
+        ))}
+      </div>
+<% when :textarea -%>
+
+      <div className="space-y-2">
+        <Label htmlFor="<%= attr.column_name %>"><%= attr.column_name.humanize %></Label>
+        <Textarea
+          id="<%= attr.column_name %>"
+          value={<%= attr.js_var %>}
+          onChange={(e) => <%= attr.js_setter %>(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("<%= attr.column_name %>").map((message, i) => (
+          <p key={i} className="text-sm text-destructive">{message}</p>
+        ))}
+      </div>
+<% when :select -%>
+
+      <div className="space-y-2">
+        <Label htmlFor="<%= attr.column_name %>"><%= attr.name.humanize %></Label>
+        {/* Eager <Select> of controller-provided options (ivar → `<%= attr.options_prop %>` prop),
+            capped at the generator's REFERENCE_OPTIONS_LIMIT. For a parent set
+            larger than that, swap this for a server-search combobox backed by a
+            parent-options read query (opt-in follow-up — that query is out of this
+            scaffold's scope since the parent model isn't scaffolded here). */}
+        <Select
+          value={<%= attr.js_var %>}
+          onValueChange={<%= attr.js_setter %>}
+          disabled={saving}
+        >
+          <SelectTrigger id="<%= attr.column_name %>">
+            <SelectValue placeholder="Select <%= attr.name.humanize.downcase %>" />
+          </SelectTrigger>
+          <SelectContent>
+            {<%= attr.options_prop %>.map((option) => (
+              <SelectItem key={option.id} value={String(option.id)}>
+                {option.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        {errorsFor("<%= attr.column_name %>").map((message, i) => (
+          <p key={i} className="text-sm text-destructive">{message}</p>
+        ))}
+      </div>
+<% else -%>
+
+      <div className="space-y-2">
+        <Label htmlFor="<%= attr.column_name %>"><%= attr.column_name.humanize %></Label>
+        <Input
+          id="<%= attr.column_name %>"
+          type="<%= html_input_type(attr) %>"
+          value={<%= attr.js_var %>}
+          onChange={(e) => <%= attr.js_setter %>(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("<%= attr.column_name %>").map((message, i) => (
+          <p key={i} className="text-sm text-destructive">{message}</p>
+        ))}
+      </div>
+<% end -%>
+<% end -%>
+
+      <div className="flex items-center gap-3 pt-2">
+        <Button type="submit" disabled={saving}>
+          {saving ? "Saving…" : initial != null ? "Update <%= human_name.downcase %>" : "Create <%= human_name.downcase %>"}
+        </Button>
+        <Button variant="outline" asChild>
+          <a href={initial != null ? `/<%= plural_name %>/${initial.id}` : "/<%= plural_name %>"}>Cancel</a>
+        </Button>
+      </div>
+    </form>
+  );
+}