turbo-rails 1.5.0 → 2.0.7

Sign up to get free protection for your applications and to get access to all the features.
Files changed (33) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +67 -16
  3. data/app/assets/javascripts/turbo.js +1974 -785
  4. data/app/assets/javascripts/turbo.min.js +9 -5
  5. data/app/assets/javascripts/turbo.min.js.map +1 -1
  6. data/app/channels/turbo/streams/broadcasts.rb +33 -7
  7. data/app/channels/turbo/streams_channel.rb +15 -15
  8. data/app/controllers/concerns/turbo/request_id_tracking.rb +12 -0
  9. data/app/controllers/turbo/frames/frame_request.rb +2 -2
  10. data/app/controllers/turbo/native/navigation.rb +6 -3
  11. data/app/helpers/turbo/drive_helper.rb +72 -14
  12. data/app/helpers/turbo/frames_helper.rb +8 -8
  13. data/app/helpers/turbo/streams/action_helper.rb +12 -4
  14. data/app/helpers/turbo/streams_helper.rb +5 -0
  15. data/app/javascript/turbo/index.js +2 -0
  16. data/app/jobs/turbo/streams/action_broadcast_job.rb +2 -2
  17. data/app/jobs/turbo/streams/broadcast_job.rb +1 -1
  18. data/app/jobs/turbo/streams/broadcast_stream_job.rb +7 -0
  19. data/app/models/concerns/turbo/broadcastable.rb +184 -35
  20. data/app/models/turbo/debouncer.rb +24 -0
  21. data/app/models/turbo/streams/tag_builder.rb +20 -0
  22. data/app/models/turbo/thread_debouncer.rb +28 -0
  23. data/config/routes.rb +3 -4
  24. data/lib/install/turbo_with_importmap.rb +1 -1
  25. data/lib/tasks/turbo_tasks.rake +0 -22
  26. data/lib/turbo/broadcastable/test_helper.rb +5 -5
  27. data/lib/turbo/engine.rb +34 -8
  28. data/lib/turbo/test_assertions/integration_test_assertions.rb +2 -2
  29. data/lib/turbo/test_assertions.rb +2 -2
  30. data/lib/turbo/version.rb +1 -1
  31. data/lib/turbo-rails.rb +10 -0
  32. metadata +9 -5
  33. data/lib/install/turbo_needs_redis.rb +0 -20
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 216ef0fb1d4b07f9231e52702506e6888495d7c15f07a0778eee156692c84d74
4
- data.tar.gz: 964ea9a3f3111be08955e9c707a591941dfe7b5f943566716bcd26fbd3d9b19b
3
+ metadata.gz: 4553ee49b6504b50ebd79364400cd57bcba2a4fd544aff65f88a4c5a12ffdaac
4
+ data.tar.gz: 7500ba88dc381e1601b0778c31e68be1a16ce72dcc535bbd8b54ba4eebac5d0e
5
5
  SHA512:
6
- metadata.gz: 2f42f0e27dcb80e83b3bae71416b1c9c0cdd82ef462dfa96c57bc3fa2d2c88b548785d9e7b10945575ab53538cfc0cf99c49c3c7f5d6f4fdd0608f251ae38bad
7
- data.tar.gz: 21bd467eed15705e4c46f3da62ae84d8466adc85dcd770abc837c1fbcb517ccca2d7a004f9c856bd2af1f6aed9f83df51825929de463428699a35a58c4b89846
6
+ metadata.gz: 40376048e8a552fb9ac3570e6fce78f7d0741cdab4b8d3851305fb5541f50dd381a4d9616e7c4fb147a1d58d7b546ab6d07061ac79f3851b8163605084cabc62
7
+ data.tar.gz: 85414d553bc478bf46ba0294381b09031e58949edd93d47e8f02b721a0fcb556388a5b3b20741a3011f3547fb0281d9bdbcc7e518a97df27953474ce3d012add
data/README.md CHANGED
@@ -6,12 +6,11 @@ On top of accelerating web applications, Turbo was built from the ground-up to f
6
6
 
7
7
  Turbo is a language-agnostic framework written in JavaScript, but this gem builds on top of those basics to make the integration with Rails as smooth as possible. You can deliver turbo updates via model callbacks over Action Cable, respond to controller actions with native navigation or standard redirects, and render turbo frames with helpers and layout-free responses.
8
8
 
9
-
10
9
  ## Navigate with Turbo Drive
11
10
 
12
11
  Turbo is a continuation of the ideas from the previous [Turbolinks](https://github.com/turbolinks/turbolinks) framework, and the heart of that past approach lives on as Turbo Drive. When installed, Turbo automatically intercepts all clicks on `<a href>` links to the same domain. When you click an eligible link, Turbo prevents the browser from following it. Instead, Turbo changes the browser’s URL using the History API, requests the new page using `fetch`, and then renders the HTML response.
13
12
 
14
- During rendering, Turbo replaces the current `<body>` element outright and merges the contents of the `<head>` element. The JavaScript window and document objects, and the HTML `<html>` element, persist from one rendering to the next.
13
+ During rendering, Turbo replaces the current `<body>` element outright and merges the contents of the `<head>` element. The JavaScript window and document objects, and the `<html>` element, persist from one rendering to the next.
15
14
 
16
15
  Whereas Turbolinks previously just dealt with links, Turbo can now also process form submissions and responses. This means the entire flow in the web application is wrapped into Turbo, making all the parts fast. No more need for `data-remote=true`.
17
16
 
@@ -51,13 +50,13 @@ For instance:
51
50
  <% end %>
52
51
  ```
53
52
 
54
- When the user will click on the `Edit this todo` link, as direct response to this direct user interaction, the turbo frame will be replaced with the one in the `edit.html.erb` page automatically.
53
+ When the user clicks on the `Edit this todo` link, as a direct response to this user interaction, the turbo frame will be automatically replaced with the one in the `edit.html.erb` page.
55
54
 
56
55
  [See documentation](https://turbo.hotwired.dev/handbook/frames).
57
56
 
58
57
  ### A note on custom layouts
59
58
 
60
- In order to render turbo frame requests without the application layout, Turbo registers a custom [layout method](https://api.rubyonrails.org/classes/ActionView/Layouts/ClassMethods.html#method-i-layout).
59
+ In order to render turbo frame requests without the application layout, Turbo registers a custom [layout method](https://api.rubyonrails.org/classes/ActionView/Layouts/ClassMethods.html#method-i-layout).
61
60
  If your application uses custom layout resolution, you have to make sure to return `"turbo_rails/frame"` (or `false` for TurboRails < 1.4.0) for turbo frame requests:
62
61
 
63
62
  ```ruby
@@ -65,7 +64,7 @@ layout :custom_layout
65
64
 
66
65
  def custom_layout
67
66
  return "turbo_rails/frame" if turbo_frame_request?
68
-
67
+
69
68
  # ... your custom layout logic
70
69
  ```
71
70
 
@@ -75,14 +74,14 @@ If you are using a custom, but "static" layout,
75
74
  layout "some_static_layout"
76
75
  ```
77
76
 
78
- you **have** to change it to a layout method in order to conditionally return `false` for turbo frame requests:
77
+ you **have** to change it to a layout method in order to conditionally return `"turbo_rails/frame"` for turbo frame requests:
79
78
 
80
79
  ```ruby
81
80
  layout :custom_layout
82
81
 
83
82
  def custom_layout
84
83
  return "turbo_rails/frame" if turbo_frame_request?
85
-
84
+
86
85
  "some_static_layout"
87
86
  ```
88
87
 
@@ -110,9 +109,8 @@ This gem is automatically configured for applications made with Rails 7+ (unless
110
109
  1. Add the `turbo-rails` gem to your Gemfile: `gem 'turbo-rails'`
111
110
  2. Run `./bin/bundle install`
112
111
  3. Run `./bin/rails turbo:install`
113
- 4. Run `./bin/rails turbo:install:redis` to change the development Action Cable adapter from Async (the default one) to Redis. The Async adapter does not support Turbo Stream broadcasting.
114
112
 
115
- Running `turbo:install` will install through NPM if Node.js is used in the application. Otherwise the asset pipeline version is used. To use the asset pipeline version, you must have `importmap-rails` installed first and listed higher in the Gemfile.
113
+ Running `turbo:install` will install through NPM or Bun if a JavaScript runtime is used in the application. Otherwise the asset pipeline version is used. To use the asset pipeline version, you must have `importmap-rails` installed first and listed higher in the Gemfile.
116
114
 
117
115
  If you're using node and need to use the cable consumer, you can import [`cable`](https://github.com/hotwired/turbo-rails/blob/main/app/javascript/turbo/cable.js) (`import { cable } from "@hotwired/turbo-rails"`), but ensure that your application actually *uses* the members it `import`s when using this style (see [turbo-rails#48](https://github.com/hotwired/turbo-rails/issues/48)).
118
116
 
@@ -122,17 +120,26 @@ The `Turbo` instance is automatically assigned to `window.Turbo` upon import:
122
120
  import "@hotwired/turbo-rails"
123
121
  ```
124
122
 
125
-
126
123
  ## Usage
127
124
 
128
125
  You can watch [the video introduction to Hotwire](https://hotwired.dev/#screencast), which focuses extensively on demonstrating Turbo in a Rails demo. Then you should familiarize yourself with [Turbo handbook](https://turbo.hotwired.dev/handbook/introduction) to understand Drive, Frames, and Streams in-depth. Finally, dive into the code documentation by starting with [`Turbo::FramesHelper`](https://github.com/hotwired/turbo-rails/blob/main/app/helpers/turbo/frames_helper.rb), [`Turbo::StreamsHelper`](https://github.com/hotwired/turbo-rails/blob/main/app/helpers/turbo/streams_helper.rb), [`Turbo::Streams::TagBuilder`](https://github.com/hotwired/turbo-rails/blob/main/app/models/turbo/streams/tag_builder.rb), and [`Turbo::Broadcastable`](https://github.com/hotwired/turbo-rails/blob/main/app/models/concerns/turbo/broadcastable.rb).
129
126
 
127
+ Note that in development, the default Action Cable adapter is the single-process `async` adapter. This means that turbo updates are only broadcast within that same process. So you can't start `bin/rails console` and trigger Turbo broadcasts and expect them to show up in a browser connected to a server running in a separate `bin/dev` or `bin/rails server` process. Instead, you should use the web-console when needing to manaually trigger Turbo broadcasts inside the same process. Add "console" to any action or "<%= console %>" in any view to make the web console appear.
128
+
130
129
  ### RubyDoc Documentation
131
130
 
132
- For the API documentation covering this gem's classes and packages, [visit the
133
- RubyDoc page][].
131
+ For the API documentation covering this gem's classes and packages, [visit the RubyDoc page](https://rubydoc.info/github/hotwired/turbo-rails/main).
132
+ Note that this documentation is updated automatically from the main branch, so it may contain features that are not released yet.
134
133
 
135
- [visit the RubyDoc page](https://rubydoc.info/github/hotwired/turbo-rails/main)
134
+ - [Turbo Drive Helpers](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/DriveHelper)
135
+ - [Turbo Frames Helpers](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/FramesHelper)
136
+ - [Turbo Streams View Helpers](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/StreamsHelper)
137
+ - [Turbo Streams Broadcast Methods](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Broadcastable)
138
+ - [Turbo Streams Channel](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/StreamsChannel)
139
+ - [Turbo Native Navigation](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Native/Navigation)
140
+ - [Turbo Test Assertions](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/TestAssertions)
141
+ - [Turbo Integration Test Assertions](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/TestAssertions/IntegrationTestAssertions)
142
+ - [Turbo Broadcastable Test Helper](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Broadcastable/TestHelper)
136
143
 
137
144
  ## Compatibility with Rails UJS
138
145
 
@@ -140,17 +147,61 @@ Turbo can coexist with Rails UJS, but you need to take a series of upgrade steps
140
147
 
141
148
  ## Testing
142
149
 
143
-
144
- The [`Turbo::TestAssertions`](./lib/turbo/test_assertions.rb) concern provides Turbo Stream test helpers that assert the presence or absence of `<turbo-stream>` elements in a rendered fragment of HTML. `Turbo::TestAssertions` are automatically included in [`ActiveSupport::TestCase`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/TestCase.html) and depend on the presence of [`rails-dom-testing`](https://github.com/rails/rails-dom-testing/) assertions.
150
+ The [`Turbo::TestAssertions`](./lib/turbo/test_assertions.rb) concern provides Turbo Stream test helpers that assert the presence or absence ofs s `<turbo-stream>` elements in a rendered fragment of HTML. `Turbo::TestAssertions` are automatically included in [`ActiveSupport::TestCase`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/TestCase.html) and depend on the presence of [`rails-dom-testing`](https://github.com/rails/rails-dom-testing/) assertions.
145
151
 
146
152
  The [`Turbo::TestAssertions::IntegrationTestAssertions`](./lib/turbo/test_assertions/integration_test_assertions.rb) are built on top of `Turbo::TestAssertions`, and add support for passing a `status:` keyword. They are automatically included in [`ActionDispatch::IntegrationTest`](https://edgeguides.rubyonrails.org/testing.html#integration-testing).
147
153
 
148
- The [`Turbo::Broadcastable::TestHelper`](./lib/turbo/broadcastable/test_helper.rb) concern provides Action Cable-aware test helpers that assert that `<turbo-stream>` elements were or were not broadcast over Action Cable. They are not automatically included. To use them in your tests, make sure to `include Turbo::Broadcastable::TestHelper`.
154
+ The [`Turbo::Broadcastable::TestHelper`](./lib/turbo/broadcastable/test_helper.rb) concern provides Action Cable-aware test helpers that assert that `<turbo-stream>` elements were or were not broadcast over Action Cable. `Turbo::Broadcastable::TestHelper` is automatically included in [`ActiveSupport::TestCase`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/TestCase.html).
155
+
156
+ ### Rendering Outside of a Request
157
+
158
+ Turbo utilizes [ActionController::Renderer][] to render templates and partials
159
+ outside the context of the request-response cycle. If you need to render a
160
+ Turbo-aware template, partial, or component, use [ActionController::Renderer][]:
161
+
162
+ ```ruby
163
+ ApplicationController.renderer.render template: "posts/show", assigns: { post: Post.first } # => "<html>…"
164
+ PostsController.renderer.render :show, assigns: { post: Post.first } # => "<html>…"
165
+ ```
166
+
167
+ As a shortcut, you can also call render directly on the controller class itself:
168
+
169
+ ```ruby
170
+ ApplicationController.render template: "posts/show", assigns: { post: Post.first } # => "<html>…"
171
+ PostsController.render :show, assigns: { post: Post.first } # => "<html>…"
172
+ ```
173
+
174
+ [ActionController::Renderer]: https://api.rubyonrails.org/classes/ActionController/Renderer.html
149
175
 
150
176
  ## Development
151
177
 
152
178
  Run the tests with `./bin/test`.
153
179
 
180
+ ### Using local Turbo version
181
+
182
+ Often you might want to test changes made locally to [Turbo lib](https://github.com/hotwired/turbo) itself. To package your local development version of Turbo you can use [yarn link](https://classic.yarnpkg.com/lang/en/docs/cli/link/) feature:
183
+
184
+ ```sh
185
+ cd <local-turbo-dir>
186
+ yarn link
187
+
188
+ cd <local-turbo-rails-dir>
189
+ yarn link @hotwired/turbo
190
+
191
+ # Build the JS distribution files...
192
+ yarn build
193
+ # ...and commit the changes
194
+ ```
195
+
196
+ Now you can reference your version of turbo-rails in your Rails projects packaged with your local version of Turbo.
197
+
198
+ ## Contributing
199
+
200
+ Having a way to reproduce your issue will help people confirm, investigate, and ultimately fix your issue. You can do this by providing an executable test case. To make this process easier, we have prepared an [executable bug report Rails application](./bug_report_template.rb) for you to use as a starting point.
201
+
202
+ This template includes the boilerplate code to set up a System Test case. Copy the content of the template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing.
203
+
204
+ You can then share your executable test case as a gist or paste the content into the issue description.
154
205
 
155
206
  ## License
156
207