Ability to document type of detail property for CustomEvents

[superchris]

I don't know if there is a way to do this that I'm not aware of, but it would be great to add more type information about the detail property of CustomEvents that an element can dispatch. Thanks!

[veith]

This would be a nice feature, because a lot of the events of a web component is a custom event. Having CustomEvent only as documentation is not enough.

But this would mean that types must also be definable, because having Object as detail is also not very useful.

For string, number and boolean this is no problem.

....
"events": [{
  "name": "layout-changed",
  "type": {
    "text": "CustomEvent",
    "detail": {
      "type": {
        "text": "string"
      }
    }
  }
}]

Maybe something like a OpenApi / swagger type definition could work?

[grimly]

Maybe something like a OpenApi / swagger type definition could work?

I had the same idea but then what about functions that would be placed in that event ?
JSON Schema cannot represent functions.

I came myself to the conclusion the current Type is actually enough for this issue.

Here is an example. Let's say you are working on a component and you want to send an event relative to an Event (I'm reusing the resources of this repo ;) ). You would describe your event as such:

{
  "name": "event-selected",
  "type": {
    "text": "CustomEvent<Event>",
    "references": [
      {
        "name": "CustomEvent",
        "package": "global:"
      },
      {
        "name": "Event",
        "package": "https://raw.githubusercontent.com/webcomponents/custom-elements-manifest/main/schema.d.ts"
      }
    ]
  }
}

In order to use those types with Typescript, a compiler would find all those package, import them, then immediately use text as the type.

[veith]

After thinking for a while about that topic, it seems to me that the OpenApi and Typescript idea is not a good solution.

The schema contains already a FunctionDeclaration, ClassDeclaration, Type (which is used in the VariableDeclaration and other places)

It looks to me that detail should accept functions or types or whatever can be assigned to the detail of a CustomEvent. So having a TypeDeclaration and the detail specified should do it.

[grimly]

I think you're too focused on CustomEvent and your proposal tend to develop into a full AST.

The point is to create documentation, not make its redaction impossible. You can start from a design before you start developing.

[veith]

@grimly There is more then the documentation use case.

Editor Support
Developers using custom elements should be able to get full-featured IDE support including auto-completion, hover-documentation, unknown symbol warnings, etc. These features should be available in HTML files, and in various template syntaxes via template-specific tools.

• I use the manifest to create web-types and having code completion and component documentation inside the IDE.
• And yes, I also use the manifest to create stories for storybook and other documentation systems.

BTW, I like your idea to write the manifest first and develop later.

As i understand the feature request from @superchris , this should be an optional feature.