docs: restructure TypeScript event handling and JSX directive sections#1533
docs: restructure TypeScript event handling and JSX directive sections#1533harshagarwalnyu wants to merge 2 commits into
Conversation
- Move custom/native on: event docs into API types > Event handling - Add dedicated section for on: directive with subsections for custom and native events - Convert native events callout to a proper subsection - Promote Forcing properties and Custom directives headings to h3 so they appear in the page outline Closes solidjs#569
|
|
✅ Deploy Preview for solid-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the TypeScript documentation to better explain Solid’s on: directive and how to type custom/native events, while removing the older duplicated “Custom event handlers” section.
Changes:
- Added a dedicated “The
on:directive” section with examples for custom events and listener options. - Documented how to extend
CustomEventsto support native events (all or selected). - Reorganized “Advanced JSX attributes and directives” headings by removing the older custom-events subsection and promoting subsequent sections.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| class NameEvent extends CustomEvent { | ||
| type: "Name"; | ||
| detail: { name: string }; | ||
|
|
||
| constructor(name: string) { | ||
| super("Name", { detail: { name } }); | ||
| } | ||
| } |
There was a problem hiding this comment.
Fixed in 8a1566e. Using CustomEvent<{ name: string }> generic now, dropped the field declarations entirely.
| import type { JSX } from "solid-js" | ||
|
|
||
| const handler: JSX.EventHandlerWithOptions<HTMLDivElement, Event> = { |
There was a problem hiding this comment.
Fixed in 8a1566e. Added semicolon after import, removed the extra space.
|
|
||
| ##### Using native events with `on:` | ||
|
|
||
| By default, using native events like `mousemove` with the `on` prefix — for example, `<div on:mousemove={e => {}} />` — will trigger a TypeScript error. |
There was a problem hiding this comment.
Fixed in 8a1566e. Changed to on: prefix throughout that section.
| declare module "solid-js" { | ||
| namespace JSX { | ||
| interface CustomEvents extends HTMLElementEventMap {} | ||
| } | ||
| } |
There was a problem hiding this comment.
Good call. Added a parenthetical note: 'which covers HTML element events -- not Document or Window events'.
- Use CustomEvent<{name: string}> generic instead of field declarations
- Fix semicolon and whitespace in EventHandlerWithOptions example
- Change on prefix to on: prefix for clarity
- Note that HTMLElementEventMap covers HTML element events only
The TypeScript page had
on:___event handling docs split into two disconnected places, and some headings buried too deep to appear in the page outline. This PR fixes all the issues raised in #569.What changed:
Moved
on:docs into the Event handling section. The "Custom event handlers" content was living under "Advanced JSX attributes and directives" even though it's just another way to handle events. It's now anon:directive subsection directly under Event handling, where readers would expect to find it.Converted the native events callout to a real subsection. The guidance about extending
CustomEventswithHTMLElementEventMapwas buried inside a:::notecallout. It's now a proper "Using native events withon:" subsection, making it easier to discover and link to.Upgraded heading levels for Forcing properties and Custom directives. Both were at the
####level, which means they didn't show up in the page outline. They're now###so readers can navigate to them from the outline.Addresses all four items from #569.