What to do with "demo"?

[justinfagnani]

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.

[georges-gomes]

demo to CustomElements and Package I get it 👍
What else do you see?

I would maybe restrict to one demo (vs array) because supporting multiple demos is an ergonomical challenge/question for the implementer of the "player". I don't think it brings much. IMHO.

When you see https://web-padawan.github.io/vanilla-colorful/
I think a single demo can do a lot of things already.

[thepassle]

Doing some strawperson-ing here just to get the ball rolling on this discussion again. I'm all for giving anything in declarations a Demo, I'm not sure about Modules though, how would that be documented? What do we demo for a Module if not its declarations?

I was thinking of having a kind field on Demo, so users could distinguish between different kinds of demos; maybe the demo is a url that links to something, maybe the demo is markdown, maybe the demo is a storybook story, etc.

I imagine it could look something like this:

export interface Demo {
  kind: 'storybook' | 'url' | 'markdown' | 'whatever?';
  source: string;
}

/*
 * @demo {markdown}
 * This is a description
 * ```html
 * <my-el foo="bar"></my-el>
 * ```
 */
class MyEl extends HTMLElement {} 

Which would output:

{
  kind: 'markdown',
  source: "This is a description\n```html\n<my-el foo=\"bar\"></my-el>\n```"
}

Tools/plugins could then easily iterate through a CEM and fetch all markdown demos, and stitch them together.

/*
 * @demo {url} https://whatever
 */
class MyEl extends HTMLElement {} 

/*
 * @demo {storybook}
 * ???????????
 */
class MyEl extends HTMLElement {} 

I'm not entirely sure how we'd go about Storybook here, in the sense of; how do we document it? Just write an actual storybook story there? What does that mean for the CEM schema if storybooks way of creating stories changes?

[Westbrook]

For "storybook", I'd say it would be better to lean into the CSF format: https://storybook.js.org/docs/react/api/csf and speak in that language directly. In this way, if Storybook decided to move away from it at some point, we'd not be in as large a bind as CSF is structured for cross tool usage and means alternative "formats" would likely have new names, even if used by Storybook.

If we went this way, it would be cool if there was a types reference format that we could point to the actual story in a separate story file. Maybe?

/*
 * @demo {csf} {import('./my-el.stories.js').Default}
 * @demo {csf} {import('./my-el.stories.js').styles}
 * @demo {csf} {import('./my-el.stories.js').complex}
 */
class MyEl extends HTMLElement {} 

I could also see a nice plugin supporting the automatic association of these across files, etc.

[daKmoR]

Defining demos

I personally don't believe in standalone demos anymore. Most demos should have at least a specific headline and an intro text.

And once you start adding extra stuff it's probably easier to "just" go the markdown route...

So you could say we show the Readme.md by default and offer some special handling for js script and js preview-story

# Lion Forms

```js script
import { html } from '@mdjs/preview';  
// 👆 this makes sure that the `html` matches with the `render` of preview-story 
// e.g. it can render independent of the used lit-html or lit version (or if lit is not used at all for the component)


import '@lion/input/define';
import '@lion/form/define';
```

A web component that enhances the functionality of the native `form` component.
It is designed to interact with (instances of) the [form controls](https://github.com/ing-bank/lion/blob/8a322836ce238bd09d6c73f1a947d130e01cb697/docs/components/inputs/overview.md).

```js preview-story
export const main = () => html`
  <lion-form>
    <form>
      <lion-input name="firstName" label="First Name" .modelValue=${'Foo'}></lion-input>
      <lion-input name="lastName" label="Last Name" .modelValue=${'Bar'}></lion-input>
    </form>
  </lion-form>
`;
```

and then you would get something like this
https://lion-web.netlify.app/components/inputs/form/overview/ (only the right content side)

Supporting multiple pages

I have already made components (with docs) for multiple catalogs and they usually only support a single README.md and honestly, it's never enough... if this limitation exists teams will always build their own docs pages... and then adding only a link is probably better 😅

So instead of using a README.md I would say show all files in the docs folder.

Example File Structure

Single component

docs/index.md
docs/Details.md
docs/API.md
src/my-el.js
package.json

Multiple component

docs/index.md
docs/my-el/index.md
docs/my-el/details.md
docs/my-el/api.md
docs/foo-el/index.md
docs/foo-el/details.md
docs/foo-el/api.md
src/my-el.js
src/foo-el.js
package.json

For ordering we could add meta info into the filename 01-index.md, 02-details.md
or into the markdown header # Overview || 1, # Details || 2

PS: I'm probably biased as that is sort of the system we are currently using to show our own docs - but yeah it was born out of a need and so far it has worked amazingly well.

[thepassle]

I definitely think we need a way of supporting multiple kinds of demos though. The problem I see with your suggestion is that it assumes people have a README.md (or other named md files). While I agree generally components should have documentation files, we cant really make that assumption, and we also cant really guess which md file belongs to which custom element (in the case where a package contains multiple custom elements).

[bennypowers]

My opinion is to have demo be an optional URL or URL array, maybe maybe with title attr

Any kind of structured data will perforce bake in assumptions about the demo-doing tech, which isn't what we're about

wc catalogue should be able to build a default demo from manifest, anyways

[thepassle]

My opinion is to have demo be an optional URL or URL array, maybe maybe with title attr

But this again assumes the demo is something that has an url