Requirements

[justinfagnani]

What do we need to capture in the description file?

[justinfagnani]

From my comment here: WICG/webcomponents#776 (comment)

These are things that describe the basic HTML, DOM, & CSS structure of an element:

• Tag name
• Defining module
• Attributes
• DOM interface
  • properties
  • methods
  • superclass
• Events fired
• CSS variables
• CSS shadow parts
• CSS custom state
• Slots
• Default ARIA roles
• Permitted content
• Permitted parents
• Form participation

In addition, we'll probably want:

• Demo location (hosted or packaged)
• Typings
• Libraries used
• Design system used
• Tags
• Collection membership
• Additional non-standard protocols supported:
  • Theme systems
  • Context / dependency injection, pending-tasks, etc.

[daKmoR]

I am a little afraid if we put here all the things that are potentially nice - that it will be just wwaayyy too much.

Let's focus on what are the must-haves for an MVP then go for it and then adjust from there.

I would say must-haves are (all have name, description)

• attributes (+ default, required, typeHint)
• properties (+ default, required, typeHint)
• methods (+ params)
• events
• slots
• cssProperties (+ typeHint)
• cssParts

You can see a complete example here #3 (comment)

[web-padawan]

One thing not listed above is delegatesFocus feature.

[justinfagnani]

@daKmoR a lot of what I included are necessary to document the material components. We absolutely need to document CSS shadow parts if we include them. There aren't a lot of methods, but those need to be documented as much as properties.

[daKmoR]

jup fully agree 👍 added methods (+ params) and cssParts

possible output example

Methods

Name	Description
open	Will open a dialog where you can define an initial action Params: - focusAfterClose <Element> Provide a reference to an element so it get's focus after close - initialDelay <Number> You can delay when the option action should happen
close	Closes the Dialog

[mzeiher]

@daKmoR the superclass is also important for extending built-ins (also interesting for an IDE to allow auto completion for the is attribute.
A general question regarding inheritance should the element information just contain the attributes/properties/events which are declared in the specific implementation or implementation + super class information merged (preferred). Otherwise there must be a field which defines the module/package where the super class is defined to pull the information from the packages custom-elements.json (which complicates things if you need to resolve custom-elements.json and merge them during runtime)

[daKmoR]

I should be the merged information 👍 as for many use case it should just be read this one file and you should have everything you need 🤗

For the inheritance I'm not sure how easy that is from the analyze tools size... let's discuss it separately at #7

[bengfarrell]

This might be a question rather than a requirement/feature request - I'm not sure. In my vanilla component, I'm piggybacking on some common event names that already exist in the DOM for my custom events.

For example, I dispatch a "playing" event, and I call it "playing" so that the tag has the power to use "onplaying" as an attribute.

It's not clear to me if this should be documented as an event, an attribute, or both. Maybe a special category is needed to get across the idea that this is an even that can be used as "onwhatever".

[bengfarrell]

I have another weird one. I'm likely looking to put non-slotted content as non-rendered DOM objects existing outside the Shadow Root that exist purely for reference and for the sake of placing in a tag to feed the component data. Basically exactly what A-Frame is doing. I assume this falls under "permitted content"? Maybe it's too much of an edge case to really consider in the spec, but something I'm likely to do

[jarrodek]

I would add an information whether a property is readonly or not. When only getter is created then a property is read only.