expo_turbo-rails 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 879d2dc22ae296a562bec85a13416fc54a99af71451a9301a933e70fe2e526f7
-  data.tar.gz: 5e17db2c9cd79b5da438b6a2896a2cbe711b3222649453d1df2427a5d84db28b
+  metadata.gz: ab2beaab9a4d3b8388af91c107877e839dbfec1b07c10efb13fc08e8d16df206
+  data.tar.gz: 58a6a45c227b1cbf20128ae1a17e550b032ccd4f2545d05322a2721a37576048
 SHA512:
-  metadata.gz: d638831a71e7c9a957c9deb5aa43b1d7d9329fa77e954bf692d71b97929685105b7cd812ab3edae9668a7e1801f9f3f71dd5b471959d6c2bd272798e5f9ed815
-  data.tar.gz: 4dda22e4406787f8b1380801fe7191720cd342a37346e892229d08f0b6c8406c3506f0dff5dea375eaa8f583e497bc39c06bd76952ef7164bf8a87fa46b0d242
+  metadata.gz: a5310b102f127ff8f64f42ec7d56360d8834a752dd395637d55cabeca393221b16617714729a9f2467acb39382eaac8ab75414f1ecf0cdc1b8954a377acdcdfc
+  data.tar.gz: 0a10cd23ece57b85a58c66cc5256f5288b4a9ffba0a1d8725f7774155e96c6767b7136858d69bbe62a36c3b6d8251c18d3f5b72f8465f37637644daebbc55788

data/README.md

@@ -5,10 +5,10 @@ The Rails package for Expo Turbo. It registers the distinct `application/vnd.exp
 The package validates rendered Expo Turbo documents structurally and rejects blank or duplicate literal IDs across the complete response, including Frame IDs. A controller must declare the components and style tokens it is allowed to render documents; when it does, the same policy also applies to its Frame, Stream, and raw controller-broadcast output. Its optional protected Cable boundary delegates all credentials and resource policy to the host.
 
 > [!IMPORTANT]
-> Version [`0.1.0`](https://rubygems.org/gems/expo_turbo-rails) is the stable
-> release published on 2026-07-27. Manual VoiceOver, TalkBack, and browser
+> Version [`0.1.4`](https://rubygems.org/gems/expo_turbo-rails) is the stable
+> release published on 2026-07-30. Manual VoiceOver, TalkBack, and browser
 > screen-reader evidence remains an explicit follow-up and is not claimed by
-> the `0.1.0` compatibility surface.
+> the `0.1.4` compatibility surface.
 
 ```ruby
 gem "expo_turbo-rails"
@@ -18,6 +18,16 @@ gem "expo_turbo-rails"
 require "expo_turbo/rails"
 ```
 
+Use the Accept-header route constraint when Expo Turbo and another format share a route family:
+
+```ruby
+constraints ExpoTurbo::Rails::RouteConstraint.new do
+  get "screens/:step", to: "turbo/documents#show"
+end
+```
+
+The constraint matches the registered Expo Turbo MIME type and positive `application/*` or `*/*` wildcards. A `q=0` value on the most-specific matching media range rejects the request, even when a less-specific wildcard has a positive quality. Missing, blank, unrelated, and substring-only Accept values do not match.
+
 Opt a controller into XML rendering and confine it to one host-owned view root:
 
 ```ruby
@@ -46,6 +56,29 @@ end
 
 The template argument is relative to the configured root; absolute paths, traversal, missing files, and symlink escapes are rejected. The resolved `.xml.erb` source is evaluated as ERB with layouts disabled, rather than served as raw file content. Before it renders, the exact output must be a strict UTF-8 XML document: one root, valid namespaces and attributes, no DTD or processing instruction, and an optional leading UTF-8 XML declaration only. Every literal `id` must also be nonblank and unique across the complete rendered document, including nested Frames. The capability declaration then admits only its exact components (and explicit aliases), exact unprefixed `turbo-frame`, `turbo-stream`, `template`, and `turbo-cable-stream-source` wrappers (including default-namespace elements), and declared `style-tokens`. Style-token lists use the same JavaScript whitespace split, count, duplicate, component, and group-conflict rules as the native adapter. A component must opt into the `style-tokens` attribute, and style-token component lists are canonicalized through aliases. The host declaration must mirror its installed registry and style adapter; it deliberately does not attempt to derive or validate arbitrary Zod props/codecs. Validation never serializes the output, so it does not alter preserved XML text.
 
+Do not put multiline values in XML attributes with ordinary ERB interpolation. The client XML parser changes raw tabs and line breaks in an attribute to spaces before component decoding. A later form submission can then save the changed value. Use `expo_turbo_attribute` for each value that can contain this whitespace:
+
+```erb
+<CustomerNotes value="<%= expo_turbo_attribute(@order.notes) %>" />
+```
+
+The helper first HTML-escapes the value. It then writes tabs, carriage returns, and line feeds as `&#9;`, `&#13;`, and `&#10;`. The character references preserve the original value through XML parsing. Use `xml:space="preserve"` instead for multiline element text.
+
+The client registry can replace the hand-written component map. Write `registry.capabilityManifestJSON()` to a checked-in or generated file, then configure the controller with `manifest:` instead of `components:`:
+
+```ruby
+expo_turbo_template_capabilities(
+  manifest: Rails.root.join("config/expo_turbo_manifest.json"),
+  max_style_tokens: 5,
+  style_tokens: {
+    "space:compact" => {components: ["DemoCard"], group: "space"},
+    "tone:info" => {components: ["DemoCard"], group: "tone"}
+  }
+)
+```
+
+The versioned manifest contains the registry modules, component tags and aliases, and each component's attribute names. Rails loads it when the controller is configured, rejects a malformed or protocol-incompatible file, derives `style-tokens` support from the declared attribute, and applies the same component validation in every environment. Generate the file in CI and fail on a diff to detect a stale manifest before deployment.
+
 For a native Frame GET, read the validated request header and emit an exact matching Frame from the host-owned XML template. `expo_turbo_frame_tag` accepts a nonblank UTF-8 literal ID without control characters, or a model class that it normalizes with Rails' `dom_id`, then delegates tag generation to `turbo-rails`. It deliberately does not install `Turbo::Frames::FrameRequest`, so it does not alter HTML layouts or adopt its raw-header behavior. Before returning, it parses the exact Frame output under a private synthetic root and applies the same configured component/style admission: markup must be valid UTF-8 XML without declarations, DTDs, or processing instructions, and any XML prefix must be declared by the Frame fragment itself. Validation does not serialize or alter the returned `SafeBuffer`, so inline `xml:space="preserve"` text keeps its authored bytes for the native parser.
 
 ```ruby

data/lib/expo_turbo/rails/attributes/helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/erb/util"
+require "active_support/core_ext/string/output_safety"
+
+module ExpoTurbo
+  module Rails
+    module Attributes
+      module Helper
+        XML_WHITESPACE_REFERENCES = {
+          "\t" => "	",
+          "\n" => "
",
+          "\r" => "
"
+        }.freeze
+
+        def expo_turbo_attribute(value)
+          ERB::Util.html_escape(value)
+            .gsub(/[\t\n\r]/, XML_WHITESPACE_REFERENCES)
+            .html_safe
+        end
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/controller.rb

@@ -16,6 +16,7 @@ module ExpoTurbo
       included do
         class_attribute :expo_turbo_views_path, instance_accessor: false
         class_attribute :expo_turbo_template_capabilities_config, instance_accessor: false
+        helper ExpoTurbo::Rails::Attributes::Helper
         helper ExpoTurbo::Rails::Frames::Helper
         helper ExpoTurbo::Rails::DomIds::Helper
         helper ExpoTurbo::Rails::Streams::Helper
@@ -27,9 +28,10 @@ module ExpoTurbo
           self.expo_turbo_views_path = Pathname(path).expand_path
         end
 
-        def expo_turbo_template_capabilities(components:, style_tokens: {}, max_style_tokens: 5)
+        def expo_turbo_template_capabilities(components: nil, manifest: nil, style_tokens: {}, max_style_tokens: 5)
           self.expo_turbo_template_capabilities_config = TemplateCapabilities.new(
             components:,
+            manifest:,
             style_tokens:,
             max_style_tokens:
           )

data/lib/expo_turbo/rails/route_constraint.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rack/media_type"
+
+module ExpoTurbo
+  module Rails
+    class RouteConstraint
+      ACCEPT_ENTRY = /[^,\s"](?:[^,"]|"[^"]*")*/
+
+      def matches?(request)
+        accept = request.get_header("HTTP_ACCEPT").to_s.strip
+        return false if accept.empty?
+
+        mime_type = Mime[MIME_SYMBOL]
+        return false unless mime_type
+
+        quality = accept.scan(ACCEPT_ENTRY).filter_map do |value|
+          begin
+            media_range = Rack::MediaType.type(value)
+            parsed = Mime::Type.parse(media_range)
+          rescue Mime::Type::InvalidMimeType
+            next
+          end
+          next unless parsed.include?(mime_type) || media_range == "*/*"
+
+          specificity = if media_range == "*/*"
+            0
+          elsif media_range.end_with?("/*")
+            1
+          else
+            2
+          end
+
+          [specificity, Rack::MediaType.params(value).fetch("q", 1).to_f]
+        end.max_by { |specificity, range_quality| [specificity, range_quality] }&.last
+
+        quality.to_f.positive?
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/template_capabilities.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "json"
+
 module ExpoTurbo
   module Rails
     class TemplateCapabilities
+      MANIFEST_VERSION = 1
       PROTOCOL_ELEMENTS = %w[turbo-cable-stream-source turbo-frame turbo-stream template].freeze
       RESERVED_COMPONENT_NAMES = [*PROTOCOL_ELEMENTS, "expo-turbo-fragment"].freeze
       TOKEN_PATTERN = /\A[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)*\z/
@@ -14,7 +17,12 @@ module ExpoTurbo
       class ValidationError < StandardError
       end
 
-      def initialize(components:, style_tokens: {}, max_style_tokens: 5)
+      def initialize(components: nil, manifest: nil, style_tokens: {}, max_style_tokens: 5)
+        if components.nil? == manifest.nil?
+          raise ConfigurationError, "Expo Turbo template capabilities require exactly one of components or manifest"
+        end
+
+        components = load_manifest_components(manifest) unless manifest.nil?
         @components, @style_token_components = normalize_components(components)
         @style_tokens = normalize_style_tokens(style_tokens)
         @max_style_tokens = validate_max_style_tokens!(max_style_tokens)
@@ -36,6 +44,102 @@ module ExpoTurbo
 
       private
 
+      def load_manifest_components(path)
+        manifest = parse_manifest(read_manifest(path))
+        unless manifest["manifestVersion"] == MANIFEST_VERSION
+          raise ConfigurationError, "Expo Turbo capability manifest version is unsupported"
+        end
+        unless manifest["protocolVersion"] == PROTOCOL_VERSION
+          raise ConfigurationError, "Expo Turbo capability manifest protocol version does not match"
+        end
+        unless manifest["hash"].is_a?(String) && /\Afnv1a32:[0-9a-f]{8}\z/.match?(manifest["hash"])
+          raise ConfigurationError, "Expo Turbo capability manifest hash is invalid"
+        end
+
+        validate_manifest_modules!(manifest["modules"])
+        normalize_manifest_components(manifest["components"])
+      end
+
+      def read_manifest(path)
+        path = path.to_path if path.respond_to?(:to_path)
+        unless path.is_a?(String) && !path.empty?
+          raise ConfigurationError, "Expo Turbo capability manifest path must be a nonblank path"
+        end
+
+        File.binread(path).force_encoding(Encoding::UTF_8).tap do |body|
+          unless body.valid_encoding?
+            raise ConfigurationError, "Expo Turbo capability manifest must be valid UTF-8"
+          end
+        end
+      rescue SystemCallError, ArgumentError
+        raise ConfigurationError, "Expo Turbo capability manifest could not be read"
+      end
+
+      def parse_manifest(body)
+        JSON.parse(body).tap do |manifest|
+          unless manifest.is_a?(Hash)
+            raise ConfigurationError, "Expo Turbo capability manifest must be a JSON object"
+          end
+        end
+      rescue JSON::ParserError
+        raise ConfigurationError, "Expo Turbo capability manifest must be valid JSON"
+      end
+
+      def validate_manifest_modules!(modules)
+        unless modules.is_a?(Array)
+          raise ConfigurationError, "Expo Turbo capability manifest requires a module list"
+        end
+
+        names = {}
+        modules.each do |component_module|
+          unless component_module.is_a?(Hash) &&
+              component_module["name"].is_a?(String) &&
+              !component_module["name"].strip.empty? &&
+              component_module["version"].is_a?(String) &&
+              !component_module["version"].strip.empty?
+            raise ConfigurationError, "Expo Turbo capability manifest modules require names and versions"
+          end
+          if names.key?(component_module["name"])
+            raise ConfigurationError, "Expo Turbo capability manifest contains a duplicate module"
+          end
+
+          names[component_module["name"]] = true
+        end
+      end
+
+      def normalize_manifest_components(component_entries)
+        unless component_entries.is_a?(Array)
+          raise ConfigurationError, "Expo Turbo capability manifest requires a component list"
+        end
+
+        component_entries.each_with_object({}) do |component, components|
+          unless component.is_a?(Hash) && component["tag"].is_a?(String) && component["aliases"].is_a?(Array)
+            raise ConfigurationError, "Expo Turbo capability manifest components require tags and aliases"
+          end
+          unless component["aliases"].all? { |alias_name| alias_name.is_a?(String) }
+            raise ConfigurationError, "Expo Turbo capability manifest aliases must be strings"
+          end
+
+          attributes = component["attributes"]
+          unless attributes.is_a?(Array) &&
+              attributes.all? { |attribute| attribute.is_a?(Hash) && attribute["name"].is_a?(String) && !attribute["name"].empty? }
+            raise ConfigurationError, "Expo Turbo capability manifest components require attribute names"
+          end
+          attribute_names = attributes.map { |attribute| attribute["name"] }
+          if attribute_names.uniq.length != attribute_names.length
+            raise ConfigurationError, "Expo Turbo capability manifest contains duplicate attributes"
+          end
+          if components.key?(component["tag"])
+            raise ConfigurationError, "Expo Turbo capability manifest contains a duplicate component"
+          end
+
+          components[component["tag"]] = {
+            aliases: component["aliases"],
+            style_tokens: attribute_names.include?("style-tokens")
+          }
+        end
+      end
+
       def normalize_components(components)
         raise ConfigurationError, "Expo Turbo template capabilities require a component map" unless components.is_a?(Hash)
 

data/lib/expo_turbo/rails/version.rb

@@ -2,6 +2,6 @@
 
 module ExpoTurbo
   module Rails
-    VERSION = "0.1.3"
+    VERSION = "0.1.4"
   end
 end

data/lib/expo_turbo/rails.rb

@@ -7,8 +7,10 @@ require "turbo-rails"
 
 require_relative "rails/version"
 require_relative "rails/protocol"
+require_relative "rails/route_constraint"
 require_relative "rails/errors"
 require_relative "rails/template_capabilities"
+require_relative "rails/attributes/helper"
 require_relative "rails/frames"
 require_relative "rails/frames/helper"
 require_relative "rails/dom_ids"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expo_turbo-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - NoScrubs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -120,6 +120,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/expo_turbo/rails.rb
+- lib/expo_turbo/rails/attributes/helper.rb
 - lib/expo_turbo/rails/cable.rb
 - lib/expo_turbo/rails/cable/configuration.rb
 - lib/expo_turbo/rails/cable/connection.rb
@@ -133,6 +134,7 @@ files:
 - lib/expo_turbo/rails/frames.rb
 - lib/expo_turbo/rails/frames/helper.rb
 - lib/expo_turbo/rails/protocol.rb
+- lib/expo_turbo/rails/route_constraint.rb
 - lib/expo_turbo/rails/streams.rb
 - lib/expo_turbo/rails/streams/broadcast_job.rb
 - lib/expo_turbo/rails/streams/helper.rb