ruby_native 0.11.0 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 354cc245f5601b5e39b3cbba720da1fe06edf675eb373e22eb1028b2c27056ce
-  data.tar.gz: 38080a8029fbffa2c920cd734196a88377f6b20967b83f9f947eab37835f46c6
+  metadata.gz: 17263e207966bb624e15f4fc93399c2cfb28b15d9810cffa563cfa24b5a8b725
+  data.tar.gz: 6e7b9c3de16b19ef85ec7a614b207cf22e5d39f1517e5d9467950d315586660b
 SHA512:
-  metadata.gz: 92f68b9731f743efd5aece5debb221c4963a93b373f9c76997dc688eba4f6da85b3eb3832efa457ebca0a0ed93d36a2b8417d0af5efa2fb23e8ce64734ac7002
-  data.tar.gz: 3142eea082eab9acc7f279173ca731452cd3e21f58a1d491470b61433204bed26a35f81f71ca6fad60ac7271fb776931872215867d6fbc574682605ee7b8286f
+  metadata.gz: a9574b90d18f99866ee2d2c291475aeac0f4c7e57f8b15ea2c8cdc0aaa312818e2d7f5e1e5fa421e313e3f5214d36a314c975d56146b8d329660aed07aaab20c
+  data.tar.gz: 3c2da4697edaa56eb5194531352282c5c28aa1fa6c3c4edbd83d6a74da1f5d9a751e7175799244ad207741c73ecc4ba29a55a061cdcf563412bee7d9d21203fb

data/lib/ruby_native/helper.rb

@@ -85,6 +85,89 @@ module RubyNative
       tag.div(data: data, hidden: true)
     end
 
+    # No :root. Landing a page as the tab root — dropping what is behind it —
+    # is a distinct operation from replacing the current entry, and no shell
+    # implements it: every one of them mapped :root onto replace, which unwinds
+    # nothing. Offering the word without the behavior is worse than not
+    # offering it, so it is out until a shell can honor it.
+    ACTIONS = %w[push replace].freeze
+
+    # Validates a push/replace landing value. Returns the value as a string,
+    # raises otherwise.
+    def self.validate_action(value, label: "action")
+      value = value.to_s
+      unless ACTIONS.include?(value)
+        raise ArgumentError,
+          "#{label} must be :push or :replace, got #{value.inspect}"
+      end
+      value
+    end
+
+    # The landing intents a page can declare about itself. Only :root so far.
+    # :modal is the obvious second member (both shells hardcode a /new + /edit
+    # rule today that no app can reach), which is why this is a vocabulary
+    # rather than a boolean tag.
+    PRESENTATION_INTENTS = %w[root].freeze
+
+    # Declares that this page is a root: it lands with nothing behind it, and no
+    # back affordance, wherever it lands.
+    #
+    #   <%= native_presentation_tag :root %>
+    #
+    # Emits the fact on two channels, because the shells need it at two
+    # different moments and neither channel reaches both:
+    #
+    # 1. A `data-native-presentation` element, reported with every other signal
+    #    once the page has rendered. This is what Normal Mode reads, and Normal
+    #    Mode can act on it late: it has no push stack, so suppressing back is
+    #    not a navigation and nothing refetches.
+    #
+    # 2. A `Native-Presentation` response header. Advanced Mode has to decide
+    #    before the navigation commits, or it pushes and then visibly corrects
+    #    itself. On a form submission Turbo has already fetched the destination
+    #    by the time it proposes the visit, so the header is readable at
+    #    `turbo:before-fetch-response` — before the proposal — and the header is
+    #    the only part of that response readable synchronously, since the body
+    #    arrives as a promise that consuming would take from Turbo.
+    #
+    # Nothing is declared at the origin. Both channels ride the response for the
+    # page itself, so a redirect chain carries the intent to wherever it actually
+    # lands rather than to wherever the link pointed.
+    #
+    # In Advanced Mode this takes effect before the navigation commits when the
+    # page arrives from a form submission, because that is the only case where
+    # Turbo has already fetched the destination by the time it proposes the
+    # visit. A link tap, a deep link and a cold boot are proposed before anything
+    # is fetched, so those fall back to the element and the shell corrects after
+    # the page renders. Normal Mode always uses the element.
+    #
+    # Do not call this inside a `cache` block. On a cache hit the element comes
+    # back from the cache and the header is never set, which silently leaves
+    # Advanced Mode with only the slower path.
+    def native_presentation_tag(presentation)
+      value = presentation.to_s
+      unless PRESENTATION_INTENTS.include?(value)
+        raise ArgumentError,
+          "native_presentation_tag must be #{PRESENTATION_INTENTS.map { |i| ":#{i}" }.join(" or ")}, " \
+          "got #{value.inspect}"
+      end
+
+      # `respond_to?` rather than a nil check alone: ActionView forwards it to
+      # the controller for the delegated methods, so a view rendered without one
+      # answers false here instead of raising a DelegationError.
+      if respond_to?(:response) && response
+        if Rails.env.development? && response.committed?
+          Rails.logger.warn(
+            "[ruby_native] native_presentation_tag rendered after the response was committed, " \
+            "so Advanced Mode will not see it before the navigation commits."
+          )
+        end
+        response.headers["Native-Presentation"] = value
+      end
+
+      tag.div(data: { native_presentation: value }, hidden: true)
+    end
+
     def native_navbar_tag(title = nil, pull_to_refresh: true, &block)
       builder = NavbarBuilder.new(self)
       capture(builder, &block) if block
@@ -131,14 +214,43 @@ module RubyNative
     # form (`{ ios: "...", android: "..." }`). When both are given, a matching
     # `icons[platform]` wins; otherwise falls back to `icon`. Returns nil when
     # nothing resolves.
+    #
+    # A non-Hash `icons:` raises rather than falling through. `icons: [ios:
+    # "...", android: "..."]` is an easy slip in ERB and yields an Array holding
+    # one Hash, which used to skip the lookup and fall back to `icon` — usually
+    # nil, so the button rendered with no icon on either platform and nothing
+    # said why. That reads as "per-platform icons are broken" rather than "wrong
+    # bracket," and it is invisible on whichever platform you aren't testing.
     def self.resolve_icon(icon: nil, icons: nil, platform: nil)
+      if !icons.nil? && !icons.is_a?(Hash)
+        raise ArgumentError,
+          "icons: must be a Hash like { ios: \"square.and.arrow.up\", android: \"share\" }, " \
+          "got #{icons.class}. Check for square brackets instead of curly braces."
+      end
+
       if icons.is_a?(Hash) && platform
         key = platform.to_sym
         per_platform = icons[key] || icons[key.to_s]
         return per_platform if per_platform
       end
-      icon
+
+      # Nothing matched, which is every web render: `native_platform` is nil in
+      # a browser. Fall back to `icon:`, then to any name in `icons:`, the same
+      # order `RubyNative.backfill_tab_icons` uses for the YAML config.
+      #
+      # Returning nil here instead would make `icons:` alone unusable, because
+      # `native_fab_tag` raises on a nil icon and would 500 a page that renders
+      # fine inside the app. The signal element is hidden and only read by the
+      # native app, so which name survives on the web doesn't matter.
+      icon || fallback_icon(icons)
+    end
+
+    def self.fallback_icon(icons)
+      return nil unless icons.is_a?(Hash)
+
+      icons[:ios] || icons["ios"] || icons[:android] || icons["android"]
     end
+    private_class_method :fallback_icon
 
     class NavbarBuilder
       def initialize(context)
@@ -225,13 +337,14 @@ module RubyNative
         @items = []
       end
 
-      def item(title, href: nil, click: nil, icon: nil, icons: nil, selected: false)
+      def item(title, href: nil, click: nil, icon: nil, icons: nil, selected: false, action: nil)
         resolved = RubyNative::Helper.resolve_icon(icon: icon, icons: icons, platform: @context.try(:native_platform))
         data = { native_menu_item: "", native_title: title }
         data[:native_href] = href if href
         data[:native_click] = click if click
         data[:native_icon] = resolved if resolved
         data[:native_selected] = "" if selected
+        data[:native_action] = RubyNative::Helper.validate_action(action) if action
         add(@context.tag.div(data: data))
       end
 

data/lib/ruby_native/version.rb

@@ -1,3 +1,3 @@
 module RubyNative
-  VERSION = "0.11.0"
+  VERSION = "0.11.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_native
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.2
 platform: ruby
 authors:
 - Joe Masilotti