turbo-router 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ec701744c6e0f0e21aba83ec1e1700fa83dcba61626adffc6807d5a12eb9431
+  data.tar.gz: 3b8e7651774273b3cb4a13ef9e8ac1d368c1f835e9256b6aee4c30b1962e18c8
+SHA512:
+  metadata.gz: 2b0b72a73917ae1f3be77ca7a8ed986cfb712020b4dabb91d92f095d82368bac599cf3fd708d5227e38ffe3555bd22184162c599c153ad8a2ee0f95636420e60
+  data.tar.gz: f9e46336505575c37e4b06e28eb9bd30e481d785235893b4aef4e27332a167444349074869b5932804906629831b0747acccc781232b5ff2c40958fd0da85771

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Bryant Morrill
+
+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,115 @@
+# TurboRouter
+
+TurboRouter is a simple Rails plugin that smooths over some of the complexity and inconsistencies of using turbo-frames. For example, it can be a bit frustrating to understand or predict how turbo enabled links will behave, especially when you are just learning how to use them. This is because they can have several different attributes that can change their behavior, and their location in the context of the DOM can also change what they do.
+
+To make things just a little easier, TurboRouter provides a handfull of straightforward view helpers that wrap the standard Rails `link_to` helper and set the proper attributes on the links they generate so they will have a consistant and predictable behavior, regardless of where they are in the DOM and without the need to set different attributes. They also make it more straightforward to know when the browser's history will be advanced, and when it will not be.
+
+Another aspect of turbo_frames that TurboRouter remedies is the fact that you need to wrap the HTML templates rendered back from your controllers with a turbo_frame matching the part of the DOM you wish to replace. Doing this may limit the reusability and flexibility of your templates, and it is extra boiler plate code that can easily be abstracted away. TurboRouter does this by rendering your templates with a layout with a dynamic id set to match the targeted turbo_frame of the request, so the partials always render with the proper turbo_frame wrapper. This behavior is, of course, opt-in for each controller action, so that you are not forced to use the dynamic template when you do not what to, but it is there when you need it.
+
+TurboRouter establishes a baseline for turbo enabled links by wrapping the `<%= yield %>` in your `application.html.erb` with a turbo_frame (using a partial) with `id="turbo_router_content"`. By default, links generated by TurboRouter view helpers that don't target the entire page, will target this turbo_frame. Of course, you can set the `data-turbo-frame` attribute on these links just as you would with `link_to` to target a different turbo_frame instead.
+
+TurboRouter also provides a method to your controllers for rendering a turbo_stream that targets the default turbo_frame, but can accept a different `id` as well
+
+In short, TurboRouter turns the following table:
+
+<img width="1134" alt="Screen Shot 2022-02-24 at 8 47 24 PM" src="https://user-images.githubusercontent.com/11528362/155743029-4888afbf-847c-44b2-98ab-e4b7a50f2197.png">
+
+Into this:
+
+<img width="1133" alt="Screen Shot 2022-02-24 at 8 47 38 PM" src="https://user-images.githubusercontent.com/11528362/155743143-b3159932-1877-4a98-905f-b56a84b5dca0.png">
+
+The above tables may not look that different, and they are not. This plugin simply provides a slightly different API that is more imperative and requires setting fewer attributes yourself and less boiler plate code in your templates. It certainly isn't necessary, but it might be nice to have for those that find it useful.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "turbo-router"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Then run:
+```bash
+rails generate turbo_router
+```
+
+The above command will create the following files in your app:
+
+* app/views/layouts/_turbo_router_content.erb
+* app/views/layouts/turbo_router_content.erb
+
+The above command will also wrap the `yield` call in `application.html.erb` with the `layouts/turbo_router_content` partial layout like so:
+
+```ruby
+  <%= render "layouts/turbo_router_content" do %><%= yield %><% end %>
+```
+
+The above layout ultimately wraps its contents with a turbo frame with `id="turbo_router_content"` which will serve as the target for all TurboRouter navigations that do not target the full page.
+
+## Usage
+
+### Controllers
+Simply add this line to your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include TurboRouter::Controller
+```
+
+For any actions you wish to render using the dynamic turbo_frame template, simply call `use_dynamic_layout` and pass those actions to it like so:
+
+```ruby
+  use_dynamic_layout :index, :show
+```
+
+When an action is passed to `use_dynamic_layout` and when requests are turbo_frame requests (`turbo_frame_request?` returns `true`), the layout rendered will wrap the template in a turbo_frame with the id matching `request.headers["Turbo-frame"]`. This is always the same value that is set on the `data-turbo-frame` attribute on the link that initiated the request (or the containing turbo_frame's id if not set). TurboRouter view helpers ensure that this value is always set to either `turbo_router_content` if it isn't already set.
+
+By default, if a request does not use the dynamic layout, the application layout will be used.
+
+Because TurboRouter sets the controller's layout to use its dynamic layout for turbo_frame requests, it is incompatible with setting a different static/ global layout for a controller for other types of requests (turbo-rails also has this problem, but offers no solution). TurboRouter, however, allows you to set a layout for all requests that are not turbo_frame requests without interfering with the dynamic layout behavior using the `page_layout` method, like so:
+
+```ruby
+class ChaptersController < ApplicationController
+  page_layout :other_layout
+```
+
+Of course, you are still able to set a layout more granularly with individual calls to render by passing a layout parameter, in which case the provided layout will override any layout that was determined by other means.
+
+TurboRouter provides an additional method for controllers, `turbo_router_stream`, which simply reduces the amount of boilerplat code you have to write to render a turbo_stream. It takes a template as it's first argument, and an optional id for the target element which defaults to `turbo_router_content` if not provided, and any other options to be passed to as locals to the render call. Use it like so:
+
+```ruby
+    respond_to do |format|
+      format.turbo_stream do
+        turbo_router_stream "posts/show", "post_container", post: @post
+      end
+    end
+```
+
+### View Helpers
+
+The view helper TurboRouter provides are:
+
+* `turbo_router_load_to`
+* `turbo_router_link_to`
+* `turbo_router_render_to`
+* `turbo_router_route_to`.
+
+The helpers `turbo_router_load_to` and `turbo_router_link_to` both target the entire page, but the former performs a full page load without using TurboDrive, while the latter utilizes TurboDrive (under the hood it uses `data-turbo-frame="_top"`). Both of these links will advance the browser's history.
+
+The helpers `turbo_router_render_to` and `turbo_router_route_to` both target a turbo_frame (either the default turbo_frame with `id="turbo_router_content"` or a different one specified with `data-turbo-frame`), but the former does not advance the browser's history while the latter does.
+
+All of the view helpers have take the same signature as `link_to` so you may still pass any other attributes such as `class` or other `data` attributes as well (certain data attributes will be overridend to achieve the required behavior). This means they can directly replace any `link_to` calls you have in your views and they will continue to work as expected in all other ways, but with the more imperatively determined behavior described above.
+
+## Contributing
+### This plugin is currently in it's alpha stage and contributors are welcome!
+
+Things that need to be done:
+
+* Add helpers for button_to perhaps.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/generators/templates/_turbo_router_content.erb

@@ -0,0 +1,3 @@
+<%= turbo_frame_tag(turbo_router_frame_id_for_request, **turbo_router_frame_options) do %>
+  <%= yield %>
+<% end %>

data/lib/generators/templates/turbo_router_content.erb

@@ -0,0 +1,3 @@
+<%= render "layouts/turbo_router_content" do %>
+  <%= yield %>
+<% end %>

data/lib/generators/turbo_router_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class TurboRouterGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  desc "This generator copies the required templates along with helpful view helpers into your app."
+  def copy_turbo_router_content_partial
+    copy_file "_turbo_router_content.erb", "app/views/layouts/_turbo_router_content.erb"
+  end
+
+  def copy_turbo_router_content_template
+    copy_file "turbo_router_content.erb", "app/views/layouts/turbo_router_content.erb"
+  end
+
+  def wrap_yield_call_in_application_template
+    gsub_file "app/views/layouts/application.html.erb", /(<%=\s*yield\s*%>)/, "<%= render \"layouts/turbo_router_content\" do %>\\1<% end %>"
+  end
+end

data/lib/tasks/turbo_router_tasks.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# desc "Explaining what the task does"
+# task :turbo_router do
+#   # Task goes here
+# end

data/lib/turbo-router.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "turbo_router/version"
+require "turbo_router/controller"
+require "turbo_router/view_helpers"
+require "turbo_router/railtie" if defined?(Rails)
+
+module TurboRouter
+end

data/lib/turbo_router/controller.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module TurboRouter
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      layout lambda {
+        use_dynamic_layout? ? "layouts/turbo_router_content" : self.class.page_layout
+      }
+
+      before_action :set_turbo_frame_request_variant
+      helper_method :turbo_router_frame_options
+      helper_method :turbo_router_frame_id_for_request
+    end
+
+    class_methods do
+      def page_layout(layout = nil)
+        @page_layout ||= "application"
+        @page_layout = layout if layout.present?
+        @page_layout
+      end
+
+      def use_dynamic_layout(*actions)
+        @dynamic_layout_actions = actions if actions.present?
+      end
+
+      def dynamic_layout_actions
+        @dynamic_layout_actions ||= []
+        @dynamic_layout_actions
+      end
+    end
+
+    def use_dynamic_layout?
+      turbo_frame_request? && self.class.dynamic_layout_actions&.include?(params[:action].to_sym)
+    end
+
+    def turbo_router_stream(template, id = :turbo_router_content, **options)
+      render turbo_stream: turbo_stream.replace(id, template: template, locals: options)
+    end
+
+    def turbo_router_frame_options
+      @turbo_router_advance ? { turbo_action: "advance", target: request.headers["Turbo-frame"] } : {}
+    end
+
+    def turbo_router_frame_id_for_request
+      request.headers["Turbo-frame"].present? ? request.headers["Turbo-frame"] : "turbo_router_content"
+    end
+
+    private
+
+    def set_turbo_frame_request_variant
+      request.variant = if turbo_frame_request?
+                          :turbo_frame
+                        else
+                          :page
+                        end
+    end
+  end
+end

data/lib/turbo_router/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TurboRouter
+  class Railtie < Rails::Railtie
+    initializer "turbo_router.view_helpers" do
+      ActiveSupport.on_load(:action_view) { include TurboRouter::ViewHelpers }
+    end
+  end
+end

data/lib/turbo_router/version.rb

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

data/lib/turbo_router/view_helpers.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TurboRouter
+  module ViewHelpers
+    def turbo_router_load_to(name = nil, options = nil, html_options = nil, &block)
+      new_html_options = block_given? ? options : html_options
+      new_html_options ||= {}
+      new_html_options[:data] ||= {}
+      new_html_options[:data][:turbo] = false
+      block_given? ? link_to(name, new_html_options, nil, &block) : link_to(name, options, new_html_options, &block)
+    end
+
+    def turbo_router_link_to(name = nil, options = nil, html_options = nil, &block)
+      new_html_options = block_given? ? options : html_options
+      new_html_options ||= {}
+      new_html_options[:data] ||= {}
+      new_html_options[:data][:turbo_frame] = "_top"
+      block_given? ? link_to(name, new_html_options, nil, &block) : link_to(name, options, new_html_options, &block)
+    end
+
+    def turbo_router_render_to(name = nil, options = nil, html_options = nil, &block)
+      new_html_options = block_given? ? options : html_options
+      new_html_options ||= {}
+      new_html_options[:data] ||= {}
+      new_html_options[:data][:turbo_frame] ||= :turbo_router_content
+      block_given? ? link_to(name, new_html_options, nil, &block) : link_to(name, options, new_html_options, &block)
+    end
+
+    def turbo_router_route_to(name = nil, options = nil, html_options = nil, &block)
+      new_html_options = block_given? ? options : html_options
+      new_html_options ||= {}
+      new_html_options[:data] ||= {}
+      new_html_options[:data][:turbo_frame] ||= :turbo_router_content
+      new_html_options[:data][:turbo_action] = "advance"
+      block_given? ? link_to(name, new_html_options, nil, &block) : link_to(name, options, new_html_options, &block)
+    end
+  end
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: turbo-router
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Bryant Morrill
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-03-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.2.2
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails-controller-testing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+description: TurboRouter makes it easier to use turbo_frames by dynamically wrapping
+  responses with turbo_frames and providing view helpers to generate links with predictable
+  and straightforward behavior.
+email:
+- bryantreadmorrill@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/generators/templates/_turbo_router_content.erb
+- lib/generators/templates/turbo_router_content.erb
+- lib/generators/turbo_router_generator.rb
+- lib/tasks/turbo_router_tasks.rake
+- lib/turbo-router.rb
+- lib/turbo_router/controller.rb
+- lib/turbo_router/railtie.rb
+- lib/turbo_router/version.rb
+- lib/turbo_router/view_helpers.rb
+homepage: https://github.com/WriterZephos/turbo-router
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/WriterZephos/turbo-router
+  source_code_uri: https://github.com/WriterZephos/turbo-router
+  changelog_uri: https://github.com/WriterZephos/turbo-router
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: TurboRouter - turbo_frames and turbo_streams made easy.
+test_files: []