turbo_frame_src 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d98ef71bdc867a5320038121e1e22c6e458515019ddfd8d708ff726cb60e2c7c
+  data.tar.gz: '028d11c82757191c3890e0ee5b4165960944bcb0d28e196b9743cba75567d9fd'
+SHA512:
+  metadata.gz: ad5d603d63c04211ea15272a2e898f5174a3cbfb09c8e5da9815bd39e0bca155efc6497be52da77ac2f030424e383c26709a773d32e32a42b4c52ab5b4c52eb4
+  data.tar.gz: 75b733317f1c3c992be17d0625e08c09aacea395afcfb6ddaca32cc2b2970db38ba6691adb730866c233945bc0bd0cb72d61b48eef18a785f7c1e30a0d509368

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-13
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"turbo_frame_src" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["alexis.crozier@spendhq.com"](mailto:"alexis.crozier@spendhq.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexis Crozier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# TurboFrameSrc
+
+`TurboFrameSrc` gives your Rails app back a piece of information Turbo doesn't expose natively: **the original `src` of the turbo-frame that triggered the current request.**
+
+## The problem
+
+Imagine a common Hotwire pattern: a lazy-loaded `turbo-frame` renders a filterable, paginated collection.
+
+```erb
+<%= turbo_frame_tag "orders", src: orders_path %>
+```
+
+Filtering is implemented once, generically, through a shared concern (e.g. a `Filterable` concern included in several controllers). That concern also exposes a generic `reset_filters` action so users can clear the filters that apply to whatever controller/action they're currently on — without wiping out unrelated filters living elsewhere on the page.
+
+To reset the filters "in place" and re-render the same frame, that generic action needs to know **which URL originally loaded the frame** (`orders_path`, in the example above) so it can redirect or respond with the right content. Turbo does not give you this for free:
+
+- The current request's URL is the *action's* URL (e.g. `/orders/reset_filters`), not the frame's original `src`.
+- The `Turbo-Frame` request header only tells you *which frame* is requesting the update, not what URL it was first loaded from.
+
+Once your filters are reset, you're stuck without knowing where to send the user back to.
+
+## The solution
+
+`TurboFrameSrc` tracks each turbo-frame's initial `src` on the client, forwards it as a request header on every subsequent Turbo Frame fetch, and echoes it back so your Rails controllers/views can read it at any point in the request cycle — including from a generic, shared action like `reset_filters`.
+
+```ruby
+class FiltersController < ApplicationController
+  include Filterable
+
+  def reset_filters
+    reset_filters_for(params[:scope])
+
+    redirect_to turbo_frame_src
+  end
+end
+```
+
+```erb
+<%= turbo_frame_tag "orders", src: turbo_frame_src || orders_path %>
+```
+
+## How it works
+
+1. **JavaScript** listens for Turbo's `turbo:before-fetch-request` event. The first time a given `turbo-frame` fires a request, its current `src` (or the page URL, if it has none yet) is stashed in a `data-initial-src` attribute on the frame element, then sent as the `X-Turbo-Frame-Src` request header on this and every following fetch initiated by that frame.
+2. **Rack middleware** (`TurboFrameSrc::Middleware`) reads the incoming `X-Turbo-Frame-Src` header (only for requests that also carry Turbo's own `Turbo-Frame` header) and re-attaches it to the response headers, so it survives redirects and stays available across the request/response cycle.
+3. **A view/controller helper**, `turbo_frame_src`, reads that header back for you:
+
+```ruby
+module TurboFrameSrc::Helper
+  def turbo_frame_src
+    request.headers['X-Turbo-Frame-Src']
+  end
+end
+```
+
+Because the whole flow is generic (frame name agnostic), it works the same way no matter which lazy-loaded frame, controller, or action is involved — which is exactly what a shared/generic `reset_filters` action needs.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```bash
+bundle add turbo_frame_src
+```
+
+### Ruby / Rails side
+
+The gem ships a Rails engine. Simply requiring it (via Bundler) is enough to:
+
+- register `TurboFrameSrc::Middleware` in your middleware stack,
+- include `TurboFrameSrc::Helper` in `ActionController::Base` (available in controllers and views),
+- register the JS package path with **Importmap**, if your app uses it.
+
+### JavaScript side
+
+The client-side behavior is published to npm as `turbo_frame_src`.
+
+#### Importmap
+
+If your app uses `importmap-rails`, the engine already added the gem's JS path to the importmap. Just pin it:
+
+```bash
+bin/importmap pin turbo_frame_src
+```
+
+Then register it in your entrypoint:
+
+```js
+import "turbo_frame_src"
+```
+
+#### Yarn / npm / Vite
+
+```bash
+yarn add turbo_frame_src
+# or
+npm install turbo_frame_src
+```
+
+```js
+import { registerTurboFrameSrc } from "turbo_frame_src"
+
+registerTurboFrameSrc()
+```
+
+(Importing the package directly, without calling `registerTurboFrameSrc`, also works — the listener self-registers as soon as the module is loaded in a browser context.)
+
+## Usage
+
+Once installed, use the `turbo_frame_src` helper anywhere you have access to the current `request` — controllers, views, or a shared concern/action — to retrieve the `src` the enclosing turbo-frame was originally loaded from:
+
+```ruby
+turbo_frame_src # => "/orders?status=pending"
+```
+
+Typical use case: a generic `reset_filters` action, shared across several controllers via a concern, that needs to redirect back to whichever frame (or page) initiated the request:
+
+```ruby
+module Filterable
+  extend ActiveSupport::Concern
+
+  def reset_filters
+    session.delete(filters_session_key)
+
+    redirect_to turbo_frame_src || request.referer
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/AlexisCro/turbo_frame_src. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/AlexisCro/turbo_frame_src/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the TurboFrameSrc project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/AlexisCro/turbo_frame_src/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/javascript/turbo_frame_src/index.js

@@ -0,0 +1,18 @@
+export function registerTurboFrameSrc() {
+    document.addEventListener("turbo:before-fetch-request", (event) => {
+        const fetchOptions = event.detail.fetchOptions;
+        const targetFrame  = event.target.closest("turbo-frame");
+
+        if (targetFrame) {
+            if (!targetFrame.dataset.initialSrc) {
+                targetFrame.dataset.initialSrc = targetFrame.getAttribute("src") || window.location.href;
+            }
+
+            fetchOptions.headers["X-Turbo-Frame-Src"]  = targetFrame.dataset.initialSrc;
+        }
+    });
+}
+
+if (typeof window !== "undefined") {
+    registerTurboFrameSrc();
+}

data/lib/turbo_frame_src/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class TurboFrameSrc::Engine < ::Rails::Engine
+  isolate_namespace TurboFrameSrc
+
+  initializer "turbo_frame_src.importmap", before: "importmap" do |app|
+    if app.config.respond_to?(:importmap)
+      app.config.importmap.paths.add_gem_path "turbo_frame_src", root.join("app/javascript")
+    end
+  end
+
+  initializer "turbo_frame_src.helpers" do
+    ActiveSupport.on_load(:action_controller_base) do
+      include TurboFrameSrc::Helper
+
+      helper TurboFrameSrc::Helper
+    end
+  end
+
+  initializer "turbo_frame_src.middleware" do |app|
+    app.config.middleware.use TurboFrameSrc::Middleware
+  end
+end

data/lib/turbo_frame_src/helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TurboFrameSrc::Helper
+  def turbo_frame_src
+    request.headers['X-Turbo-Frame-Src']
+  end
+end

data/lib/turbo_frame_src/middleware.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class TurboFrameSrc::Middleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    initial_frame_src = env['HTTP_X_TURBO_FRAME_SRC'] if env['HTTP_TURBO_FRAME'].present?
+
+    status, headers, response = @app.call(env)
+
+    headers['X-Turbo-Frame-Src'] = initial_frame_src if initial_frame_src&.present?
+
+    [status, headers, response]
+  end
+end

data/lib/turbo_frame_src/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class TurboFrameSrc::Railtie < Rails::Railtie
+  initializer "turbo_frame_src.insert_middleware" do |app|
+    app.config.middleware.use TurboFrameSrc::Middleware
+  end
+end

data/lib/turbo_frame_src/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TurboFrameSrc
+  VERSION = "0.1.0"
+end

data/lib/turbo_frame_src.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "turbo_frame_src/version"
+require "turbo_frame_src/middleware"
+require "turbo_frame_src/helper"
+require "turbo_frame_src/engine" if defined?(Rails::Engine)
+
+module TurboFrameSrc
+  class Error < StandardError; end
+end

data/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "turbo_frame_src",
+  "version": "0.1.0",
+  "description": "Preserve initial Turbo Frame src during navigation",
+  "main": "app/javascript/turbo_frame_src/index.js",
+  "module": "app/javascript/turbo_frame_src/index.js",
+  "files": [
+    "app/javascript"
+  ],
+  "author": "Ton Nom",
+  "license": "MIT"
+}

data/sig/turbo_frame_src.rbs

@@ -0,0 +1,4 @@
+module TurboFrameSrc
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: turbo_frame_src
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexis Crozier
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: See https://github.com/AlexisCro/turbo_frame_src
+email:
+- alexis.crozier@spendhq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/javascript/turbo_frame_src/index.js
+- lib/turbo_frame_src.rb
+- lib/turbo_frame_src/engine.rb
+- lib/turbo_frame_src/helper.rb
+- lib/turbo_frame_src/middleware.rb
+- lib/turbo_frame_src/railtie.rb
+- lib/turbo_frame_src/version.rb
+- package.json
+- sig/turbo_frame_src.rbs
+homepage: https://github.com/AlexisCro/turbo_frame_src
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/AlexisCro/turbo_frame_src
+  source_code_uri: https://rubygems.org/
+  changelog_uri: https://github.com/AlexisCro/turbo_frame_src/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: TurboFrameSrc tracks each turbo-frame's initial src on the client, forwards
+  it as a request header on every subsequent Turbo Frame fetch, and echoes it back
+  so your Rails controllers/views can read it at any point in the request cycle —
+  including from a generic, shared action.
+test_files: []