Given that some tools already support reading and writing the custom-elements.json format, should we take that as a starting point?

On the other hand, @octref has suggested starting from the VS Code Custom Data Format. Whether the format should be based on one IDEs format is a great question to answer.

There should be a way to signal whether or not a property reflects to it's associated attribute when set

@justinfagnani
sometimes attributes&properties are linked to a specific event like it was in polymer. or in lit with this addon: https://github.com/morbidick/lit-element-notify

shouldn't this also be reflected in the schema?

I think it would be helpful to specify a version for the custom element. For example, if I add a few major properties/events to an element, I should be able to say that the element is now version 2.0.0

Demo is an interesting bit of the schema. Right now it's only referenced from CustomElement#demos, but really, anything could have an associated demo, including or especially the package as a whole.

We could add a demos field to all declarations, modules and package. We could also add an extensible metadata field to just about everything and make DemoMetadata well-known object that can appear there.

Out of my point of view, I am only a ECMAScript Implamentator so I write interpreters and parsers and compilers Runtimes VM's such stuff. The Objects them self are the description of the component? It is Machine and Human Readable.

Sure it's big but that is how it works and that is what it is that's why it is what it is.

see https://github.com/JetBrains/web-types
and the comment here: WICG/webcomponents#776 (comment)

Catalogs and GUI builders would benefit from being able to show a custom icon. This could go in metadata. We should probably look for inspiration from PWA app manifests.

Why?

I know this is controversial, but I'm not entirely confortable about only self-define custom-element.
There is so much opportunity for tag collision...

I know there are other issues if we don't use self-define components but it will ultimately be resolved by Scoped Registries.

Additionally, I can see a number of use cases where it would make sense to control programmatically the tag name and the discovery of the class in a module. I would definitely need it in my project for example.

Cases

If custom-elements.json has a tagName then it was self define by the module.
If custom-elements.json has no tagName you need to define.

• option 1: The module expose the class as a named export.
• option 2: The module expose the class as export default.

Proposal

exportName = default | xxxxxxx in the schema
(xxxxxxx being the exported name of the class)

"custom-elements.json" is a filename and not necessarily a description of the file's contents or purpose. The file specific name also might not be required to be custom-elements.json. On npm it could be referenced from a package.json field, like the "types" field. In other systems, like databases, the name might not matter or even exist.

A few options to consider:

• Custom elements manifest
• Custom elements docs file
• Package docs file

Considering that the format will be capable of pretty fully describing package contents, being a "package docs file" might make sense. There very well might be other communities interested in shared docs infrastructure, even if that isn't a primary goal right now.

I would really like to have custom element attribute etc. type checking and I'm also really happy about the work you've put into this already, but..

Isn't TypeScript (and/or another typing tool like Flow) in a better position to support all of this? It already supports analyzing, declaring and checking types when it comes to classes, properties and methods etc. Specific support for custom elements including attributes, events, styles etc. and html parsing would have to be added. But in that case it could be used both in full fledged TypeScript projects during compilation and in JavaScript projects that only use the type checking part of their tools.

I don't want to force TypeScript on users. I'm definitely also open to using other existing tooling like Babel or Flow. But it seems that right now"types": "index.d.ts" is being published by most NPM packages; wouldn't it be great if that could just include all of this and we wouldn't have to install additional analyzing and linting tooling for our IDE's and CI?

The main issue I do recognize with this is that it will probably be difficult and take a lot of time to get support from the TypeScript team for this and/or contribute to it ourselves there. Still, even if we continue to work on solutions like this I think it might be interesting to simultaneously push and work towards what we think is the best final solution as well.

PS: Sorry if this is not the place to discuss this. But it seems like the related discussion is centering around here, so I've taken the liberty to create this issue.

Once we publish to npm and host the schema at a stable URL, we should remove schema.json from the repo as it's a generated artifact.

Documented here: #70

As in some situations, the tooling might not have access to a package.json, it would be beneficial to be able to indicate the location of the custom elements manifest in the html page. A meta tag should be enough for this.

This came up in a discussion with @claviska (https://github.com/claviska), when discussing CEM and DevTools support with the shoelace documentation site.

This would allow documentation sites to indicate the location of the CEM through a meta tag, allowing the devtools to find the manifest for an enhanced experience on the docs page.

Consider this case

class MyElement extends HTMLElement {
  constructor() {
    super().attachShadow({ mode: 'open' }).innerHTML = `
      <style>
        :host { color: var(--my-color, red); }
        @media (prefers-color-scheme: dark) {
          :host { color: var(--my-color, blue); }
        }
      </style>
    `;
  }
}

Should I get

"cssProperties": [
  {
    "name": "--my-color",
    "default": "red"
  }
]

Or

"cssProperties": [
  {
    "name": "--my-color",
    "default": "blue"
  }
]

And if I get either, that's not really correct is it?

We should add a schema facility for declaring multiple defaults and their conditions

Many analysis tools will use JSDoc tags to determine what web component specific features. To keep from fragmenting the ecosystem around different sets of JSDoc, we should make a recommended set of tags.

Tags will need to document the features in the CustomElement schema kind:

• Tag Name
• Attributes
• Events
• Slots
• CSS Shadow Parts
• CSS Custom Properties
• Demos

Maybe we could add a example string for inserting a component (with some default attribute and style values). So a Designer could use this info.

So what I mean in my designer:
https://github.com/node-projects/web-component-designer-demo/blob/1db285872f8c9173db00a33f9ede29f55af31cc2/src/elements-demo.json#L4
I have a list of attributes, but that sample could also be a html part string

@justinfagnani
are there any sample using this manifest?
I thought maybe lit already has one, but I could not find it.
What's the state of this?
What's the sate of rebooting custom elements catalogue?

We should standardize on a package.json field to use to point to a custom elements manifest. This is important for indexers and catalogs that might need to inspect npm package for custom elements. The npm registry API allows callers to fetch the package.json metadata without fetching and unpacking the package's tarball.

I'm not sure if this is intentional or not, but given this example:

https://github.com/storybookjs/storybook/blob/31e3ad8b816f8a0686d616309e100a7d0f3bad72/examples/web-components-kitchen-sink/src/components/sb-button.ts

that has the following attributes defined in the comments:

 * @attr {string} label - Label of the button
 * @attr {boolean} primary - primary
 * @attr {string} size - Size of the button, can be "small", "medium" or "large"; default is "medium".
 * @attr {string} background-color - Color of the button's background

The custom elements analyzer spits out:

   "attributes": [
            {
              "type": {
                "text": "string"
              },
              "description": "Label of the button",
              "name": "label"
            },
            {
              "type": {
                "text": "boolean"
              },
              "description": "primary",
              "name": "primary"
            },
            {
              "type": {
                "text": "string"
              },
              "description": "Size of the button, can be \"small\", \"medium\" or \"large\"; default is \"medium\".",
              "name": "size"
            },
            {
              "type": {
                "text": "string"
              },
              "description": "Color of the button's background",
              "name": "background-color"
            },
            {
              "name": "label",
              "fieldName": "label"
            },
            {
              "name": "primary",
              "fieldName": "primary"
            },
            {
              "name": "size",
              "fieldName": "size"
            },
            {
              "name": "background-color",
              "fieldName": "backgroundColor"
            }
          ],

This is probably because it parses the comments but still parses the Lit properties?
I would expect it to merge them like:

...
            {
              "type": {
                "text": "string"
              },
              "description": "Label of the button",
              "name": "label",
              "fieldName": "label"
            },
...

Is this a bug or intentional?

We probably at least want a JSON Schema file describing the spec, at least to validate tool output and to help generate file readers.

JSON Schema isn't the most human readable format though, do we want another format to develop the spec in and present in the main README?

Parameter and other types have a markdown summary field which our user could populate with a table to represent a property bag.

It would be helpful to include that summary on the return type of functions and methods so that they can document the properties of return types.

This is an easy escape hatch for many typings-related issues and could be a good way to "thread the needle" of flexibility vs API pollution.

@justinfagnani
I've some Webcomponents wich only use the Attrbiutes Values, when they are set at object creation. They do not look for attribute/property changes.
Is this something we should describe also?
So a designer knows, do I need to change they attribute, the property or do I need to recreate the whole element.

Salesforce is quite interested in capitalizing on a manifest like this for a range of projects. I believe the proposed state of schema.ts already covers the majority of Salesforce's requirements. The remaining requirements are rather proprietary, and could be addressed with general-purpose mechanism for including custom data in a manifest.

This could be achieved by:

1. Adding a standard, unrestricted custom key to the top-level schema.
2. Recommending a strategy for component authors or tool vendors to further subdivide that custom key. Example: an organization adding custom data should do so inside a key containing a relevant domain name they own.
3. Encouraging tools to either ignore custom keys they don't understand, or to perform generic processing of anything they find there. Type-checkers could potentially ignore all that data. A doc tool could either skip the custom data, or format it as a pretty-printed JSON block or table as supplementary documentation.

Example: Using some hypothetical custom data values taken from Salesforce's own internal requirements, a Salesforce component might include the following in its manifest:

{
  "custom": {
    "salesforce.com": {
      "apiVersion": "53", /* Salesforce platform API version targeted by this component */
      "formFactor": "mobile", /* Component is designed primarily for mobile use */
      "capabilities": [ /* In which product environments is the component capable of being used? */
        "dashboard",
        "communities"
      ]
    }
  }
}

Something like this would minimize the impact on the schema design, give component creators a way to include component metadata in a single place, and increase the chance that a tool created by one group could be used by a different group without choking on unexpected custom data. This would also provide a means of trying out new ideas for schema fields before standardizing on them.

We should also have a configuration to tell if a WebComponent is a container for other elements (maybe a array of querySelectors wich define possible elements)

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.

Beyond goals and motivations as the readme currently has, we need to explain the schema and rationale for some of the decisions.

It would be useful to flag members as deprecated

"members": [
  {
    "kind": "method",
    "name":  "dismiss",
    "deprecated": "use `close()`"
  }
]

deprecated could be a boolean or a string, and could apply to almost all the types in schema.d.ts. certainly to ClassLike, FunctionLike, and ClassMember.

Consuming Tools could use this to warn the user about this member, like typescript lang server does for @deprecated jsdoc tag

So the manifest should list the possible values, so a designer could use them.
also a min/max for a number could be usefull

I've the following Properties for a Property in my designer:
https://github.com/node-projects/web-component-designer/blob/master/src/elements/services/propertiesService/IProperty.ts

It will be useful to discuss and record specific goals and non-goals.

Two examples:

• Many view libraries allow you to create components that they roughly call "web components" that aren't actual W3C custom elements. Some of these can be used in HTML-like syntaxes, like Angular and Vue templates. Should it be a goal or non-goal to describe these components too?
• Custom elements are JavaScript objects, and their descriptions are a superset of JavaScript. Should it be a goal or non-goal of this description format to completely document the JavaScript-side of the component interface?

currently, it says

Referencing manifests from npm packages

In order to allow tools to find npm packages with custom element manifests without having to download package tarballs, > packages should have a "customElements" field in their package.json that points to the manifest:

{
  "name": "example-package",
  "customElements": "custom-elements.json",
}

but if you are using an export map

"name": "my-package",
"customElements": "custom-elements.json",
"exports": {
  ".": "./index.js"
}

then the files can not be imported... e.g. this will fail

import cem from 'my-package/custom-elements.json' assert { type: 'json' };

Suggestion

Replace the custom property with an entry in the export map.

Benefits:

• resolving is depending on an import map or the node resolution system
• file is always accessible as it's part of the export map
• not 2 different ways of defining an CEM

- "customElements": "custom-elements.json",
+ "exports": {
+  "customElements": "custom-elements.json",
+  ".": "./index.js"
+ }

It would be helpful to mark a class field or property as readonly (i.e. getter only or defined as writable: false)

{
  "name": "elements",
  "type": "readonly ApolloElementElement[]",
  "readonly": true,
  "attribute": false,
  "summary": "List of all ApolloElements registered to this client."
},

As far as I could tell there's no schema to identify a spread parameter:

This could be useful for class methods or functions that take a spread:

  protected notify(...keys: (keyof this)[]): void {
    this[update](Object.fromEntries(keys.map(x => [x, this[x]])));
  }

Both standard components (e.g. table, tr, td, dl, dd) and web components (e.g. tab-panels, tab-panel) have implicit constraints on what elements are allowed as children, and also what are allowed as parents.

I would propose that a slot description should also include a way to codify this.

For example:

export interface Slot {
  /**
   * The slot name, or the empty string for an unnamed slot.
   */
  name: string;

  /**
   * A markdown summary suitable for display in a listing.
   */
  summary?: string;

  /**
   * A markdown description.
   */
  description?: string;

  /**
  * A set of CSS selectors for allowable children
  */
  allowedChildren?: string[];
}

Summary

Today, there's no way to provide type-hints to consumers about a CSS custom property (e.g. '<color>', '<length>', etc.) This requires component authors to have very explicit property names (--my-foo-color) or document the property adequately in the description. Unfortunately, neither is suitable for IDE intellisense support.

Chrome has shipped the CSS @property rule and enabled by default as of 85, and the CSS Properties and Values API as of 78.

Proposal

Add a "type" property to the Custom CSS Property schema. Manifest consumers can treat the omission of this value as '*', which I believe is the default behavior of Custom CSS Properties.

We can additionally strongly type the TypeScript declaration schema with all the legal string values

Consider the following code:

class DisabledElement extends LitElement {}
class MyInput extends FieldMixin(DisabledElement) {}

how would we save this nicely to the json?

strawman proposal:

{
  "tags": [
    {
      "name": "my-input",
      "inheritance": "FieldMixin -> DisabledElement -> LitElement",
      "properties": [
        {
          "name": "myInputState",
          "inheritance": "this"
        },
        {
          "name": "value",
          "inheritance": "FieldMixin"
        },
        {
          "name": "disable",
          "inheritance": "DisabledElement"
        }
      ]
    }
  ]
}

as this is probably not that simple to analyze? I thought we could postpone it? but yeah if anyone things that's easily doable by an analyzer and it totally make sense like this we could move forward with it?

I listed some initial use cases in the README. If there are additional use cases that should be added, propose them here.

We will hopefully soon have non-JS module types that packages may want to advertise, and that may be the target for references. CSS custom properties may be defined in a CSS module rather than a JS module.

I don't think we should spend too much time defining the schema for non-JS modules now, but we should probably allow for different module types by encoding a kind discriminator.

export interface PackageDoc {
  version: string;

  /**
   * An array of the modules this package contains.
   */
  modules: Array<ModuleDoc>;
}

type ModuleDoc = JSModuleDoc | CSSModuleDoc;

export interface JSModuleDoc {
  kind: 'js';
  path: string;

  /**
   * A markdown summary suitable for display in a listing.
   */
  summary?: string;

  /**
   * A markdown description of the module.
   */
  description?: string;

  exports?: Array<ExportDoc>;
}

I've added

    static get formAssociated() {
        return true
    }

to a custom element and run the script to generate the manifest. There doesn't seem to be any mention in the manifest that the control is associated to a form. This could be useful in a component directory if someone's looking specifically for controls.

I also saw there was no mention of this anywhere in the custom elements schema definition.

APIs need a way to describe object interfaces in a way that documentation can describe. ClassDeclaration has most of what we need, but includes some fields not suitable for interfaces.

coptic: Any interest in improving the controls? For example, size here has three options, so a radio is a little nicer than having to type in something IMO. If there’s 3+ it could default to a select maybe?

bennyp: This could maybe be automated from the type field in a custom elements manifest, however, we'd have to assume the type text is typescript in order to parse the union, where the manifest scema makes no such assumption

coptic: Ya that’s what I was playing around with. That’s a good point though not assuming TS. FWIW, stencils doc schema and generator is nice in that it does parse any union into a values array.

tl;dr: tools can't know for certain what kind of string the type text is. If we added a hint (per file, or per type), they could parse the type to do things like generate radio buttons for demos

per type:

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "my-element.js",
      "declarations": [
        {
          "kind": "class",
          "name": "MyElement",
          "members": [
            {
              "kind": "field",
              "name": "type",
              "type": {
                "text": "'number'|'string'|'boolean'",
                "kind": "typescript"
              }
            }
          ]
        }
      ]
    }
  ]
}

per file

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "my-element.js",
      "types": "typescript",
      "declarations": [
        {
          "kind": "class",
          "name": "MyElement",
          "members": [
            {
              "kind": "field",
              "name": "type",
              "type": {
                "text": "'number'|'string'|'boolean'",
              }
            }
          ]
        }
      ]
    }
  ]
}

I originally opened this issue on the custom-elements-manifest analyzer (open-wc/custom-elements-manifest#43), but I'm told this is a bug in the spec, so reopening here.

In the custom-elements-manifest analyzer playground, use this custom element:

class MyElement extends HTMLElement {}
customElements.define("my-element", MyElement)

You'll get this JSON:

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/my-element.js",
      "declarations": [
        {
          "kind": "class",
          "description": "",
          "name": "MyElement",
          "superclass": {
            "name": "HTMLElement"
          },
          "tagName": "my-element",
          "customElement": true
        }
      ],
      "exports": [
        {
          "kind": "custom-element-definition",
          "name": "my-element",
          "declaration": {
            "name": "MyElement",
            "module": "src/my-element.js"
          }
        }
      ]
    }
  ]
}

If you compare this to the schema, it doesn't match because of tagName on the ClassDeclaration.

You can repro using a simple TypeScript file:

import { Package } from 'custom-elements-manifest/schema'

const json: Package = {
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "index.js",
      "declarations": [
        {
          "kind": "class",
          "description": "",
          "name": "MyElement",
          "superclass": {
            "name": "HTMLElement"
          },
          "tagName": "my-element",
          "customElement": true
        }
      ],
      "exports": [
        {
          "kind": "custom-element-definition",
          "name": "my-element",
          "declaration": {
            "name": "MyElement",
            "module": "index.js"
          }
        }
      ]
    }
  ]
}

Then run:

mkdir test
cd test
npm init --yes
npm i --save [email protected] [email protected]
npx tsc index.ts

You'll see the error:

test.ts:18:11 - error TS2322: Type '{ kind: "class"; description: string; name: string; superclass: { name: string; }; tagName: string; customElement: true; }' is not assignable to type 'Declaration'.
  Object literal may only specify known properties, and '"tagName"' does not exist in type 'ClassDeclaration'.

18           "tagName": "my-element",
             ~~~~~~~~~~~~~~~~~~~~~~~


Found 1 error.

Expected behavior

I would expect the output schema to match the one from schema.d.ts.

The path property here:

is? relative to this file or relative to the package.json? has the extension within?

What do we need to capture in the description file?

add optional property that links members to source code

use case: docs sites that link element properties, etc to github source pages.

source code references are strings, could either be relative paths from package root or fully qualified URLs to e.g. github

class fields may be optional in implementations, likewise methods

class Base extends CanErrorElement {
  context?: any;

  onError?(error: Error, context?: any): void;

  thing() {
    try {
      that()
    } catch(e) {
      this.onError?.(e, context);
    }
}

While subsequent tooling could infer this from the return type, @justinfagnani rightly pointed out that there are some semantic differences, notably for error types, and perhaps for early returns too.

API tables would benefit from this flag as well:

{
  "name": "mutate",
  "async": true,
  "summary": "This resolves a single mutation according to the options specified and returns a Promise which is either resolved with the resulting data or rejected with an error.",
  "parameters": [{
    "name": "params",
    "optional": true,
    "type": "Partial<MutationOptions<Data<D>, Variables<D, V>>>",
    "summary": "All named arguments to mutate default to the element's corresponding instance property. So you can call `element.mutate()` without arguments and it will call using `element.mutation`, `element.variables`, etc. You can likewise override instance properties per-call by passing them in, e.g.\n\n```ts\nawait element.mutate({\n  fetchPolicy: 'network-only'\n  variables: {\n    ...element.variables,\n    name: 'overridden',\n  },\n});\n```\n\n| Property | Description | Type |\n| -------- | ----------- | ---- |\n| `awaitRefetchQueries` | See [awaitRefetchQueries](#awaitrefetchqueries) | `ApolloMutation#awaitRefetchQueries` |\n| `context` | See [context](../element/#context) | `Record<string, unknown>` |\n| `errorPolicy` | See [errorPolicy](../element/#errorpolicy) | `ErrorPolicy` |\n| `fetchPolicy` | See [fetchPolicy](#errorpolicy) | `FetchPolicy` |\n| `mutation` | See [mutation](#mutation) | `ApolloMutation#mutation`\n| `optimisticResponse` | See [optimisticResponse](#optimisticresponse) | `ApolloMutation#optimisticResponse`\n| `refetchQueries` | See [refetchQueries](#refetchqueries) | `ApolloMutation#refetchQueries`\n| `update` | See [updater](#updater) | `ApolloMutation#updater`\n| `variables` | See [variables](#variables) | `ApolloMutation#variables`\n"
  }],
  "return": {
    "type": "Promise<FetchResult<Data<D>>>",
    "summary": "A `FetchResult` object containing the result of the mutation and some metadata\n\n| Property | Description | Type |\n| -------- | ----------- | ---- |\n| `data` | The result of a successful execution of the mutation | `Data<D>` |\n| `errors` | included when any errors occurred as a non-empty array | `readonly GraphQLError[]` |\n| `extensions` | Reserved for adding non-standard properties | `ApolloMutation#awaitRefetchQueries` |\n| `context` | See [context](../element/#context) | `Record<string, unknown>` |\n"
  }
}

As per the spec, (https://github.com/webcomponents/custom-elements-manifest/blob/master/schema.d.ts#L85-L96), a default-exported class gets named "default". However in the Schema's Reference -type, used by the "superclass" property for example (https://github.com/webcomponents/custom-elements-manifest/blob/master/schema.d.ts#L149-L153), a "name" field is provided, and is always populated by the actual class name of the Javascript class.

When creating tooling, it would be useful to be able to look at the declarations of the superclass, but this is impossible with the current schema as if the class is default exported, the name is not found anywhere on the class' schema.

Proposed solution

Add a "className" or similiar field to the JavaScriptExport type. This would always be populated with the actual classname of the class, instead of "default" in default exported classes

We want to avoid duplication of data in the schema, but we also want to allow for easily querying a schema, or related collection of schemas.

Tools will want to answer questions like:

• What are all the elements in this package?
• Build an index from tag name to class, or class to tag name
• What is the entire class hierarchy for class A?
• Find all references to a symbol

We can make this much easier by building a shared library that given a set of package docs builds a queryable model from them. It should not live in this repository, but the people here would be interested in it.