marcoroth / turbo_power

Power-pack for Turbo Streams

TurboPower

Getting Started

turbo_power is a power-pack for Turbo Streams. It provides Turbo Streams with a bunch of new actions and additionally adds the morph action from turbo-morph.

Note: Requires Turbo 7.2+

Getting Started

yarn add turbo_power

// application.js
import * as Turbo from '@hotwired/turbo'

+import TurboPower from 'turbo_power'
+TurboPower.initialize(Turbo.StreamActions)

Getting Started with Rails

Checkout the instructions in the turbo_power-rails repo.

Getting Started with Django

Checkout the doc of the django-turbo-helper repo.

Custom Actions

DOM Actions

• turbo_stream.graft(target, parent, **attributes)
• turbo_stream.morph(target, html = nil, **attributes, &block)
• turbo_stream.inner_html(target, html = nil, **attributes, &block)
• turbo_stream.insert_adjacent_html(target, html = nil, position: 'beforeend', **attributes, &block)
• turbo_stream.insert_adjacent_text(target, text, position: 'beforebegin', **attributes)
• turbo_stream.outer_html(target, html = nil, **attributes, &block)
• turbo_stream.text_content(target, text, **attributes)
• turbo_stream.set_meta(name, content)

Attribute Actions

• turbo_stream.add_css_class(target, classes, **attributes)
• turbo_stream.remove_attribute(target, attribute, **attributes)
• turbo_stream.remove_css_class(target, classes, **attributes)
• turbo_stream.set_attribute(target, attribute, value, **attributes)
• turbo_stream.set_dataset_attribute(target, attribute, value, **attributes)
• turbo_stream.set_property(target, property, value, **attributes)
• turbo_stream.set_style(target, name, value, **attributes)
• turbo_stream.set_styles(target, styles, **attributes)
• turbo_stream.set_value(target, value, **attributes)
• turbo_stream.toggle_css_class(target, classes, **attributes)
• turbo_stream.replace_css_class(target, from, to, **attributes)

Event Actions

• turbo_stream.dispatch_event(target, name, detail: {}, **attributes)

Form Actions

• turbo_stream.reset_form(target, **attributes)

Storage Actions

• turbo_stream.clear_storage(type, **attributes)
• turbo_stream.clear_local_storage(**attributes)
• turbo_stream.clear_session_storage(**attributes)
• turbo_stream.remove_storage_item(key, type, **attributes)
• turbo_stream.remove_local_storage_item(key, **attributes)
• turbo_stream.remove_session_storage_item(key, **attributes)
• turbo_stream.set_storage_item(key, value, type, **attributes)
• turbo_stream.set_local_storage_item(key, value, **attributes)
• turbo_stream.set_session_storage_item(key, value, **attributes)

Browser Actions

• turbo_stream.reload(**attributes)
• turbo_stream.scroll_into_view(**attributes)
  • turbo_stream.scroll_into_view(targets)
  • turbo_stream.scroll_into_view(targets, align_to_top)
  • turbo_stream.scroll_into_view(targets, behavior:, block:, inline:)
• turbo_stream.set_focus(target, **attributes)
• turbo_stream.set_title(title, **attributes)

Document Actions

• turbo_stream.set_cookie(cookie, **attributes)
• turbo_stream.set_cookie_item(key, value, **attributes)

Browser History Actions

• turbo_stream.history_back(**attributes)
• turbo_stream.history_forward(**attributes)
• turbo_stream.history_go(delta, **attributes)
• turbo_stream.push_state(url, title = nil, state = nil, **attributes)
• turbo_stream.replace_state(url, title = nil, state = nil, **attributes)

Debug Actions

• turbo_stream.console_log(message, level = :log)
• turbo_stream.console_table(data, columns)

Notification Actions

• turbo_stream.notification(title, **options)

Turbo Actions

• turbo_stream.redirect_to(url, turbo_action = nil, turbo_frame = nil, **attributes)
• turbo_stream.turbo_clear_cache()

Turbo Progress Bar Actions

• turbo_stream.turbo_progress_bar_show()
• turbo_stream.turbo_progress_bar_hide()
• turbo_stream.turbo_progress_bar_set_value(value)

Turbo Frame Actions

• turbo_stream.turbo_frame_reload(frame_id)
• turbo_stream.turbo_frame_set_src(frame_id, src)

Previous Art

TurboPower is heavily inspired by CableReady and its operations. This library aims to bring the same level of operation-diversity to Turbo Streams.

Development

To run the test runner:

yarn build
yarn test

Acknowledgments

turbo_power is MIT-licensed open-source software from Marco Roth.

turbo-morph is MIT-licensed open-source software from Marco Roth.

Turbo is MIT-licensed open-source software from Basecamp.

turbo_power's Issues

Implement `turbo_set_progress_bar` action

Add an action/multiple actions for controlling the Turbo progress bar

Turbo.navigator.adapter.progressBar.setValue(value)
Turbo.navigator.adapter.progressBar.show()
Turbo.navigator.adapter.progressBar.hide()

Implement Action to set a `window.onbeforeunload` callback

Not sure how useful this is, but it might be interesting to have an action to set a window.onbeforeunload callback. This can be handy to set from the server-side when you are sending down some data which is not persisted yet. And with this you would get a warning when you attempt to close the window/tab. Like:

The example above can be achieved with this snippet:

window.onbeforeunload = function() {
  return true;
}

Obviously we would also need an action to clear the event-listener again.

Implement `input_select` action

Action signature:

turbo_stream.input_select(targets, **attributes)

Or rather select_input? 🤔

Example Turbo Stream Element:

<turbo-stream action="input_select" target="item_1"></turbo-stream>

Action content:

target.select()

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select

Add Django Content

@marcoroth

I am a Django developer and maintainer of django-turbo-helper, which is turbo helper for Django.

Inspired by "turbo_power-rails", I just added some custom actions to the project, so Django developer can also use morph, turbo_frame_reload and other actions in Django, with the same way "turbo_power-rails" does.

Here is the source code https://github.com/rails-inspire-django/django-turbo-helper/blob/main/src/turbo_helper/turbo_power.py if you are interested.

I want to add the link to the doc of this project, to tell people this project can also work in Django, and I am sure many Django developers will like it. 👍

If you think this is good to go, please let me know and I will create PR in a bit.

Thanks for your great work on this project.

Implement `turbo_frame_set_src` action

Action signature:

turbo_stream.turbo_frame_set_src(frame_id, src, **attributes)

Reference:
https://turbo.hotwired.dev/reference/frames#properties

Feature request: Remove morph as a default action.

I'd speculate (I admit that this surmise is based on no actually data but just a professional hunch) that the morph custom action is rarely used but in turn carries a dependency, the turbo-morph NPM package.

Should it not then be required but opt-in?

Thanks @marcoroth for your consideration.

Implement `console_table` action

Action signature:

turbo_stream.console_table(data, columns = nil, **attributes)

Reference:
https://developer.mozilla.org/en-US/docs/Web/API/Console/table

Rails importmap and v0.3.0

1. I endeavored to move up to v0.3.0 just by manually adjusting the Rails config/importmap.rb turbo_power version, which after its setting yielded a browser console error of:

Uncaught TypeError: Failed to resolve module specifier "turbo-morph". Relative references must start with either "/", "./", or "../".

There was an error with either of the below CDNs.

# config/importmap.rb 
pin 'turbo_power', to: 'https://ga.jspm.io/npm:[email protected]/dist/turbo_power.js'
# pin 'turbo_power', to: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/turbo_power.js'

2. I figured it was a missing turbo-morph dependency so I just re-enabled the jspm.io CDN in config/importmap.rb and made an attempt to use the Rails' bin/importmap script to handle fetching the correct turbo-morph dependency and that venture yielded these errors:

bin/importmap unpin turbo_power
Couldn't find any packages in ["turbo_power"] on jspm
bin/importmap pin turbo_power
Couldn't find any packages in ["turbo_power"] on jspm

Thanks @marcoroth.

Implement `history_back` action

Action signature:

turbo_stream.history_back(**attributes)

Action content:

window.history.back()

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/History/back

Implement `turbo_frame_reload` action

Action signature:

turbo_stream.turbo_frame_reload(frame_id, **attributes)

Reference:
https://turbo.hotwired.dev/reference/frames#functions

Implement `toggle_css_class` action

Action signature:

turbo_stream.toggle_css_class(targets, classes, **attributes)

Example Turbo Stream Element:

<turbo-stream action="toggle_css_class" targets=".items" classes="background-blue background-gray"></turbo-stream>

Action content:

target.classList.toggle(...classes)

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle

THANK YOU

Thanks for this gem it fills a big gap!

example

Implement `alignToTop` and `scrollIntoViewOptions` for `scroll_into_view` action

Currently the scroll_into_view action takes no argument and just calls element.scrollIntoView() on all targets:

turbo_power/src/actions/browser.ts

Lines 7 to 9 in ce7ca0b

	export function scroll_into_view(this: StreamElement) {
	this.targetElements.forEach((element: Element) => element.scrollIntoView())
	}

Looking at the reference it shows that there are also other ways to call scrollIntoView(), like:

scrollIntoView()
scrollIntoView(alignToTop)
scrollIntoView(scrollIntoViewOptions)

It would make sense to also implement the alignToTop and scrollIntoViewOptions arguments.

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView

Implement `reset_form` action

Action signature:

turbo_stream.reset_form(target, **attributes)

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reset
• https://twitter.com/excid3/status/1601285720106094592

Implement `replace_css_class` action

Action signature:

turbo_stream.replace_css_class(targets, from, to, **attributes)

Question: or maybe old and new instead of from and to?

Example Turbo Stream Element:

<turbo-stream action="replace_css_class" targets=".items" from="background-blue" to="background-gray"></turbo-stream>

Action content:

target.classList.replace(from, to)

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/replace

Implement `notification` action

Action signature:

turbo_stream.notification(title, options, **attributes)

Reference:
https://developer.mozilla.org/en-US/docs/Web/API/Notification/Notification#syntax

Implement `turbo_visit` action

Action signature:

turbo_stream.turbo_visit(location, action = "advance", **attributes)

Action content:

Turbo.visit(location)
Turbo.visit(location, { action: turbo_action })

Check out the existing redirect_to action, which technically already covers the use-case for this action.

Reference:
https://turbo.hotwired.dev/reference/drive#turbo.visit

Action `redirect_to` should use Turbo by default

Currently you need to pass turbo="true" to the <turbo-stream> element in order that is uses Turbo.visit():

<turbo-stream turbo="true" url="http://localhost:3000/" action="redirect_to"><template></template></turbo-stream>

It should use Turbo.visit() by default unless turbo="false" gets explicitly passed to the stream element.

The action already accounts for when Turbo/Turbolinks is not installed in the application and will fallback to window.location.href = url

turbo_power/src/actions/browser.ts

Line 17 in 623a6f5

export function redirect_to(this: StreamElement) {

Implement `turbo_clear_cache` action

Action signature:

turbo_stream.turbo_clear_cache()

Action content:

Turbo.cache.clear()

Reference:
https://turbo.hotwired.dev/reference/drive#turbo.cache.clear

Implement `toggle_attribute` action

Action signature:

turbo_stream.toggle_attribute(targets, attribute, **attributes)

Example Turbo Stream Element:

<turbo-stream action="toggle_attribute" targets=".items" attribute="disabled"></turbo-stream>

Action content:

target.toggleAttribute(attribute)

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/Element/toggleAttribute

`redirect_to` Action: rename `action` attribute to `action_name`

The redirect_to action has an action attribute which is being passed to Turbo.visit(..., { action }) to control the Turbo visit behaviour.

But the action attribute name is clashing with the <turbo-stream> element, since it's using the action attribute for determining the stream action to execute.

We should rename the attribute for the redirect_to action to either action_name or turbo_action.

Implement `console_log` action

Action signature:

turbo_stream.console_log(message, level = :log, **attributes)

Reference:
https://developer.mozilla.org/en-US/docs/Web/API/Console/log

Remove `Turbolinks` from all actions

The Turbolinks cases in all actions were taken over from the CableReady operations.

But technically Turbolinks isn't really compatible with TurboPower since you actually need to have Turbo installed in your app if you want to use Custom Turbo Stream Actions.

[Feature Request] Add or improve history actions

Thanks for the great lib!

It would be nice to have a shortcut to modify Turbo.navigator.history. I find it an essential action since the Back button is not doing what is expected when the browser history is modified without touching Turbo.navigator.history. As a workaround, the invoke action can be used at the moment.

More on the issue: https://discuss.hotwired.dev/t/back-button-not-working/3012

P.S. I'd really love to help but I'm not very familiar with Typescript yet :/

Make sure you can just enable some actions and not just "all or nothing"

Something like:

import * as Turbo from '@hotwired/turbo'
import TurboPower, { AttributeActions, BrowserActions } from 'turbo_power'

TurboPower.initialize(Turbo.StreamActions, [AttributeActions, BrowserActions])

Implement `history_forward` action

Action signature:

turbo_stream.history_forward(**attributes)

Action content:

window.history.forward()

Reference:

• https://developer.mozilla.org/en-US/docs/Web/API/History/forward

Implement `set_cookie_item` action

Action Signature:

turbo_stream.set_cookie_item(key, value, **attributes)

Reference:
https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie

Think about creating a `turbo.ts` actions file

Maybe it would makes sense to extract all the Turbo related actions into a src/actions/turbo.ts file.

For now this is:

• redirect_to (or a potential turbo_visit)
• turbo_clear_cache

Where is v0.6.0 in rubygems?

There is latest v0.6.0 release and I try to request it in Gemfile:

gem "turbo_power", "~> 0.6.0"

But its not on rubygems https://rubygems.org/gems/turbo_power ? Did it get yanked or not uploaded?

$ bundle update
Could not find gem 'turbo_power (~> 0.6.0)' in rubygems repository https://rubygems.org/ or installed locally.

The source contains the following gems matching 'turbo_power':
  * turbo_power-0.1.0
  * turbo_power-0.1.1
  * turbo_power-0.1.2
  * turbo_power-0.1.3
  * turbo_power-0.1.5
  * turbo_power-0.1.6
  * turbo_power-0.2.0
  * turbo_power-0.3.0
  * turbo_power-0.3.1
  * turbo_power-0.4.0
  * turbo_power-0.5.0