🎛️ Stimulus adoption discussion

[lb-]

A new discussion for the community to discuss the Stimulus adoption.

As release 5.2 will contain documented support for using Stimulus within the Wagtail admin, it would be good to have a place to collect feedback and discuss the progress of RFC78 generally.

Links

• Using Stimulus in Wagtail (5.2)
• Spreadsheet roadmap
• GitHub project
• RFC78
• Past updates
  • Comment: Extend Stimulus adoption roadmap#57 (comment)
  • Comment: CSP compatibility improvements roadmap#61 (comment)

[lb-]

October 2023 Update

As it's been about a year since RFC78 was merged, I thought it would be good to give an update.

Wins

• 20 controllers now in the main code with 9 different contributors involved directly with this migration, many more when it comes to reviewing PRs and providing feedback on issues.
• Removal of a huge amount of inline scripts for arbitrary JavaScript, ad-hoc JS imports and jQuery usage.
• We will have officially supported documentation for using Stimulus within Wagtail in 5.2, review the RC now to give feedback. See the latest (not yet released) docs page - https://docs.wagtail.org/en/latest/extending/extending_client_side.html#extending-with-stimulus
• All of these have robust Jest unit tests in place to help us ensure they do not break in the future.
• Many of these controllers have been able to be used/adapted to replace duplicate implementations of similar functionality throughout Wagtail's JavaScript.
• A chance for many new contributors to play a part in small to medium migrations after the initial Outreachy project completed.

State of controllers

#	Controller	Identifier(s)	Description
1.	ActionController	'w-action'	Supports common actions to be triggered by events such as click/reset and submit a related form.
2.	AutosizeController	'w-autosize'	Wrapper around the text area autosize NPM package.
3.	BulkController	'w-bulk'	Starting implementation for bulk checkbox actions.
4.	CloneController	'w-clone', 'w-messages'	Supports event driven cloning of some element with custom content injected.
5.	CountController	'w-count'	Allows for classes/summary of the number of found elements in a controller.
6.	DialogController	'w-dialog'	Wrapper around a11y dialog NPM package.
7.	DismissibleController	'w-dismissible'	Allows for some content to be closed/removed via an action.
8.	DropdownController	'w-dropdown'	Wrapper around tippy.js for dropdowns.
9.	InitController	'w-init'	Supports adding or removing classes, dispatching events when ready or loaded.
10.	ProgressController	'w-progress'	Adds the ability to indicate that something is loaded, usually when clicked.
11.	RevealController	'w-breadcrumbs', 'w-reveal'	Supports open/close (expand/collapse) functionality on elements.
12.	SkipLinkController	'w-skip-link'	Allows directing focus to another element, temporarily adding tabindex if needed.
13.	SlugController	'w-slug'	Allows an input's value to be cleaned, using slugify utils.
14.	SubmitController	'w-submit'	Creates a temporary form element for dynamic submission of some data to an endpoint.
15.	SwapController	'w-swap'	Allows async requests to be resolved and then patched into (swapped) some other location in the DOM.
18.	SyncController	'w-sync'	Allows one field to sync/push it's value to another field.
17.	TagController	'w-tag'	Wrapper around the jQuery taggit library.
18.	TeleportController	'w-teleport'	Allows a template element to be used, it's content copied and moved to another place in the DOM.
19.	TooltipController	'w-tooltip'	Wrapper around tippy.js for simple tooltip scenarios.
20.	UpgradeController	'w-upgrade'	Specific implementation for the upgrade notification on the dashboard for admin users.

Short term roadmap

1. Clean up last of the non-Stimulus attributes usage of tooltips. Remove initTooltips include & add upgrade considerations #10894
2. Replace implementations of conditional fields with new w-cond. 🎛️ Migrate conditional fields logic to use Stimulus controller w-cond/w-rules #11045
3. Remove legacy dropdown, migrate to w-dropdown. Add new dropdown-button component #11084 (Draft)
4. Replace side panel & open/close panels with w-reveal enhancements. 🎛️ Migrate panels to a Stimulus controller w-panel #10168
5. Migrate the page listing re-ordering (drag & drop) to a Stimulus wrapper. 🎛️ Migrate Page re-ordering to a Stimulus controller w-orderable #10909
6. Remove date pickers, not strictly Stimulus now but will mean much less complex JS. Replace date & date time picker widget with native browser date pickers #8056
7. Research how we can replace the current focal point chooser and the multiple file upload jQuery implementations with other libraries. WebP image upload preview fails #10947 & related issues.

Longer term

Many of these are not yet created as a new issue but will be created when the short term backlog is reduced.

• Tabs Feature request: UI component API for tabs #8408
• Remove our need for the additional JS library for keyboard shortcuts, blocked for now due to a Stimulus code change but it's hopefully close. 🎛️ Replace MouseTrap usage with built in Stimulus keyboard support #10167
• Dirty form checks
• InlinePanel / formset
• Bulk actions
• Choosers & modal workflows
• Formal support for CSP CSP compatibility improvements roadmap#61

Enhanced features (feedback requested)

If anyone would like to see some of these features make their way to be used in a more documented/Python driven way.

Please have a look at these items and add any thoughts or +1s to the issues, or if you are keen to contribute, add a comment.

• Add the ability to use the sync controller for more complex cases in FieldPanel or a potential SyncPanel. Feature Request: Live Fields #1063
• Add the ability for client-side dynamic conditional fields. Conditional form fields in admin #2172
• Add the ability to support re-ordering for Snippets. Rearrange order of Snippets in ModelViewSet index view #10816
• Add the ability to restrict field values in more dynamic ways (could leverage the code within w-slug) Allow filtered input on fieldpanels by supplying a regex code of allowed characters #7417

[lb-]

hotwire.io

One of the core contributors to Stimulus/Turbo just built a new site. It looks pretty good and has a great range of content for those using Stimulus.

https://hotwire.io/

I've just raised an issue to see if we can cross reference Wagtail's support for Stimulus on this site. marcoroth/hotwire.io#57

For anyone building custom controllers, these sections have some great resources.

• https://hotwire.io/use-cases
• https://hotwire.io/ecosystem/components
• https://hotwire.io/ecosystem/npm

[lb-]

PR up marcoroth/hotwire.io#59

[lb-]

Other projects using Stimulus

#	Website	Description	Language	Repo	controllers/ folder
43	https://avohq.io	CMS & CRM builder	Ruby	https://github.com/avo-hq/avo	📁
41	https://docs.part-db.de/	Inventory management	PHP	https://github.com/Part-DB/Part-DB-server	📁
40	https://orchid.software/	CMS & CRM builder	PHP	https://github.com/orchidsoftware/platform	📁
34	https://spinacms.com/	CMS	Ruby	https://github.com/SpinaCMS/Spina	📁
23	https://bullettrain.co/	SASS toolkit	Ruby	https://github.com/bullet-train-co/bullet_train	📁
20	https://pypi.org/	Package index	Python	https://github.com/pypi/warehouse	📁
19	https://forem.com	Discussion forum	Ruby	https://github.com/forem/forem	📁
12	https://railsdevs.com/	Blog/content site	Ruby	https://github.com/joemasilotti/railsdevs.com	📁

Sorted by amount of Stimulus controllers, only projects with 10+ controllers.

[lb-]

@thibaudcolas @laymonage - as per our discussion the other week, you wanted to see some examples of larger projects and how they are using Stimulus. Obviously a lot of these are Ruby but here's some I have sourced from Twitter and GitHub.

All have at least 10 custom built controllers in their code and a few have over 40.

Once the projects get to around 30, they appear to start splitting into sub-folders internal sub-packages. I think we could learn a lot from these approaches, including some of the kinds of controllers they have are very similar to ours.

Let me know if there is any more digging you wanted to me to do.