ruby_native 0.11.1 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c596379ed0170d7784e8273e1ac3c10023ebc6115a7d8a7d1edb2633f7325449
-  data.tar.gz: b966e8aeb40899fa32ff8f34f85dffc031b073f0637cf1917083f43ce504e06a
+  metadata.gz: 17263e207966bb624e15f4fc93399c2cfb28b15d9810cffa563cfa24b5a8b725
+  data.tar.gz: 6e7b9c3de16b19ef85ec7a614b207cf22e5d39f1517e5d9467950d315586660b
 SHA512:
-  metadata.gz: fbddcd87a18dc14cd8eacdf1b4456c6cacc41c2f26c76e3dc0d6d2383b8c40a76de274901d3456d2ee40a79f56edd3b17d0a9510918e7a67adc9d6fa675f57d3
-  data.tar.gz: 1d9bbb26a648e42952fd11de6d63cb65286d8247e5c847fbd2007760de213ed371f5ff6a61372f582a9cfe75b26fb10f8b11f6c5187187f415af4c511021a748
+  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
@@ -254,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.1"
+  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.1
+  version: 0.11.2
 platform: ruby
 authors:
 - Joe Masilotti