ratalada-contrib 3.1.3 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd4a7fbadabdbb7170fe43f3a2c5b95c5c48f3ff3922f85c54fc00e0a4c9adc6
-  data.tar.gz: '0100897c369bb0855515dad4ec9b9c169dcf7a35430283cb51fd81ea3941fbf0'
+  metadata.gz: 573d68187596b59f3cffc50dea8b7388b476d51642dbd5590c13ab9ae9c032a1
+  data.tar.gz: 777d49ac4d40319da47e24b2f92e3627b6ff69396aba7051fcbeb579d4023107
 SHA512:
-  metadata.gz: 0eab446bf859b69de75f4c1ee0963eaff5751c1ab50adefbb0a2df43c959155222f635ffe99e98fac3c686c9008d41a613659212d77245b6922eb58989fff17e
-  data.tar.gz: a470f4628f5e8de7ff27fde72d1b03e0a83161ab213df976f2f60d6ab0cf82c364b8e2e2e1796ef054e21b1c3336ea34a9d9a3b3602283d8a4d8d078791ad094
+  metadata.gz: 20f45f1748cbaff125996e822255ac91d467cbb79c62d016866e0d24788f2b61cd7f36b2f4b6afa7046346f1b4848eaa178a312ef786b07f3bce46fb67a2e629
+  data.tar.gz: 01f40c238089497d6d2bae340c6ceb1cd886ab305864bb1d40c0b7f74086e9010b9cc6cbd35fc1403fe53c400ee8ffaae45a1e999b074074a5787c0e72b53079

data/lib/ratalada/contrib/inertia/core_ext.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# The gem's PropsResolver is plain Ruby except for three ActiveSupport core
-# extensions it calls on every resolve. We don't load ActiveSupport, so here
-# they are, AS-compatible.
+# Three ActiveSupport extensions PropsResolver needs, since we don't load it.
 class Object
   def try(method_name, ...) = respond_to?(method_name) ? public_send(method_name, ...) : nil
 

data/lib/ratalada/contrib/inertia/helpers.rb

@@ -114,8 +114,11 @@ module Ratalada
           request.env["ratalada.inertia.csrf_token"]
         end
 
-        # The prop factories are the gem's (Ratalada::Contrib::Inertia delegates to
-        # InertiaRails).
+        # The prop factories are the gem's.
+        #
+        # @parameter value [Object] a literal value, if any.
+        # @parameter block [Proc] evaluated lazily, if given.
+        # @returns [Object] the InertiaRails prop.
         def always(value = nil, &block) = Ratalada::Contrib::Inertia.always(value, &block)
         def defer(group: "default", &block) = Ratalada::Contrib::Inertia.defer(group: group, &block)
         def optional(&block) = Ratalada::Contrib::Inertia.optional(&block)

data/lib/ratalada/contrib/inertia/json_params_middleware.rb

@@ -5,8 +5,7 @@ require "json"
 module Ratalada
   module Contrib
     module Inertia
-      # The Inertia client posts JSON, which Sinatra does not read into `params`.
-      # This parses the body into the hash Rack::Request builds `params` from.
+      # Parses the JSON Inertia posts, which Sinatra ignores, into `params`.
       class JsonParamsMiddleware
         def initialize(app) = @app = app
 

data/lib/ratalada/contrib/inertia/middleware.rb

@@ -3,11 +3,7 @@
 module Ratalada
   module Contrib
     module Inertia
-      # Rack middleware for the Inertia protocol. Mirrors
-      # InertiaRails::Middleware but built on plain Rack rather than
-      # ActionDispatch — the gem's version also manages its Rails flash and
-      # session keys, which this app does not use (errors live in
-      # session[:_inertia_errors] and are swept by the render helpers).
+      # Rack middleware for the Inertia protocol, on plain Rack.
       class Middleware
         INERTIA_HEADER = "HTTP_X_INERTIA"
         INERTIA_VERSION_HEADER = "HTTP_X_INERTIA_VERSION"
@@ -27,14 +23,12 @@ module Ratalada
             status, headers, body = convert_to_location_response!(headers, body)
           end
 
-          # Only 301/302 are rewritten to 303: a 303 already forces a GET on
-          # follow, and 307/308 preserve the request method by design.
+          # Only 301/302 become 303; 307/308 preserve the method by design.
           if inertia_non_get_redirect?(env, status)
             status = 303
           end
 
-          # A response with X-Inertia-Location is already a full page visit —
-          # nothing to refresh.
+          # X-Inertia-Location is already a full page visit; nothing to refresh.
           if stale_inertia_get?(env) && !headers["X-Inertia-Location"]
             force_refresh(env)
           else
@@ -44,9 +38,12 @@ module Ratalada
 
         private
 
-          # XHR follows redirects transparently, so a cross-origin target is only
-          # reachable through a window.location visit (409 + X-Inertia-Location).
-          # 307/308 are excluded: a full page visit is always a GET.
+          # Whether a redirect crosses origins, which needs a full visit.
+          #
+          # @parameter env [Hash] the rack env.
+          # @parameter status [Integer] the response status.
+          # @parameter headers [Hash] the response headers.
+          # @returns [Boolean] true for a cross-origin redirect.
           def external_redirect?(env, status, headers)
             inertia_request?(env) &&
               REDIRECT_STATUSES.include?(status) &&
@@ -70,8 +67,11 @@ module Ratalada
             false
           end
 
-          # Mutates the headers in place to keep the rest of the response,
-          # notably Set-Cookie (which matters mid-OAuth).
+          # Mutates the headers in place, keeping Set-Cookie.
+          #
+          # @parameter headers [Hash] the response headers.
+          # @parameter body [Object] the response body, closed here.
+          # @returns [Array] a 409 with the Inertia-Location header.
           def convert_to_location_response!(headers, body)
             headers["X-Inertia-Location"] = headers.delete("Location")
             headers.delete("Content-Type")

data/lib/ratalada/contrib/inertia/response.rb

@@ -5,11 +5,7 @@ require "json"
 module Ratalada
   module Contrib
     module Inertia
-      # Builds the Inertia page object for a render. Shared data is deep-merged
-      # under the page props and errors are merged on top; prop resolution —
-      # partial reloads, deferred/optional/merge/once/scroll metadata — is the
-      # gem's PropsResolver, evaluating blocks in the request context via the
-      # gem's PropEvaluator.
+      # Builds the Inertia page object for a render.
       class Response
         attr_reader(
           :component,

data/lib/ratalada/contrib/inertia.rb

@@ -49,8 +49,10 @@ module Ratalada
       def cache(...) = ::InertiaRails::CachedProp.new(...)
       def scroll(metadata = nil, **options, &block) = ::InertiaRails::ScrollProp.new(metadata: metadata, **options, &block)
 
-      # Registers a shared-prop block, run in the request context on every
-      # inertia render and deep-merged under the page props.
+      # Registers a shared-prop block, run on every inertia render.
+      #
+      # @parameter block [Proc] produces the shared props, called in the request context and deep-merged under the page props.
+      # @returns [Array] the registered share blocks.
       def share(&block)
         unless block
           raise ArgumentError, "share requires a block"
@@ -61,10 +63,11 @@ module Ratalada
 
       def share_props(&block) = share(&block)
 
-      # The asset version sent with every page object. An app-defined
-      # page_version setting wins over inertia_version; either may be
-      # callable, and whatever comes out is stringified.
+      # The asset version sent with every page object.
+      #
+      # @returns [String] the configured version, stringified.
       def current_version
+        # page_version wins over inertia_version; either may be callable.
         config = Ratalada.config
         if config.respond_to?(:page_version)
           version = config.page_version
@@ -82,7 +85,7 @@ unless defined?(::Inertia)
   ::Inertia = Ratalada::Contrib::Inertia
 end
 
-# Contrib settings, registered on the core config exactly like the core's own.
+# Contrib settings, registered on the core config.
 Ratalada.setting :inertia_version, default: "1"
 Ratalada.setting :inertia_layout, default: :layout
 Ratalada.setting :inertia_encrypt_history, default: false

data/lib/ratalada/contrib/router/file_based/expo.rb

@@ -16,11 +16,10 @@ module Mustermann
     NOT_FOUND = "+not-found"
     NOT_FOUND_CAPTURE = "unmatched"
 
-    # Turns an Expo Router file path into the route it serves: file extensions
-    # and the +api suffix are dropped, a _layout file stands for its directory,
-    # group segments are invisible and a trailing index is its directory.
-    # Mirrors getContextKey/stripInvisibleSegmentsFromPath in expo-router.
-    # @!visibility private
+    # Turns an Expo Router file path into its route.
+    #
+    # @parameter string [String] the file path, relative to the route root.
+    # @returns [String] the route it serves.
     def self.route(string)
       string   = string.sub(%r{\A(?:\.\.?/|/)+}, "")
       string   = string.sub(/(\+api)?\.rb$/, "").sub(%r{/?_layout$}, "")

data/lib/ratalada/contrib/router/file_based/grape_adapter.rb

@@ -8,8 +8,7 @@ module Ratalada
   module Contrib
     module Router
       module FileBased
-        # Teaches Grape `route_prefix`, the same way as Sinatra: the paths of
-        # every route defined while it is set hang off it.
+        # Teaches Grape `route_prefix`, as Sinatra does.
         module GrapeAdapter
           def route(methods, paths = ["/"], route_options = {}, &block)
             unless route_prefix.to_s.empty?

data/lib/ratalada/contrib/router/file_based/hanami_adapter.rb

@@ -8,9 +8,7 @@ module Ratalada
   module Contrib
     module Router
       module FileBased
-        # Teaches Hanami::API `route_prefix`. Hanami's router already carries a
-        # path prefix — it is what `scope` sets for the length of its block —
-        # so this is that, set until the next file.
+        # Teaches Hanami::API `route_prefix`, via its router's path prefix.
         module HanamiAdapter
           def route_prefix=(prefix)
             @router.instance_variable_set(:@path_prefix, ::Hanami::Router::Prefix.new("/").join(prefix.to_s))

data/lib/ratalada/contrib/router/file_based/sinatra_adapter.rb

@@ -8,37 +8,19 @@ module Ratalada
   module Contrib
     module Router
       module FileBased
-        # Teaches Sinatra `route_prefix`: every route defined while it is set
-        # hangs off it, which is how a route file's own `get "/members"` lands
-        # under the prefix its path spelled.
+        # Teaches Sinatra `route_prefix`.
         module SinatraAdapter
-          # Expo spelling, kept all the way to the pattern. Sinatra's own
-          # syntax has no way to say `[user-id]`: `:user-id` reads as the
-          # capture `user` followed by the literal `-id`, so a hyphenated
-          # parameter silently routes nowhere. Mustermann::Expo is the pattern
-          # the file path already is.
+          # Expo spelling, kept to the pattern: Sinatra cannot spell `[user-id]`.
+          # `:user-id` reads as capture `user` then literal `-id`, routing nowhere.
           SPELLING = {placeholder: "[%s]", catch_all: "[...%s]"}.freeze
 
           def route_spelling = SPELLING
 
-          # ONE APP PER ROUTE FILE, NOT ONE FOR THE TREE. `use`, `set`, `before`,
-          # `error` and `helpers` are all class-level Sinatra DSL, so evaluating
-          # every file into a single Sinatra::Base makes a _layout.rb reach files
-          # it does not sit above: an app/(api)/_layout.rb with
-          # `before { content_type(:json) }` relabels every HTML page in the tree.
-          # A layout is meant to scope those to its own subtree, which it can only
-          # do if the files under it have a class of their own.
+          # Gives each route file a Sinatra subclass, chained as middleware.
           #
-          # So each route file (with the layouts above it) becomes its own
-          # subclass, and they are chained: a Sinatra app used as rack middleware
-          # forwards the request on when none of its own routes matched
-          # (Base#route_missing), so the first file that spells the path answers
-          # and the rest fall through. build_map already orders them
-          # most-specific-first.
-          #
-          # ponytail: one middleware hop per route file, walked per request.
-          # Collapse the leaves into one class if a fat tree ever shows up in a
-          # profile -- the isolation is the point, not the chain.
+          # @parameter parent [Class] the app the subclasses mount on.
+          # @parameter map [Hash] route prefix => the files under it.
+          # @returns [void]
           def mount_files(parent, map)
             map.each do |prefix, paths|
               child = Class.new(::Sinatra::Base)

data/lib/ratalada/contrib/router/file_based.rb

@@ -12,16 +12,16 @@ module Ratalada
 
         module_function
 
-        # Evaluates every route file in the directory into an app class, under
-        # the prefix its path spells. That class is the frontend's own, so this
-        # is what a Server.run block calls: the block is already being evaluated
-        # into it, and `self` is it. Requiring the frontend's adapter is what
-        # teaches the class `route_prefix`.
+        # Evaluates every route file under the directory into the app.
         #
+        # @example
         #   Server.run { Ratalada::Contrib::Router::FileBased.mount(self, "app") }
+        #
+        # @parameter app [Object] the frontend app class.
+        # @parameter directory [String] the route file root.
+        # @returns [void]
         def mount(app, directory)
-          # The adapter says how its frontend spells a placeholder; the default
-          # is `:name`, which is what hanami and grape read.
+          # The adapter spells placeholders; `:name` suits hanami and grape.
           if app.respond_to?(:route_spelling)
             spelling = app.route_spelling
           else
@@ -30,10 +30,8 @@ module Ratalada
 
           map = build_map(directory, **spelling)
 
-          # An adapter that can give each route file its own class does, so a
-          # _layout.rb's `use`, `set`, `before` and `error` reach only the files
-          # below it. Without that the whole tree shares one class and a nested
-          # layout's filter fires for every route in the app.
+          # Per-file classes where the adapter can, so `_layout.rb` scopes downward.
+          # One shared class makes a nested layout's filter fire everywhere.
           if app.respond_to?(:mount_files)
             app.mount_files(app, map)
           else
@@ -44,21 +42,25 @@ module Ratalada
           end
         end
 
-        # The same, as a whole app built by whichever Ratalada frontend is in
-        # use — for mounting a directory somewhere other than the server's own
-        # run block.
+        # Builds a whole app from the directory, for mounting elsewhere.
+        #
+        # @parameter directory [String] the route file root.
+        # @returns [Object] the built app.
         def build(directory)
           Ratalada.frontend.build(proc { FileBased.mount(self, directory) })
         end
 
-        # A hash of route => the files that serve it, ordered most specific
-        # first. Mustermann::Expo does the file path => route translation; all
-        # this adds is which files to evaluate and how the adapter spells a
-        # placeholder.
+        # Route => the files that serve it, most specific first.
+        #
+        # @example
+        #   {
+        #     "/organisations/:id/edit" => ["./app/organisations/[id]/edit.rb"]
+        #   }
         #
-        # {
-        #   "/organisations/:id/edit" => ["./app/organisations/[id]/edit.rb"]
-        # }
+        # @parameter directory [String] the route file root.
+        # @parameter placeholder [String] the adapter's placeholder spelling.
+        # @parameter catch_all [String] the adapter's catch-all spelling.
+        # @returns [Hash] route => files.
         def build_map(directory, placeholder: ":%s", catch_all: "*%s")
           root = File.expand_path(directory)
 
@@ -81,8 +83,12 @@ module Ratalada
             .push(File.join(root, relative))
         end
 
-        # An expo route in the adapter's own spelling: "/teams/[team]" => "/teams/:team".
-        # The root route is "" — a prefix nothing hangs off, not a route of "/".
+        # An expo route in the adapter's own spelling.
+        #
+        # @parameter route [String] the expo route.
+        # @parameter placeholder [String] the adapter's placeholder spelling.
+        # @parameter catch_all [String] the adapter's catch-all spelling.
+        # @returns [String] the adapter's route.
         def spell(route, placeholder, catch_all)
           route.delete_suffix("/").gsub(%r{\[(\.\.\.)?([^\[\]/]+)\]}) do
             format(Regexp.last_match(1) ? catch_all : placeholder, Regexp.last_match(2))
@@ -93,11 +99,10 @@ module Ratalada
           "#{prefix}#{route.delete_suffix("/")}".sub(/\A\z/, "/")
         end
 
-        # Least specific last. A segment that is PARTLY literal beats a bare
-        # capture: `[index].[diffType]` and `[index]` both match "7.diff", and
-        # the one that spells the dot is the one that means it -- so the
-        # patterns are anchored to a single capture rather than to the whole
-        # segment, which `[index].[diffType]` would also satisfy.
+        # How specific a route is, as per-segment weights.
+        #
+        # @parameter route [String] the route path.
+        # @returns [Array(Integer)] the segment weights, least specific last.
         def specificity(route)
           route.split("/").drop(1).map do |segment|
             case segment

data/lib/ratalada/contrib/version.rb

@@ -2,6 +2,6 @@
 
 module Ratalada
   module Contrib
-    VERSION = "3.1.3"
+    VERSION = "4.0.1"
   end
 end

data/lib/ratalada/contrib/vite.rb

@@ -3,11 +3,9 @@ require "vite_ruby"
 module Ratalada
   module Contrib
     module Vite
-      # Rack middleware that fronts the app with vite's dev-server proxy while
-      # `bin/vite dev` is running, and is a pass-through otherwise (production,
-      # or a build served from the manifest). The decision is ViteRuby's
-      # `run_proxy?`, read once at boot like any other `Server.use` argument.
+      # Rack middleware that fronts the app with vite's dev-server proxy.
       #
+      # @example
       #   Server.use(Ratalada::Contrib::Vite::DevServerProxy).run { ... }
       class DevServerProxy
         def initialize(app, ssl_verify_none: true)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratalada-contrib
 version: !ruby/object:Gem::Version
-  version: 3.1.3
+  version: 4.0.1
 platform: ruby
 authors:
 - Nathan K
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: mustermann
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +37,20 @@ dependencies:
     - - ">"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: inertia_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.22.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.22.0
 description: |
   Optional add-on modules for ratalada that do not belong in the core gem.
   Require only the ones you use; each pulls its own framework (the