Open tjcrowder opened 6 months ago
Absolutely, any time/writing you'd be willing to donate would be massively appreciated!
The docs are fairly simple, every page is a markdown file living in content/*
. The TS doc specifically lives here. I need to update the contributing doc (sorry!), but it's just a matter of running npm install && npm run dev
, with the docs site opening at localhost:8080
. You can edit the markdown and it will be reflected on the page (might need a refresh, we have a Vite migration underway and I can't quite remember if Webpack reloads or not).
I think it's fine to say TargetedEvent
is on JSX
without any mention of that changing, as the PR seems to have been stalled. I'm not familiar with some of the intricacies there, couldn't say whether it'll ever land. We certainly try to avoid any breaking changes, so these types will live on JSX
at least for the lifespan of 10.x
Explain why TargetedEvent is re-exported by preact/compat (but its subtypes aren't). (?)
Types are generally added to compat when someone asks for them. If something's missing that's needed, feel free to add. Should just be a matter of re-exporting here. I don't think there's any intent on not offering anything.
Otherwise, this sounds brilliant! Anything you add would be super appreciated, we obviously haven't touched the TS doc in a while.
Thanks for the orientation, @rschristian! Looks straightforward.
Thanks also for your comment on SO, sorry for my misunderstanding. Is there someone on the team we could check with about this? I want to be sure to provide the right guidance in the docs. It seems to me that using TargetedEvent
on the types of the onXyz
properties on the HTML elements strongly suggests that that's the current thinking for how to type handler parameters (though you can of course use the DOM types as well), but if I'm wrong or possibly wrong there I'd like to get it straight so I can document it correctly.
No worries of course, I just didn't want to lead you down the wrong path is all.
@marvinhagemeister and/or @JoviDeCroock might be more familiar, if they have the time (context, https://github.com/preactjs/preact/issues/4309).
@marvinhagemeister @JoviDeCroock I'm still keen to contribute an update to this section, but I don't know what to write, it really depends on what the Preact team's position is on typing event handlers. jsx.d.ts
uses TargetedEvent
for EventHandler
so that's what's inferred for the onXyz
props, but when I went to run with that @rschristian said he wasn't sure they're "the current way" (in a comment on a now-deleted answer to this SO question). What would you like to see documented for this?
TargetedEvent
and its relatives?TIA
I personally point folks at these types https://github.com/preactjs/preact/blob/main/src/jsx.d.ts line 1496 MouseEventHandler for instance. When defining the event handler outside of JSX these helpers should enable you
@JoviDeCroock Thanks! Those use TargetedEvent
, so are you saying Option 1? Or Option 4 (use the XYZHandler
types and avoid using TargetedEvent
and its relatives directly)? Or...
I usually type the event handler's parameter rather than the handler as a whole (not least so I can use a function
declaration), so the XYZHandler
types aren't what I'd naturally reach for. But if that's the preferred approach...
What I'm saying is that from my point of view both work, I personally am a big fan of using the Handler
approach but I can also see why folks prefer using TargetedEvent
directly so I would document both.
@JoviDeCroock Thanks, sounds good!
Here's my revised list of what I propose to cover:
MouseEventHandler
and suchTargetedEvent
and suchHTMLAttributes
on your own components that wrap DOM elements.FunctionComponent
(context).If folks are happy with that, I'll get going on it in the next couple of weeks.
Sounds great to me! Thanks again for looking into this.
Currently the typing events section of the TypeScript documentation just mentions DOM event types and using a
this
type annotation to control the type of the element associated with the event (which gives a useful type tothis
but not toevent.currentTarget
). But now,TargetedEvent
and its subtypes are used in the definitions of event types on HTML elements and provide a way to typecurrentTarget
via a type argument. I think the section should be updated and expanded. I'd be happy to do a PR for it. (I may need some guidance, I haven't done any Preact docs stuff before.)I'm thinking the update would:
TargetedEvent
and its subtypes.event
).TargetedEvent
is onJSX
currently, that may change (if it's still true that it may change?).TargetedEvent
is re-exported bypreact/compat
(but its subtypes aren't). (?)HTMLAttributes
on your own components that wrap DOM elements.Would a PR along those lines be useful? If so, should it cover anything else?