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

data/lib/ruact/controller/document_rendering.rb ADDED Viewed

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+module Ruact
+  module Controller
+    # How a ruact response becomes a full HTML DOCUMENT — the wrapper a browser
+    # gets on a normal navigation, as opposed to the raw `text/x-component`
+    # Flight body an in-app navigation gets.
+    #
+    # Split out of `Ruact::Controller` because it answers one self-contained
+    # question ("who owns the `<head>`?") whose answer is load-bearing: the host
+    # app's layout does, because `stylesheet_link_tag`, favicons, fonts,
+    # analytics and every `<head>`-writing gem live there. `#ruact_html_shell`
+    # is the fallback for an app whose layout has not been migrated — it is
+    # deliberately minimal and has NO stylesheet slot.
+    module DocumentRendering
+      extend ActiveSupport::Concern
+      # Proof that a host layout called `ruact_js_assets`: the helper always
+      # emits the `__FLIGHT_DATA` bootstrap script when a payload is present,
+      # and `render_ruact_document` always supplies one. Matching on the payload
+      # script (rather than on the entry `<script src>`) keeps the check true in
+      # BOTH dev and production, whose entry tags differ.
+      RUACT_ASSETS_MARKER = "__FLIGHT_DATA"
+      # What counts as a mount target and what counts as a real call both live in
+      # {Ruact::LayoutSource}, shared with `ruact:install` so the runtime and the
+      # generator can never disagree about whether a layout is migrated.
+      private
+      # Emit the full HTML document a browser gets on a normal navigation.
+      #
+      # `Ruact.config.layout` decides, and it is EXPLICIT — ruact does not try
+      # to infer whether your layout is ready. It used to: 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 governed how every page in the app rendered. Answering "does this
+      # template call this method?" is not something pattern-matching can do
+      # reliably, so the question is no longer asked. See
+      # Ruact::Configuration#layout.
+      #
+      # - `false` (the default) → the built-in shell. Byte-identical to ruact's
+      #   behaviour before the layout path existed, with no detection in the
+      #   way, so an app that has not opted in cannot be affected by any of this.
+      # - `true` / a String → render through the app's layout. `ruact:install`
+      #   writes both halves of that opt-in together: `config.layout = true` in
+      #   the initializer AND `<%= ruact_js_assets %>` in the layout.
+      #
+      # An opted-in layout that does not actually emit the assets would produce
+      # a blank page, so the rendered document is checked before it is
+      # committed: that is a configuration error, raised in development/test and
+      # logged-and-degraded in production rather than served to real traffic.
+      def render_ruact_document(payload)
+        layout = Ruact.config.layout
+        return render html: ruact_html_shell(payload).html_safe, layout: false if layout == false
+        unless ruact_layout_resolvable?(layout)
+          __ruact_handle_unready_layout(layout, :missing)
+          return render html: ruact_html_shell(payload).html_safe, layout: false
+        end
+        # Copied to the view by Rails' `view_assigns` plumbing (the name does not
+        # match the `/\A@_/` protected-ivar filter) — that is how the layout's
+        # zero-argument `ruact_js_assets` reaches THIS render's Flight payload.
+        @ruact_flight_payload = payload
+        document = render_to_string(html: "".html_safe, layout: layout)
+        if ruact_document_mountable?(document)
+          render html: document.html_safe, layout: false
+        else
+          __ruact_handle_unready_layout(layout, :unwired)
+          render html: ruact_html_shell(payload).html_safe, layout: false
+        end
+      ensure
+        remove_instance_variable(:@ruact_flight_payload) if instance_variable_defined?(:@ruact_flight_payload)
+      end
+      # A document is only usable if BOTH halves are present: the payload/bootstrap
+      # block AND something to mount into. Checking the assets alone accepts a
+      # layout that calls `ruact_js_assets` in `<head>` but never got the root div
+      # — React then boots with no mount target and the page is silently blank.
+      def ruact_document_mountable?(document)
+        document.include?(RUACT_ASSETS_MARKER) && Ruact::LayoutSource.root?(document)
+      end
+      # Is there a layout to render into at all? Asking FIRST matters: passing
+      # `layout: true` to a controller with no resolvable layout raises
+      # `ArgumentError("There was no default layout for ...")`, which would turn
+      # every page of an API-shaped or `layout false` controller into a 500 in
+      # an app that opted in globally. `_default_layout`'s `require_layout`
+      # argument defaults to false precisely so it can be used as a probe — it
+      # returns nil instead of raising, and honours `action_has_layout?`.
+      #
+      # `NameError` is deliberately NOT swallowed: `_default_layout` re-raises it
+      # as "Could not render layout: ..." to surface a broken layout resolver
+      # (`layout -> { MissingConstant::LAYOUT }`). Turning that into "no layout"
+      # would hide the developer's bug behind a silently degraded page.
+      def ruact_layout_resolvable?(layout)
+        return ruact_layout_exists?(layout) if layout.is_a?(String)
+        resolved = _default_layout(lookup_context, [:html], [])
+        return false if resolved.nil? || resolved == false
+        # `_default_layout` returns a Template for the conventional lookup but a
+        # bare String path for a controller-declared `layout "name"` — and it
+        # returns that String WITHOUT checking the template exists. Treating
+        # "not nil" as resolvable therefore sent a declared-but-missing layout
+        # into `render_to_string`, where it raised `MissingTemplate` instead of
+        # taking the intended degrade-to-shell path.
+        return ruact_layout_exists?(resolved) if resolved.is_a?(String)
+        true
+      rescue NameError
+        raise
+      rescue StandardError
+        false
+      end
+      def ruact_layout_exists?(name)
+        lookup_context.exists?(name.to_s.delete_prefix("layouts/"), ["layouts"])
+      end
+      def __ruact_handle_unready_layout(_layout, reason)
+        detail =
+          if reason == :missing
+            "no layout could be resolved for it"
+          else
+            "the layout it rendered emitted no `ruact_js_assets` output (or no " \
+              "`<div id=\"root\"></div>` to mount into), which would have been a blank page"
+          end
+        message = <<~MSG.strip
+          ruact: #{controller_path}##{action_name} fell back to ruact's built-in HTML shell — #{detail}.
+            `Ruact.config.layout` is set, so this is a configuration error, not a default:
+            the built-in shell has no stylesheet slot, so your app's CSS does not reach this page.
+            Add `<%= ruact_js_assets %>` next to the `<div id="root"></div>` in your layout
+            (`rails generate ruact:install` writes both; `rails ruact:doctor` reports what is missing),
+            or set `Ruact.configure { |c| c.layout = false }` to use the built-in shell deliberately.
+        MSG
+        # A MISSING layout is a legitimate per-controller choice — an API-shaped
+        # controller, or one that declared `layout false`, inside an app that
+        # opted in globally. Raising there would break a normal Rails pattern,
+        # so it degrades to the shell and says so where a developer will see it.
+        #
+        # An UNWIRED layout is different: the developer pointed ruact at a
+        # layout that cannot mount the app, which is their bug to see — loudly
+        # in development, and degraded (never blank) in production.
+        if reason == :missing
+          logger&.info(message) if __ruact_local_env?
+          return
+        end
+        raise Ruact::Error, message if __ruact_local_env?
+        logger&.error(message)
+      end
+      def __ruact_local_env?
+        Rails.env.development? || Rails.env.test?
+      rescue StandardError
+        false
+      end
+      def ruact_html_shell(flight_payload)
+        # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
+        # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
+        # implementation. The bootstrap entry script is a deferred ES module, so it
+        # runs after the inline `__FLIGHT_DATA` classic script has populated the
+        # queue regardless of source order — emitting the whole block in `<body>`
+        # is correct.
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+            <head>
+              <meta charset="UTF-8" />
+              <meta name="viewport" content="width=device-width, initial-scale=1" />
+              #{ruact_csrf_meta_tag}
+              <title>Rails RSC</title>
+            </head>
+            <body>
+              <div id="root"></div>
+              #{ruact_js_assets(flight_payload)}
+            </body>
+          </html>
+        HTML
+      end
+      # Story 8.3 review R7 — emits `<meta name="csrf-token" content="...">`
+      # into the shell so the JS runtime's `<meta>` lookup can forward a
+      # valid `X-CSRF-Token` on every server-function (mutation) call. Without
+      # this, hosts that route `ruact_render` through the gem's HTML shell (the
+      # standard path) have no token in the document and the host's
+      # `protect_from_forgery` rejects every non-GET server function.
+      #
+      # Returns an empty string when CSRF protection isn't available
+      # (non-Rails specs, or hosts that have deliberately stripped
+      # `form_authenticity_token` from the controller surface).
+      def ruact_csrf_meta_tag
+        return "" unless respond_to?(:form_authenticity_token, true)
+        token = form_authenticity_token
+        return "" if token.nil? || token.empty?
+        %(<meta name="csrf-token" content="#{ERB::Util.html_escape(token)}" />)
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/ruact/controller.rb CHANGED Viewed

@@ -5,6 +5,7 @@ require "socket"
 require "uri"
 require_relative "view_helper"
 require_relative "validation_errors_collector"
+require_relative "controller/document_rendering"
 module Ruact
   # Include in ApplicationController to enable RSC rendering.
@@ -27,6 +28,9 @@ module Ruact
     # and so the shared `vite_dev_running?` / `vite_manifest_entry` helpers are
     # reachable here without duplication.
     include Ruact::ViewHelper
+    # Who owns the `<head>` — the host app's layout, with ruact's built-in shell
+    # as the un-migrated fallback. See Ruact::Controller::DocumentRendering.
+    include Ruact::Controller::DocumentRendering
     private
@@ -178,7 +182,7 @@ module Ruact
         if ruact_request?
           render plain: payload, content_type: "text/x-component"
         else
-          render html: ruact_html_shell(payload).html_safe, layout: false
+          render_ruact_document(payload)
         end
       end
     end
@@ -236,50 +240,5 @@ module Ruact
       controller = self.class.name.underscore.sub("_controller", "")
       Rails.root.join("app", "views", controller, "#{action}.html.erb")
     end
-    def ruact_html_shell(flight_payload)
-      # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
-      # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
-      # implementation. The bootstrap entry script is a deferred ES module, so it
-      # runs after the inline `__FLIGHT_DATA` classic script has populated the
-      # queue regardless of source order — emitting the whole block in `<body>`
-      # is correct.
-      <<~HTML
-        <!DOCTYPE html>
-        <html lang="en">
-          <head>
-            <meta charset="UTF-8" />
-            <meta name="viewport" content="width=device-width, initial-scale=1" />
-            #{ruact_csrf_meta_tag}
-            <title>Rails RSC</title>
-          </head>
-          <body>
-            <div id="root"></div>
-            #{ruact_js_assets(flight_payload)}
-          </body>
-        </html>
-      HTML
-    end
-    # Story 8.3 review R7 — emits `<meta name="csrf-token" content="...">`
-    # into the shell so the JS runtime's `<meta>` lookup can forward a
-    # valid `X-CSRF-Token` on every server-function (mutation) call. Without
-    # this, hosts that route `ruact_render` through the gem's HTML shell (the
-    # standard path) have no token in the document and the host's
-    # `protect_from_forgery` rejects every non-GET server function.
-    #
-    # Returns an empty string when CSRF protection isn't available
-    # (non-Rails specs, or hosts that have deliberately stripped
-    # `form_authenticity_token` from the controller surface).
-    def ruact_csrf_meta_tag
-      return "" unless respond_to?(:form_authenticity_token, true)
-      token = form_authenticity_token
-      return "" if token.nil? || token.empty?
-      %(<meta name="csrf-token" content="#{ERB::Util.html_escape(token)}" />)
-    rescue StandardError
-      ""
-    end
   end
 end

data/lib/ruact/doctor.rb CHANGED Viewed

@@ -171,14 +171,46 @@ module Ruact
       end
     end
+    # Two independent halves have to line up, and BOTH are silent when wrong:
+    # the layout has to call `ruact_js_assets`, and `Ruact.config.layout` has to
+    # be on. Miss either and ruact renders its built-in shell — which carries no
+    # stylesheet, so the app's own CSS never reaches a ruact page and nothing
+    # errors. Reporting each half separately is the point: "add one line" and
+    # "flip one setting" are different fixes.
+    #
+    # `Ruact::LayoutSource` is the SHARED definition of "calls the helper" —
+    # the runtime and `ruact:install` read it too, so this check cannot drift
+    # into disagreeing with what actually happens at render time (it did:
+    # a `<%# TODO: add ruact_js_assets %>` comment used to pass here).
     def check_layout
       path = Rails.root.join("app", "views", "layouts", "application.html.erb")
-      if File.exist?(path) && File.read(path).include?("ruact: root")
-        [:pass, "React shell present in application.html.erb"]
-      else
-        [:fail, "React shell missing from application.html.erb",
-         "Run rails generate ruact:install to add the React shell to application.html.erb."]
+      unless File.exist?(path)
+        return [:fail, "React shell missing from application.html.erb",
+                "Run rails generate ruact:install to add the React shell to application.html.erb."]
       end
+      content    = File.read(path)
+      has_root   = Ruact::LayoutSource.root?(content)
+      has_assets = Ruact::LayoutSource.wired?(content)
+      opted_in   = Ruact.config.layout != false
+      return layout_unwired_result unless has_root && has_assets
+      return layout_not_opted_in_result unless opted_in
+      [:pass, "layout owns the document (React root + ruact_js_assets, config.layout on)"]
+    end
+    def layout_unwired_result
+      [:fail, "layout is missing the React root and/or the ruact_js_assets call",
+       "Add <%= ruact_js_assets %> next to <div id=\"root\"></div> in " \
+       "app/views/layouts/application.html.erb (or re-run rails generate ruact:install). " \
+       "Without both, ruact renders its built-in shell and your app's CSS never reaches the page."]
+    end
+    def layout_not_opted_in_result
+      [:warn, "layout is ready but Ruact.config.layout is false",
+       "Your layout calls ruact_js_assets, but ruact is still rendering its built-in shell " \
+       "(which has no stylesheet). Set `config.layout = true` in config/initializers/ruact.rb."]
     end
     def check_streaming

data/lib/ruact/layout_source.rb ADDED Viewed

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+module Ruact
+  # Answers one question in ONE place: does this layout actually wire ruact up?
+  #
+  # Two callers need that answer and must not disagree about it — the runtime
+  # (`Ruact::Controller::DocumentRendering`, deciding whether it is safe to
+  # render through the host layout) and `ruact:install` (deciding whether the
+  # layout still needs migrating). When they each carried their own notion of
+  # "present", they drifted: the generator skipped a layout as already-migrated
+  # on a `<%# TODO: add ruact_js_assets %>` comment, while the runtime read the
+  # same layout as unwired. Both were string-matching a NAME where only a CALL
+  # counts.
+  module LayoutSource
+    # ERB comments are stripped before anything else. A commented-out call —
+    # `<%# <%= ruact_js_assets %> %>`, which a developer produces the moment
+    # they disable it while debugging — emits NOTHING, so counting it as wired
+    # would report a layout as migrated when it is not. The `-?` covers ERB's
+    # trim-mode forms (`<%-#` / `-%>`), which Erubi treats as comments too and
+    # an earlier version of this pattern missed.
+    ERB_COMMENT = /<%-?#.*?-?%>/m
+    # An ERB OUTPUT tag calling the helper: `<%= ruact_js_assets %>` and the raw
+    # `<%== ... %>` form, with or without arguments or surrounding whitespace.
+    # Scanning stops at the tag's own `%>` rather than forbidding `%` outright —
+    # `<%= raw("100%") + ruact_js_assets %>` is a legitimate call that a
+    # `[^%]*` pattern rejected, while still never matching a bare mention that
+    # merely follows some other tag.
+    ASSETS_CALL = /<%=+(?:(?!%>).)*?\bruact_js_assets\b/m
+    # The React mount target, as an attribute rather than as a substring. The
+    # lookbehind is what stops `data-id="root"` (and any other `*-id`) from
+    # counting: those are not the mount point, and a document that has one but
+    # no real root gives React nothing to mount into. Unquoted `id=root` is
+    # valid HTML and is accepted.
+    ROOT_ATTRIBUTE = /(?<![-\w])id\s*=\s*(?:"root"|'root'|root(?=[\s>]))/
+    # The whole element, for a generator that needs something to inject AFTER.
+    ROOT_ELEMENT = %r{<div\s[^>]*#{ROOT_ATTRIBUTE.source}[^>]*>\s*</div>}
+    class << self
+      # Does this ERB source actually CALL `ruact_js_assets`?
+      def wired?(source)
+        without_comments(source).match?(ASSETS_CALL)
+      end
+      # Does this markup carry a React mount target? Used on RENDERED HTML by
+      # the runtime and on ERB source by the generator; the attribute shape is
+      # the same either way.
+      def root?(markup)
+        markup.to_s.match?(ROOT_ATTRIBUTE)
+      end
+      def without_comments(source)
+        source.to_s.gsub(ERB_COMMENT, "")
+      end
+    end
+  end
+end

data/lib/ruact/version.rb CHANGED Viewed

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

data/lib/ruact/view_helper.rb CHANGED Viewed

@@ -44,12 +44,21 @@ module Ruact
     # (no drift). Available in every view via the railtie's
     # `ActionView::Base.include(Ruact::ViewHelper)`.
     #
+    # Called from a LAYOUT the argument is normally omitted: the payload for the
+    # render in flight is picked up from `@ruact_flight_payload`, which
+    # `Ruact::Controller#render_ruact_document` sets on the controller and Rails
+    # copies to the view (the name does not match the `/\A@_/` protected-ivar
+    # filter). On a plain Rails page — no ruact render in flight — that ivar is
+    # absent and the helper emits only the entry tags, exactly as before.
+    #
     # @param flight_payload [String, nil] the per-render Flight wire payload to
-    #   inline as `__FLIGHT_DATA`; omit (or pass nil) to emit only the entry tags.
+    #   inline as `__FLIGHT_DATA`. Omit inside a layout to use the render in
+    #   flight; an explicit argument always wins.
     # @return [ActiveSupport::SafeBuffer] the asset markup, html_safe
     # @example In a layout
     #   <%= ruact_js_assets %>
     def ruact_js_assets(flight_payload = nil)
+      flight_payload ||= @ruact_flight_payload
       parts = []
       parts << ruact_flight_data_script(flight_payload) unless flight_payload.nil?
       parts << ruact_vite_tags

data/lib/ruact.rb CHANGED Viewed

@@ -7,6 +7,7 @@ require_relative "ruact/serializable"
 require_relative "ruact/signed_references"
 require_relative "ruact/flight"
 require_relative "ruact/string_distance"
+require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"

data/spec/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/ghost_layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/rootless_layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/unwired_layout_demo/show.html.erb ADDED Viewed

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/layouts/bare_host.html.erb ADDED Viewed

@@ -0,0 +1,16 @@
+<%# An UNMIGRATED host layout: it has the React root but never calls
+    `ruact_js_assets`, so rendering the page through it would produce a
+    document with no bootstrap entry and no Flight payload — a blank page.
+    ruact must detect that and fall back to its built-in shell instead. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="/host-app.css" />
+    <title>Host App Title</title>
+  </head>
+  <body>
+    <%= yield %>
+    <%# ruact: root %>
+    <div id="root"></div>
+  </body>
+</html>

data/spec/fixtures/story_7_9_views/layouts/exploding_host.html.erb ADDED Viewed

@@ -0,0 +1,24 @@
+<%# An UNMIGRATED layout that cannot survive being rendered on a ruact page.
+    It reads an ivar that only a plain Rails action would have set — exactly the
+    shape of a real pre-migration app, whose layout has never once run on a
+    ruact-rendered page. If ruact renders this speculatively just to discover it
+    lacks `ruact_js_assets`, the app 500s on a page that used to work.
+    NOTE: this comment MENTIONS the helper name on purpose — a readiness check
+    that greps for the bare string counts this layout as wired and renders it. %>
+<%# <%= ruact_js_assets %> %>
+<%# ...and the line above is a genuinely COMMENTED-OUT call, which is the
+    sharper version of the same trap: ERB comments do not nest, so it emits
+    nothing, but a check that only looks for `<%=` sees a call. Both shapes must
+    read as UNMIGRATED, or this layout gets rendered and 500s below. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= @page_title.upcase %></title>
+  </head>
+  <body>
+    <%= yield %>
+    <%# ruact: root %>
+    <div id="root"></div>
+  </body>
+</html>

data/spec/fixtures/story_7_9_views/layouts/rootless_host.html.erb ADDED Viewed

@@ -0,0 +1,15 @@
+<%# A layout that calls `ruact_js_assets` but never got the React root div.
+    The payload and the bootstrap both ship, so an assets-only readiness check
+    accepts it — and the browser boots React with nothing to mount into,
+    producing a silently blank page. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="/host-app.css" />
+    <title>Host App Title</title>
+  </head>
+  <body>
+    <%= yield %>
+    <%= ruact_js_assets %>
+  </body>
+</html>

data/spec/fixtures/story_7_9_views/layouts/ruact_host.html.erb ADDED Viewed

@@ -0,0 +1,17 @@
+<%# A MIGRATED host layout: the app owns the document. The stylesheet link is
+    the whole point — it is the thing ruact's built-in shell has no slot for,
+    so a spec asserting it appears in the response is asserting that the host
+    app's CSS actually reaches a ruact page. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="/host-app.css" />
+    <title>Host App Title</title>
+  </head>
+  <body>
+    <%= yield %>
+    <%# ruact: root %>
+    <div id="root"></div>
+    <%= ruact_js_assets %>
+  </body>
+</html>