jsx event and directive reference pages

Author: LadyBluenotes

src/routes/reference/jsx-attributes/on.mdx

@@ -2,51 +2,67 @@
 title: "on:*"
 order: 4
 use_cases: >-
-  custom events, non-bubbling events, capture phase handling, passive listeners,
-  special event options
+  direct event listeners, custom event names, event listener options
 tags:
   - events
   - listeners
   - dom
   - capture
   - passive
-  - handlers
 version: "1.0"
 description: >-
-  Attach non-delegated event handlers with on:* in SolidJS. Control capture,
-  passive, and once options for advanced event handling requirements.
+  Attach an event listener directly to an element with `addEventListener`.
 ---
 
-For events with capital letters, listener options, or if you need to attach event handlers directly to a DOM element instead of optimized delegating via the document, use `on:*` in place of `on*`.
+`on:*` attaches an event listener directly to an element with `addEventListener`.
+
+## Syntax
 
 ```tsx
-<div on:DOMContentLoaded={(e) => console.log("Welcome!")} />
+<div on:wheel={handler} />
 ```
 
-This directly attaches an event handler (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`.
+## Value
 
-:::note
+- **Type:** event handler function or `EventListenerObject & AddEventListenerOptions`
 
-<span>New in v1.9.0</span>
-:::
+Listener passed to `addEventListener`.
+
+## Behavior
+
+- `on:name={handler}` attaches a listener for the event named `name`.
+- The listener is attached directly to the element instead of using Solid's delegated event system.
+- Event names keep the text after `on:` exactly as written.
+- Listener options such as `once`, `passive`, `capture`, and `signal` can be provided by passing an object that implements `handleEvent`.
+
+## Examples
+
+### Basic usage
 
-An aditional special syntax that allows full control of [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture), [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive), [`once`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#once) and [`signal`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal) is an intersection or combination of `EventListenerObject` & `AddEventListenerOptions`, as follows:
+```tsx
+<div on:DOMContentLoaded={(e) => console.log("Welcome!", e)} />
+```
+
+### Listener options
 
 ```tsx
 const handler = {
 	handleEvent(e) {
-		console.log(e)
+		console.log(e);
 	},
-	once:true,
-	passive:false,
-	capture:true
-}
+	once: true,
+	passive: false,
+	capture: true,
+};
 
-<div on:wheel={handler} />
+<div on:wheel={handler} />;
+```
 
-// or inline
+:::note
+The object-listener form was added in Solid 1.9.0.
+:::
 
-<div on:click={{passive:true, handleEvent(e) { console.log("Weeeee!")}}} />
-```
+## Related
 
-This new syntax replaces the now deprecated `oncapture:` and it's future proof for any posible new event listener options.
+- [`on*`](/reference/jsx-attributes/on_)
+- [`oncapture:*`](/reference/jsx-attributes/on)

src/routes/reference/jsx-attributes/on_.mdx

@@ -2,48 +2,58 @@
 title: on*
 order: 3
 use_cases: >-
-  user interactions, click handlers, form events, keyboard input, mouse events,
-  touch handling
+  delegated UI events, click handlers, input handlers, keyboard handlers
 tags:
   - events
   - handlers
-  - interactions
-  - click
-  - input
   - delegation
+  - dom
 version: "1.0"
 description: >-
-  Handle user events efficiently in SolidJS with onClick and other event
-  handlers. Optimized delegation system for improved performance at scale.
+  Attach an event handler with Solid's delegated event system when the event is
+  supported.
 ---
 
-Event handlers in Solid typically take the form of `onclick` or `onClick` depending on style.
+`on*` attaches an event handler using Solid's delegated event system when the event is supported.
+
+## Syntax
 
 ```tsx
-<div onClick={(e) => console.log(e.currentTarget)} />
+<div onClick={handler} />
 ```
 
-Conceptually, this example attaches a `click` event listener (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`. However, Solid actually handles common UI events that bubble and are composed (such as `click`) at the document level, and then synthetically implements delegation (capturing and bubbling). This improves performance for these common events by reducing the number of event handlers.
+## Value
 
-Note that `onClick` handles the event `click`; in general, event names get mapped to lower case. If you need to work with event names containing capital letters, or use listener options such once, passive, capture see [`on:`](/reference/jsx-attributes/on) which attaches event handlers directly (also avoiding fancy delegation via document).
+- **Type:** event handler function or `[handler, data]`
 
-Solid also supports passing a two-element array to the event handler to bind a value to the first argument of the event handler. This doesn't use `bind` or create an additional closure, so it is a highly optimized way of delegating events.
+Event handler, or a handler/data pair for delegated binding.
 
-```tsx
-function handler(itemId, e) {
-	/*...*/
-}
+## Behavior
+
+- Common delegated events are handled at the document level instead of attaching one listener per element.
+- Event names are mapped to lower case, so `onClick` listens to `click`.
+- The two-element array form passes the first item as bound data to the handler.
+- Delegated bindings are not reactive and are not rebound automatically.
+- For direct element listeners, custom event casing, or listener options, use [`on:*`](/reference/jsx-attributes/on).
+
+## Examples
 
-<ul>
-	<For each={state.list}>{(item) => <li onClick={[handler, item.id]} />}</For>
-</ul>;
+### Basic usage
+
+```tsx
+<div onClick={(e) => console.log(e.currentTarget)} />
 ```
 
-Events are never rebound and the bindings are not reactive, as it is expensive to attach and detach listeners. Since event handlers are called like any other function each time an event fires, there is no need for reactivity; shortcut your handler if desired.
+### Handler and bound data
 
 ```tsx
-// if defined, call it; otherwise don't.
-<div onClick={() => props.handleClick?.()} />
+function handler(itemId, e) {
+	console.log(itemId, e);
+}
+
+<For each={state.list}>{(item) => <li onClick={[handler, item.id]} />}</For>;
 ```
 
-Note that `onChange` and `onInput` work according to their native behavior (unlike, say, React). [`onInput`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) will fire immediately after the value has changed; for most `<input>` fields, [`onChange`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) will only fire after the field loses focus. The event's `currentTarget` refers to the element that the event was attached to, while `target` gives the element that actually triggered the event (e.g. the user clicked on).
+## Related
+
+- [`on:*`](/reference/jsx-attributes/on)

src/routes/reference/jsx-attributes/once.mdx

@@ -2,29 +2,39 @@
 title: "@once"
 order: 5
 use_cases: >-
-  performance optimization, static props, non-reactive values, compile-time
-  optimization, reducing overhead
+  non-reactive JSX expressions, compile-time opt-out from reactive wrapping
 tags:
-  - optimization
-  - performance
-  - static
   - compiler
   - jsx
+  - optimization
 version: "1.0"
 description: >-
-  Optimize SolidJS components with @once decorator for static values. Prevent
-  unnecessary reactive wrapping and improve runtime performance.
+  Mark a JSX expression so the compiler does not wrap it reactively.
 ---
 
-Solid's compiler uses a heuristic for reactive wrapping and lazy evaluation of JSX expressions. Does it contain a function call, a property access, or JSX? If yes we wrap it in a getter when passed to components or in an effect if passed to native elements.
+`/*@once*/` marks a JSX expression so the compiler does not wrap it reactively.
+
+## Syntax
+
+```tsx
+<MyComponent value={/*@once*/ expr} />
+```
+
+## Behavior
+
+- `/*@once*/` applies to the expression that follows it.
+- It tells the compiler not to wrap that expression in reactive access machinery.
+- It can be used in props and in children.
+
+## Examples
 
-Knowing this heuristic and its limitations, we can reduce overhead of things we know will never change by accessing them outside of the JSX. A lone variable will never be wrapped. We can also tell the compiler not to wrap them by starting the expression with a comment decorator `/* @once */`.
+### Prop value
 
 ```tsx
 <MyComponent static={/*@once*/ state.wontUpdate} />
 ```
 
-This also works on children.
+### Child value
 
 ```tsx
 <MyComponent>{/*@once*/ state.wontUpdate}</MyComponent>

src/routes/reference/jsx-attributes/use.mdx

@@ -2,39 +2,51 @@
 title: "use:*"
 order: 5
 use_cases: >-
-  complex dom interactions, tooltips, form handling, two-way data binding,
-  reusable element behaviors, custom input components
+  reusable DOM behavior, directives, element setup helpers
 tags:
   - directives
   - dom
-  - forms
-  - bindings
-  - components
-  - typescript
+  - jsx
 version: "1.0"
 description: >-
-  Create custom directives in SolidJS to attach reusable behaviors to DOM
-  elements. Perfect for tooltips, form handling, and two-way data binding.
+  Attach a directive function to a native element with `use:*`.
 ---
 
-Custom directives attach reusable behavior to DOM elements, acting as syntactic sugar over `ref`. They’re ideal for complex DOM interactions like scrolling, tooltips, or form handling, which are cumbersome to repeat in JSX.
+`use:*` attaches a directive function to a native element.
 
-A directive is a function with the following signature
+## Syntax
+
+```tsx
+<input use:model={[value, setValue]} />
+```
+
+## Type
 
 ```ts
+type Accessor<T> = () => T;
+
 function directive(element: HTMLElement, accessor: Accessor<any>): void;
 ```
 
-Directive functions are called at render time but before being added to the DOM. You can do whatever you'd like in them including create signals, effects, register clean-up etc.
+## Value
 
-## Example
+- **Type:** directive argument
 
-A `model` directive for two-way data binding
+Value exposed to the directive through its accessor.
 
-```tsx
-import type { Accessor, Signal } from "solid-js";
+## Behavior
+
+- `use:name={value}` calls the directive named `name` with the element and an accessor for `value`.
+- Directive functions run during rendering before the element is connected to the DOM.
+- Directives only work on native elements, including custom elements.
+- Directives are not forwarded through user-defined components.
+
+## Examples
 
-function model(element: HTMLInputElement, value: Accessor<Signal<string>>) {
+### Basic usage
+
+```tsx
+function model(element, value) {
 	const [field, setField] = value();
 	createRenderEffect(() => (element.value = field()));
 	element.addEventListener("input", ({ target }) => setField(target.value));
@@ -45,64 +57,6 @@ const [name, setName] = createSignal("");
 <input type="text" use:model={[name, setName]} />;
 ```
 
-## TypeScript Support
-
-To type custom directives, extend the `DirectiveFunctions` interface
-
-```ts
-declare module "solid-js" {
-	namespace JSX {
-		interface DirectiveFunctions {
-			model: typeof model;
-		}
-	}
-}
-```
-
-If you just want to constrain the second argument to the directive function, you can extend the older `Directives` interface
-
-```tsx
-declare module "solid-js" {
-	namespace JSX {
-		interface Directives {
-			model: Signal<string>;
-		}
-	}
-}
-```
-
-## Avoiding Tree-Shaking
-
-When importing a directive `d` from another module and using it only as `use:d`, TypeScript (via [babel-preset-typescript](https://babeljs.io/docs/babel-preset-typescript)) may remove the import, as it doesn’t recognize `use:d` as a reference to `d`.
-To prevent this:
-
-1. Use the `onlyRemoveTypeImports: true` option in `babel-preset-typescript`. For `vite-plugin-solid`, add this to `vite.config.ts`
-
-   ```ts
-   import solidPlugin from "vite-plugin-solid";
-
-   export default {
-   	plugins: [
-   		solidPlugin({
-   			typescript: { onlyRemoveTypeImports: true },
-   		}),
-   	],
-   };
-   ```
-
-   Note: This requires consistent use of `export type` and `import type` in your codebase to avoid issues.
-
-2. Add a fake access like `false && d;` in the module
-
-   ```tsx
-   import { model } from "./directives";
-   false && model; // Prevents tree-shaking
-   <input type="text" use:model={[name, setName]} />;
-   ```
-
-   This is removed by bundlers like Terser, unlike a plain `model;` which may remain in the bundle.
-
-:::caution[Limitations]
-Directives only work with native HTML elements (HTML/SVG/MathML/Custom Elements).
-Directives are not forwarded and **won't work in user defined components**, such as `<MyComponent use:myinput={[..]}/>` [see also](https://github.com/solidjs/solid/discussions/722)
+:::note
+When using TypeScript, custom directives may require extending Solid's JSX directive typings.
 :::