How to handle types

[justinfagnani]

When documenting a field of a custom element, we definitely want to describe it's type. Before TypeScript came along we almost would have certainly would have use JSDoc-style type annotation syntax, but TypeScript's type syntax might be more commonly known by now though.

So we could use that in the descriptor, for example:

{
  "members": {
    "foo": {
      "kind": "property",
      "type": "Array<number|string>"
    }
  }
}

But at the limit you need to support many TS-specific, non-concrete entries like interfaces and type aliases so that you can use them in types. Does this mean we should leave types completely out of the format and up to .d.ts files? That would degrade the usefulness for documentation tools that don't process type declaration files. TS declaration files are also harder to parse than JSON, requiring the whole TypeScript compiler.

Another option is to include much of the type-related information parsed by Microsoft's API Extractor: https://github.com/microsoft/rushstack/tree/master/apps/api-extractor

Since this tool produces JSON, it would be relatively easy for custom-elements.json generators to use it to parse TypeScript, then merge with it's own custom element specific parsed metadata.

[daKmoR]

For documentation purposes, it would be good enough to keep types more as "type hints". e.g. to give an idea of what it should be... it does not need to be a "real" type.

Examples:

• String (e.g. foo, bar, ...)
• Number (e.g. 1, 4342, ...)
• Color (e.g. #fff, orange, rgb(255,0,0), ...)
• Css Length (e.g. 10px, 10rem, ...
• Array (does NOT type content)
• Object (does NOT type content)

REAL type support I would consider out of scope and should be handled separately by searching for *.d.ts files.

So many tools will be fine with only custome-elements.json. e.g. documentation, playgrounds, catalog, ...

Some tools will need to "gather" more data to also give type safety. e.g. linters, editor plugins, ...

[justinfagnani]

I would really like for documentation viewers to be able to show all the HTML, CSS and JS APIs, and cross-reference JS API types to their definitions so we can provide full usage. That'll require better type annotations than the norm in jsdocs. TypeScript has a well-defined type syntax, while jsdoc-style ones vary quite a bit, especially if you include Closure types.

One thing I worry about when leaving this up to TypeScript declarations is that it increases the complexity of doc viewers. You can't just pull a .json file from unpkg.com, say, you must include a full TypeScript parser.

[daKmoR]

Do you have an example of what you want to show in docs?

right now I have it sort of like that

Property	Type	Description
backSide	Boolean	Boolean to switch between front and back
data	Array<RowData>	All items to displayed with a format of { name: 'foo', age: 12, position: 'a|b|c'}

e.g. optimal for "static" documentation - so can not click on RowData but still it gives all information even in just a README.md

But yeah you need to hand write these descriptions. If you don't this information is not there

Property	Type	Description
backSide	Boolean
data	Array<RowData>

I think even if it's not perfect it's already quite a good start... I just fear if we try to incorporate a full typing system into this... that it's a very deep rabbit hole and it will postpone any delivery "forever". Also, I can imagine that such a system might make it almost impossible to hand write custom-elements.json - which imho should be a goal.

Considering this we could have a typeHint for now which is "just" a string like Boolean, Array<RowData and "reserve" type for a real type system.

[KrisGraySFDC]

LWC had this same issue and thats why we ended up with two sets of descriptions per web component. There's the parsed type from the metadata and the documented type.

/**
 * Specify either a Dom Element or element Id
 * @type String | HtmlElement
 */
target = "domId";

// Psuedo format
meta: {
    attributes: [
      { name: "target", type: "string" }
    ]
},
documentation: {
    attributes: [
      { name: "target", type: "String | HtmlElement" }
    ]
}

If you're using Typescript, you would just use the type from the definition files, but if not do we surface "string" or "String | HtmlElement" to the user?

I'd advocate for documenting both, otherwise I vote for typeHint = metadataType || documentationType.

[evanplaice]

Types that map to TS types would be nice to have...

And types -- when provided -- should work as-is from a JS-specific perspective ¹

¹Even typed JS using JSDoc. TS 3.6 added the ability to generate *.d.ts typings directly from JSDoc docstrings

The problem is...

The greatest benefit of WC is that they can be consumed directly in HTML. As in, they unlock a whole new ecosystem of capabilities for users who have little-no knowledge of JS.

From a HTML-specific perspective, there are only 2 possible types of attributes string|boolean.

string

<some-element string="somestring"></some-element>

boolean

<some-element bool-attrib></some-element>

What would hugely benefit the users¹

• auto-completion for attribute names
• inline documentation popups
• usable w/o access to documentation

In the absence of convenience tooling...

• can users quickly grasp how the WC is defined in HTML using custom-elements.json?

²Including Users who are less sophisticated in and/or lack JS/TS knowledge altogether

---

With that said, I don't see any downside to including a meta | metaType property for use in documentation, demos, etc.

{
  "version": 0,
  "tags": [
    {
      "name": "wc-markdown",
      "description": "A Markdown web component",
      "attributes": [
        {
          "name": "src",
          "description": "URL for the input markdown source",
          "type": "string",
          "required": true,
          "meta": "URL"
        }
      ]
    }
]

[justinfagnani]

@evanplaice types would only be for properties and methods. Attributes must be strings and instead of a type they might have some sort of enum or micro syntax as you see in the HTML spec. Supporting TypeScript type notation for the JS properties has no downside to HTML users.

[justinfagnani]

In runem/web-component-analyzer#140 @telpalbrox is asking for better union type handling. I think instead of case-by-case making type handling better via inlining and converting TypeScript types to something somewhat ad-hoc, we'll be better off adopting a full translation of TypeScript types into the analysis output.

[justinfagnani]

Just a note that this is still an open question, even though we've been developing a pretty extensive format that includes classes, variables, and functions in #9. It does not yet have interfaces and type aliases.

[thepassle]

I wonder what this should look like exactly. As far as I can see there are three scenarios:

• A user does not use types -> no type information available
• A user uses jsdoc types -> some type information available
• A user uses full typings with TS -> full type information available

[...] named as ButtonSize and output a reference to a definition of the ButtonSize type.

if I understand correctly, we could point to the typing file for the ButtonSize type

Considering those things, we could have an optional TypeDoc maybe? e.g.:

export interface TypeDoc {
  /** JSdoc type or TS type */
  type?: string;
  /** Reference to the definition of the type in case of TS */
  declaration?: string;
}

export interface FieldDoc {
  // ...
  type?: TypeDoc;
}

Similarly for methods we could have an optional InterfaceDoc

[justinfagnani]

I went looking for API Extractor's representation of types it's kind of interesting. There's a balance between a string-only representation that would make cross-referrences difficult-to-impossible to build, and a full tree representation of the type expression, which could be cumbersome and have to keep up with changes in type syntax.

What I think we could do that is similar to API extractor is treat the type as a string, but have an optional list of references that index into the type string.

ex:

export interface TypeDoc {
  /** JSdoc type or TS type */
  type: string;

  references?: Array<TypeReferenceDoc>;
}

export interface TypeReference extends Reference {
  // start and end must both be present or not present.
  // if they're present, they are indices into the `type` string
  // if they are missing, the entire type string is the symbol
  // referenced and the name should match the type string
  start?: number;
  end?: number;
}

export interface FieldDoc {
  // ...
  type?: TypeDoc;
}

I think this should work equally well for JSDoc types or any type system really, because all we care about is the string representation and references which tools understanding specific type annotations will generate.

wdyt? cc @rictic @runem

[bennypowers]

What about making a type declaration type, which you'd reference by package and module like the rest?
it could have optional params and properties, like this partial:

{
  "modules": [{
    "path": "./types.ts",
    "exports": [{
      "name": "FooOptions",
      "kind": "type",
      "properties": [{
        "name": "foo",
        "type": "Array<D>"
      }],
      "parameters": [{
        "type": "string|number",
        "name": "D"
      }],
    }]
  }]
}

Guiding example:

We can generate this page from the current schema, with links to internal types,
But we can't generate a table of type params or properties from the current schema, so those links would have nowhere to go to, save bespoke content

[thepassle]

What about making a type declaration type,

I'd really prefer to stay as far from this as possible and avoid becoming an alternative/substitute for type declaration files.

iirc, if useSubscription is a function, that means the CEM should already list its return type, right? Function params/return types are supported by the current schema?

[bennypowers]

There's a markdown summary on parameters that I can just manually add a table to, If we added the same to return that would cover a lot of my case for now. The author would still need to manually link types inside, but I'm ready to do that with a postprocessor for now. WDYT @justinfagnani

See #32