search

webcomponents / custom-elements-manifest

A file format for describing custom elements
BSD 3-Clause "New" or "Revised" License
370 stars 27 forks source link

Requirements #5

Open justinfagnani opened 5 years ago

justinfagnani commented 5 years ago

What do we need to capture in the description file?

justinfagnani commented 5 years ago

From my comment here: https://github.com/w3c/webcomponents/issues/776#issuecomment-443018559

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

In addition, we'll probably want:

daKmoR commented 5 years ago

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)

You can see a complete example here https://github.com/webcomponents/custom-elements-json/issues/3#issuecomment-546750767

web-padawan commented 5 years ago

One thing not listed above is delegatesFocus feature.

justinfagnani commented 5 years ago

@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 commented 5 years ago

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 \ Provide a reference to an element so it get's focus after close
- initialDelay \ You can delay when the option action should happen
close Closes the Dialog
mzeiher commented 5 years ago

@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 commented 5 years ago

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 https://github.com/webcomponents/custom-elements-json/issues/7

bengfarrell commented 5 years ago

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 commented 5 years ago

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 commented 4 years ago

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