phlex-reactive 0.15.1 → 0.15.3

data/lib/phlex/reactive/component/identity.rb

@@ -18,6 +18,16 @@ module Phlex
       module Identity
         extend ActiveSupport::Concern
 
+        # Whether the installed GlobalID gives a class its own app
+        # (global_id_app, then GlobalID.app — rails/globalid after 1.4).
+        # Read once: it is a fact about the loaded gem.
+        def self.per_class_gid_app?
+          return @per_class_gid_app if defined?(@per_class_gid_app)
+
+          @per_class_gid_app = ::GlobalID::Identification.const_defined?(:ClassMethods, false) &&
+                               ::GlobalID::Identification::ClassMethods.method_defined?(:global_id_app)
+        end
+
         class_methods do
           # The record's instance-variable symbol (e.g. :@todo), computed once.
           # reactive_token reads it on every render; interpolating :"@#{key}" each
@@ -74,7 +84,7 @@ module Phlex
           # before to_gid (nil.to_gid would raise).
           if (record_ivar = klass.reactive_record_ivar) &&
              (record = instance_variable_get(record_ivar)) && signable_gid?(record)
-            payload["gid"] = record.to_gid.to_s
+            payload["gid"] = reactive_gid(record)
           end
 
           state_ivars = klass.reactive_state_ivars
@@ -95,6 +105,29 @@ module Phlex
         def signable_gid?(record)
           !(record.respond_to?(:persisted?) && !record.persisted?)
         end
+
+        # record.to_gid.to_s, without the URI. For a record whose to_gid is
+        # GlobalID's own (not overridden on its class or on itself) and whose
+        # id is an Integer, GlobalID's string is exactly
+        # "gid://<GlobalID.app>/<class name>/<id>": an Integer needs no
+        # escaping and there are no params. Building it directly skips a
+        # validated URI::GID (~37 objects, about half a record token's cost),
+        # once per record-backed row per render. Anything else goes through
+        # to_gid unchanged, its errors included.
+        def reactive_gid(record)
+          if record.is_a?(::GlobalID::Identification) &&
+             record.method(:to_gid).owner.equal?(::GlobalID::Identification) &&
+             (id = record.id).is_a?(Integer) && (app = reactive_gid_app(record.class)) && (name = record.class.name)
+            "gid://#{app}/#{name}/#{id}"
+          else
+            record.to_gid.to_s
+          end
+        end
+
+        # The app to_gid would use: the class's own where GlobalID has one.
+        def reactive_gid_app(klass)
+          (Identity.per_class_gid_app? && klass.global_id_app) || ::GlobalID.app
+        end
       end
     end
   end

data/lib/phlex/reactive/component/image_fallback_binding.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # An <img> that falls back when its src fails and recovers when the src
+      # changes (issue #383).
+      #
+      #   img(id: "logo", alt: "", **reactive_image_fallback(hide: true))
+      #   img(id: "logo", alt: "Bank", **reactive_image_fallback(show_alt: "#bank-name"))
+      #   span(id: "bank-name", hidden: true)
+      #
+      # On `error` the client sets data-reactive-image-state="error", adds
+      # `hidden` (hide: true, the default) and, with show_alt:, writes the
+      # img's alt into that node (a CSS selector inside the root) and shows it.
+      # On `load` the state is "loaded". A later src — copy_media,
+      # reactive_media, preview_file, a morph, or any src that loads — clears
+      # the error and shows the img again; an img with no src is never an
+      # error. hide: false leaves visibility alone: style the state with CSS.
+      # Composes with reactive_media (its **attrs mix the data attribute in):
+      #
+      #   img(**reactive_media(from: :rib, pool: POOL, **reactive_image_fallback))
+      #
+      # Named ImageFallbackBinding for the reason MediaBinding is (issue #233).
+      module ImageFallbackBinding
+        def reactive_image_fallback(hide: true, show_alt: nil, **attrs)
+          wire = { "hide" => image_fallback_hide!(hide) }
+          wire["alt"] = image_fallback_alt!(show_alt) unless show_alt.nil?
+          mix({ data: { reactive_image_fallback: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def image_fallback_hide!(hide)
+          return hide if [true, false].include?(hide)
+
+          raise ArgumentError, "reactive_image_fallback hide: must be true or false, got #{hide.inspect}"
+        end
+
+        # A selector the client passes to querySelector, never a URL.
+        def image_fallback_alt!(selector)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_image_fallback show_alt: #{selector} names the whole root — pass the selector of a node inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_image_fallback show_alt: must be a CSS selector (e.g. \"#bank-name\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/component/media_binding.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # A preview image that follows a field (issue #373), with no URL in the
+      # page's ops or attributes: the server renders every candidate <img>
+      # (hidden), and the binding copies the one whose key matches.
+      #
+      #   input(name: "code")
+      #   img(id: "logo", alt: "", **reactive_media(
+      #     from: :code, take: 3,
+      #     pool: { "007" => "#logo-007", "011" => "#logo-011" },
+      #     label: "#caption", blank_label: "Unknown"
+      #   ))
+      #   img(id: "logo-007", src: "/logos/007.svg", alt: "North", hidden: true)
+      #
+      # The field is read the way reactive_show reads one (owned fields, a
+      # radio group's checked value, reactive_scope applied). `take:` keeps the
+      # first n characters as the key; omit it to use the whole value. A pool
+      # value is a CSS SELECTOR for an <img> inside the root, never a URL: the
+      # client copies that element's src, srcset and alt the way
+      # js.copy_media does. A key, selector or element that misses (or is not
+      # an <img>) clears the preview. A pool <img> with an alt and no src is a
+      # hit without an image: the preview drops its src and takes the alt
+      # (issue #381). `label:` names a node whose textContent becomes the
+      # chosen image's alt (`blank_label`, or "", on a miss). Client-only: no token,
+      # no round trip.
+      #
+      # Until the field has `take` characters, or while `match:` (a Regexp,
+      # anchored to the whole key) rejects the key, the binding is PENDING
+      # (issue #380): never `blank_label`. `pending: :clear` (the default)
+      # clears the preview and empties the label; `pending: :keep` leaves both
+      # alone. The preview's data-reactive-media-state reads pending, hit or
+      # miss, so a row can hide itself with CSS until there is an answer.
+      #
+      # Named MediaBinding, not Media: this module sits in every reactive
+      # component's ancestry, and a bare `Media` would shadow a host app's kit
+      # component of that name (issue #233).
+      module MediaBinding
+        def reactive_media(from:, pool: nil, take: nil, match: nil, pending: :clear, label: nil, blank_label: nil, **attrs)
+          wire = { "field" => media_field!(from) }
+          wire["take"] = media_take!(take) unless take.nil?
+          wire["match"] = MediaPattern.to_js(match) unless match.nil?
+          wire["pending"] = "keep" if media_pending!(pending) == "keep"
+          wire["pool"] = media_pool!(pool)
+          wire["label"] = media_selector!(:label, label) unless label.nil?
+          wire["blank"] = blank_label.to_s unless blank_label.nil?
+          mix({ data: { reactive_media: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def media_field!(from)
+          name = from.to_s if from.is_a?(Symbol) || from.is_a?(String)
+          return name unless name.nil? || name.strip.empty?
+
+          raise ArgumentError, "reactive_media from: needs the field name to watch (e.g. from: :code), got #{from.inspect}"
+        end
+
+        def media_take!(take)
+          return take if take.is_a?(Integer) && take.positive?
+
+          raise ArgumentError, "reactive_media take: must be a positive Integer (or omitted for the whole value), " \
+                               "got #{take.inspect}"
+        end
+
+        def media_pending!(pending)
+          mode = pending.to_s if pending.is_a?(Symbol) || pending.is_a?(String)
+          return mode if %w[clear keep].include?(mode)
+
+          raise ArgumentError, "reactive_media pending: must be :clear or :keep, got #{pending.inspect}"
+        end
+
+        def media_pool!(pool)
+          if pool.nil?
+            raise ArgumentError, "reactive_media needs pool: — a Hash of key => selector of a server-rendered <img> " \
+                                 "(e.g. pool: { \"007\" => \"#logo-007\" })"
+          end
+          unless pool.is_a?(Hash) && !pool.empty?
+            raise ArgumentError,
+              "reactive_media pool: must be a non-empty Hash of key => <img> selector, got #{pool.inspect}"
+          end
+
+          pool.to_h { |key, selector| [key.to_s, media_selector!(:pool, selector)] }
+        end
+
+        # A pool value or label: is a selector, never a URL — the client only
+        # ever passes it to querySelector.
+        def media_selector!(kind, selector)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_media #{kind}: #{selector} names the whole root — pass the selector of an element inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_media #{kind}: values are CSS selectors (e.g. \"#logo-007\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/component/media_pattern.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # reactive_media's match: (issue #380) — a Ruby Regexp as the JavaScript
+      # source the client anchors as ^(?:…)$ and compiles without flags. The
+      # source is tokenized (an escape is one token, so an escaped backslash is
+      # never mistaken for one): a leading \A and a trailing \z/\Z are dropped,
+      # and anything JavaScript would read differently raises at render rather
+      # than matching silently wrong in the browser.
+      module MediaPattern
+        # Escapes Ruby reads as an anchor or a class and JS reads as a letter,
+        # plus \s/\S, whose JS class also holds Unicode spaces Ruby's does not.
+        RUBY_ONLY_ESCAPES = %w[\A \z \Z \G \h \H \R \X \K \p \P \s \S].freeze
+        # The group openers both engines read alike: (?: (?= (?! (?<= (?<! (?<name>
+        SHARED_GROUPS = [":", "=", "!", "<"].freeze
+        OPTIONS = Regexp::IGNORECASE | Regexp::EXTENDED | Regexp::MULTILINE
+
+        module_function
+
+        def to_js(match)
+          unless match.is_a?(Regexp)
+            raise ArgumentError,
+              "reactive_media match: must be a Regexp (e.g. /\\A\\d{3}\\z/), got #{match.inspect}"
+          end
+
+          unless match.options.nobits?(OPTIONS)
+            refuse!(match,
+              "has options (i, m, x) the client would read differently — drop them")
+          end
+
+          tokens = match.source.scan(/\\.|./m)
+          tokens.shift if tokens.first == "\\A"
+          final = tokens.pop if %w[\z \Z].include?(tokens.last)
+          check!(tokens, match)
+          # Ruby's \Z also matches before one final newline.
+          final == "\\Z" ? "#{tokens.join}\\n?" : tokens.join
+        end
+
+        def check!(tokens, match)
+          in_class = false
+          tokens.each_with_index do |token, i|
+            if RUBY_ONLY_ESCAPES.include?(token)
+              refuse!(match,
+                "uses #{token}, which is Ruby-only (JavaScript reads it differently)")
+            end
+            refuse!(match, "has a character above U+FFFF (the client pattern has no u flag)") if token.ord > 0xFFFF
+            if token == "\\u" && tokens[i + 1] == "{"
+              refuse!(match,
+                "uses \\u{…}, which JavaScript without the u flag reads as a repeated u")
+            end
+            if in_class
+              in_class = false if token == "]"
+              class_syntax!(tokens, i, match)
+            elsif token == "["
+              in_class = true
+            elsif token == "(" && tokens[i + 1] == "?" && !SHARED_GROUPS.include?(tokens[i + 2])
+              refuse!(match, "uses (?#{tokens[i + 2]}…), a group JavaScript does not read the same way")
+            end
+          end
+        end
+
+        # A [ inside a class (a nested class or a POSIX [:digit:]) and && (an
+        # intersection) are Ruby-only: JavaScript reads them as literals.
+        def class_syntax!(tokens, index, match)
+          token = tokens[index]
+          return unless token == "[" || (token == "&" && tokens[index + 1] == "&")
+
+          refuse!(match, "has a nested character class, a POSIX [:class:] or && — JavaScript reads them literally")
+        end
+
+        def refuse!(match, why)
+          raise ArgumentError, "reactive_media match: #{match.inspect} #{why}"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/doctor.rb

@@ -248,7 +248,15 @@ module Phlex
       # authorization / mark_authorized! call. It is :unknown, NEVER a hard fail:
       # a helper may authorize indirectly, so this is a hint, not a verdict.
       def authorization_check(components)
-        suspects = components.flat_map { unauthorized_action_labels(it) }
+        infos = nil
+        suspects = components.flat_map do
+          next [] if component_defines_authorization_method?(it)
+
+          # Read once, and only when needed: Inspector.components Prism-scans
+          # every component's actions.
+          infos ||= inspector_infos
+          unauthorized_action_labels(it, infos)
+        end
         return Check.new(:ok, "every mutating action appears to authorize", name: :authorization) if suspects.empty?
 
         Check.new(:unknown, "actions with no detected authorization call: #{suspects.join(", ")}",
@@ -394,13 +402,11 @@ module Phlex
       end
 
       # "Klass#action" for every declared action on `klass` that (advisory)
-      # appears unauthorized: the component defines no authorization method in its
-      # ancestry, the action isn't skipped, and the Prism scan (via the shared
-      # Inspector) finds no authorization / mark_authorized! call in its body.
-      def unauthorized_action_labels(klass)
-        return [] if component_defines_authorization_method?(klass)
-
-        info = Phlex::Reactive::Inspector.components.find { it.klass == klass }
+      # appears unauthorized (the caller has already ruled out an authorization
+      # method in its ancestry): the action isn't skipped, and the Prism scan (via
+      # the shared Inspector) finds no authorization / mark_authorized! call in its body.
+      def unauthorized_action_labels(klass, infos)
+        info = infos[klass]
         return [] unless info
 
         info.actions
@@ -417,6 +423,12 @@ module Phlex
       # Phlex::Reactive.authorization_methods and NOT the Inspector's set, which
       # folds in mark_authorized! — every component inherits that instance helper,
       # so including it would silence the check for everything.
+      def inspector_infos
+        Phlex::Reactive::Inspector.components.to_h { [it.klass, it] }
+      rescue StandardError
+        {}
+      end
+
       def component_defines_authorization_method?(klass)
         Phlex::Reactive.authorization_methods.any? do
           klass.method_defined?(it) || klass.private_method_defined?(it)

data/lib/phlex/reactive/held_fields.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The fields a morph held over a changed server value (issue #370).
+    #
+    # Since #338 a morph keeps the value of the field being typed in and writes
+    # the render's value as the field's default. When that render differs from
+    # the old default, someone else changed the field while the user typed.
+    # The client marks such a field and the root's next action request names it
+    # in the X-Reactive-Held header (a JSON array of field names). Inside the
+    # action, `reactive_held_fields` returns those names, so the app can refuse
+    # or merge instead of silently overwriting the other change:
+    #
+    #   def save(title: nil)
+    #     authorize!(@note, to: :update?)
+    #     return conflict! if reactive_held_fields.include?("title") && title != @note.title
+    #     ...
+    #
+    # The header is UNTRUSTED input, like every request field: it carries names
+    # only, never values, and is read as data — capped in bytes, count and
+    # length, non-strings dropped, and filtered to the names the running action
+    # declares as params (matched on the base name, so `title[en]` counts for a
+    # declared `title`). A name the action can't receive can't be overwritten
+    # by it. Malformed input reads as nothing held; it never fails a request.
+    # It is a hint about what the user saw, not authorization.
+    module HeldFields
+      HEADER = "X-Reactive-Held"
+
+      # A raw header longer than this is ignored unparsed.
+      MAX_BYTES = 4_096
+      # At most this many names are read …
+      MAX_NAMES = 64
+      # … each at most this long.
+      MAX_NAME_LENGTH = 128
+
+      EMPTY = [].freeze
+
+      class << self
+        # The held field names during the current action ([] outside one).
+        def current
+          Thread.current[:phlex_reactive_held_fields] || EMPTY
+        end
+
+        # Expose `names` for the block, restoring the previous list after.
+        def with(names)
+          previous = Thread.current[:phlex_reactive_held_fields]
+          Thread.current[:phlex_reactive_held_fields] = names
+          yield
+        ensure
+          Thread.current[:phlex_reactive_held_fields] = previous
+        end
+
+        # The header's names that `action_def` declares, frozen; [] for
+        # anything absent, oversized or malformed.
+        def parse(raw, action_def)
+          return EMPTY if raw.nil? || raw.empty? || raw.bytesize > MAX_BYTES
+
+          names = JSON.parse(raw)
+          names.is_a?(Array) ? filter(names, action_def) : EMPTY
+        rescue JSON::ParserError
+          EMPTY
+        end
+
+        # Keep the strings among `names` that `action_def` declares as params.
+        def filter(names, action_def)
+          declared = declared_names(action_def)
+          return EMPTY if declared.empty?
+
+          names.first(MAX_NAMES).select do
+            it.is_a?(String) && it.length <= MAX_NAME_LENGTH && declared.include?(base_name(it))
+          end.uniq.freeze
+        end
+
+        private
+
+        def declared_names(action_def)
+          params = action_def.params
+          params.is_a?(Hash) ? params.keys.map(&:to_s) : EMPTY
+        end
+
+        # "title" for "title", "title[]" and "title[en]".
+        def base_name(name) = name.split("[", 2).first
+      end
+    end
+  end
+end