Document events available per element

[timvdalen]

It would be good if the documentation on https://xel-toolkit.org/ included a list of events that are available for each element.

[jarek-foksa]

I'm planning to implement ./project update-docs script which should parse each x-*.js file and update corresponding HTML file with documentation. All required annotations (like @type, @attribute or @events) are already in place.

[timvdalen]

Sounds like a good plan, although I'm not sure the @events annotations are currently complete. Looking at x-button, https://github.com/jarek-foksa/xel/blob/144043f/elements/x-button.js#L28-L29, only toggle is documented, while the documentation examples use click (as you would expect).

x-menuitem documents no events at all, while listing for click on them works.

[jarek-foksa]

Note that x-button (XButtonElement) and x-menuitem (XMenuItemElement) are inheriting from the standard HTMLElement, which in turn dispatches the click event.

It doesn't make sense to document all the standard DOM events like click, dbclick, contextmenu, pointerdown, pointermove, pointerup, lostpointercapture, etc.

[timvdalen]

I guessed that, yes, but I still think there is some value in documenting that x-menuitem dispatches click events so you know that's the thing you should listen on.

I agree that this doesn't make sense for everything; x-label and x-card don't need click events. However, for elements that revolve around a certain (standard) event, I think it makes sense to make that clear in the documentation.

[tosolini]

i'm looking at the tabs, dont worry, but documentation seems incomplete. How content of each tabs is supposed to works?

[jarek-foksa]

@tosolini You should listen for "open", "close" and "select" events on <x-doctabs>. When the event fires, you are responsible for updating manually the visibility of your views to match the current state of <x-doctabs>.

[tosolini]

@jarek-foksa thanks but this was clear. I dont understand the correlation between button tab and tab content, usually a typical tab have button with id and related content near or other part of page with same id in the container. In tabs examples i dont see the content at all. For example the x-accordion is clear to understand.

[jarek-foksa]

<x-tabs> and <x-doctabs> widgets are responsible only for drawing the tabs, If you want a given tab to toggle some specific content with given ID, you should implement this behavior yourself.

This functionality is not provided out of the box because some apps might want to load the content associated with the tab asynchronously or perform other optimisations such as disconnecting the content from the DOM tree when it is not toggled.

[tosolini]

ok understood.

[jarek-foksa]

The new project website now documents the JavaScript API for each element.

[timvdalen]

Nice!