Docs - Prepare short section on Stimulus usage in UI guidelines

- Aimed at contributors, based on initial implementation learnings and original RFC content
- See https://github.com/wagtail/rfcs/blob/main/text/078-adopt-stimulus-js.md#c-documentation-for-contributors
- Closes #10093

CHANGELOG.txt

@@ -35,6 +35,7 @@ Changelog
  * Docs: Add helpful troubleshooting links and refine wording for getting started with development (Loveth Omokaro)
  * Docs: Ensure search autocomplete overlay on mobile does not overflow the viewport (Ayman Makroo)
  * Docs: Improve documentation for InlinePanel (Vallabh Tiwari)
+ * Docs: Add contributor guidelines for building Stimulus Controllers (Thibaud Colas, Loveth Omokaro, LB (Ben) Johnston)
  * Maintenance: Removed features deprecated in Wagtail 3.0 and 4.0 (Matt Westcott)
  * Maintenance: Update djhtml (html formatting) library to v 1.5.2 (Loveth Omokaro)
  * Maintenance: Re-enable `strictPropertyInitialization` in tsconfig (Thibaud Colas)

docs/contributing/ui_guidelines.md

@@ -22,7 +22,8 @@ We use [djhtml](https://github.com/rtts/djhtml) for formatting and [Curlylint](h
 
 -   Write [valid](https://validator.w3.org/nu/), [semantic](https://html5doctor.com/element-index/) HTML.
 -   Follow [ARIA authoring practices](https://w3c.github.io/aria-practices/), in particular, [No ARIA is better than Bad ARIA](https://w3c.github.io/aria-practices/#no_aria_better_bad_aria).
--   Use classes for styling, `data-` attributes for JavaScript behaviour, IDs for semantics only.
+-   Use IDs for semantics only, classes for styling, `data-` attributes for JavaScript behaviour.
+-   Order attributes with `id` first, then `class`, then any `data-` or other attributes with Stimulus `data-controller` first.
 -   For comments, use [Django template syntax](https://docs.djangoproject.com/en/stable/ref/templates/language/#comments) instead of HTML.
 
 ## CSS guidelines
@@ -42,6 +43,47 @@ We use [Prettier](https://prettier.io/) for formatting and [ESLint](https://esli
 -   We follow a somewhat relaxed version of the [Airbnb styleguide](https://github.com/airbnb/javascript).
 -   Familiarise yourself with our [eslint-config-wagtail](https://github.com/wagtail/eslint-config-wagtail) configuration, which details our preferred code style.
 
+(ui_guidelines_stimulus)=
+
+## Stimulus
+
+Wagtail uses [Stimulus](https://stimulus.hotwired.dev/) as a lightweight framework to attach interactive behaviour to DOM elements via `data-` attributes.
+
+### Why Stimulus
+
+Stimulus is a lightweight framework that allows developers to create interactive UI elements in a simple way. It makes it easy to do small-scale reactivity via changes to data attributes and does not require developers to 'init' things everywhere, unlike JQuery. It also provides an alternative to using inline script tag usage and window globals which reduces complexity in the codebase.
+
+### When to use Stimulus
+
+Stimulus is our [preferred library](https://github.com/wagtail/rfcs/pull/78) for simple client-side interactivity. It’s a good fit when:
+
+-   The interactivity requires JavaScript. Otherwise, consider using HTML and CSS only.
+-   Some of the logic is defined via HTML templates, not just JavaScript.
+-   The interactivity is simple, and doesn’t require usage of more heavyweight libraries like React.
+
+Wagtail’s admin interface also leverages jQuery for similar scenarios. This is considered legacy and will eventually be removed. For new features, carefully consider whether existing jQuery code should be reused, or whether a rebuild with Stimulus is more appropriate.
+
+### How to build a Stimulus controller
+
+First think of how to name the controller. Keep it concise, one or two words ideally. Then,
+
+1. Start with the HTML templates, build as much of the UI as you can in HTML alone. Ensure it is accessible and follows the CSS guidelines.
+2. Create the controller file in our `client/src/controllers` folder, along with its tests (see [](testing)) and Storybook stories.
+3. For initialisation, consider which [controller lifecycle methods](https://stimulus.hotwired.dev/reference/lifecycle-callbacks#methods) to use, if any (`connect`, `initialize`).
+4. If relevant, also consider how to handle the controlled element being removed from the DOM [`disconnect` lifecycle method](https://stimulus.hotwired.dev/reference/lifecycle-callbacks#disconnection).
+5. Document controller classes and methods with [JSDoc annotations](https://jsdoc.app/index.html).
+6. Use [values](https://stimulus.hotwired.dev/reference/values) to provide options and also reactive state, avoiding instance properties if possible. Prefer falsey or empty defaults and avoid too much usage of the Object type when using values.
+7. Build the behaviour around small, discrete, methods and use [Stimulus actions](https://stimulus.hotwired.dev/reference/actions) declared in HTML to drive when they are called.
+
+### Helpful tips
+
+-   Prefer controllers that do a small amount of 'work' that is collected together, instead of lots of large or specific controllers.
+-   Lean towards dispatching events for key behaviour in the UI interaction as this provides a great way for custom code to hook into this without an explicit API, but be sure to document these.
+-   Multiple controllers can be attached to one DOM element for composing behaviour, where practical split out behaviour to separate controllers.
+-   Consider when to document controller usage for non-contributors.
+-   When writing unit tests, note that DOM updates triggered by data attribute changes are completed async (next `microtick`) so will require a await Promise or similar to check for the changes in JSDom.
+-   Avoid hard-coding a controller's identifier, instead reference it with `this.identifier` if adjusting attributes. This way the controller can be used easily with a changed identifier or extended by other classes in the future.
+
 ## Multilingual support
 
 This is an area of active improvement for Wagtail, with [ongoing discussions](https://github.com/wagtail/wagtail/discussions/8017).

docs/releases/5.0.md

@@ -53,6 +53,7 @@ Support for adding custom validation logic to StreamField blocks has been formal
  * Ensure search autocomplete overlay on mobile does not overflow the viewport (Ayman Makroo)
  * Improve documentation for InlinePanel (Vallabh Tiwari)
  * Remove confusing `SettingsPanel` reference in the page editing `TabbedInterface` example as `SettingsPanel` no longer shows anything as of 4.1 (Kenny Wolf, Julian Bigler)
+ * Add contributor guidelines for building [Stimulus Controllers](ui_guidelines_stimulus) (Thibaud Colas, Loveth Omokaro, LB (Ben) Johnston)
 
 ### Maintenance