Running / viewing stories

[techanvil]

Hi, I've noticed there are demo folders for a number of the components, in turn containing stories which look very useful for getting a running example of the components.

They look like they might be integrated with the docs, but despite having run various build scripts under catalog/ (and having spotted https://material-components.github.io/material-web/), and also trying to run tsc to build the stories separately, I've not had any luck getting the stories to run.

Rather than keep digging into a potential rabbit hole, I thought I'd drop a line here to see if anyone can help out with some pointers on how to get these demo stories up and running, would be most useful if so.

Aside from this, I would like to say thanks for all the great work here, we are in the early stages of using these components in the Google Site Kit plugin and look forward to getting it into production.

Cheers,

Tom

[asyncLiz]

@e111077 might know, he's actively working on the catalog with stories. I think there should just be an npm script to start the catalog

[techanvil]

Hey @asyncLiz, thanks for getting back to me! Apologies for not being clearer in my first post, but I have also run the serve NPM script to start the catalog, it gives me the same thing locally as can be seen on the project's GH page https://material-components.github.io/material-web/, but although the story files are copied to the build folder (e.g. catalog/_prod/assets/stories), they are not transpiled from TS and I haven't found out how to correctly build/run them.

As you mentioned @e111077 is working on this maybe he can shed some light?

[e111077]

Heya glad to hear your interest in our stories.

The TL;DR

If it's not on the in-progress docs site or you want to mess around with the live build of the components:

1. Clone the repo
2. npm ci
3. cd into the catalog directory
4. If the docs for the component do not yet exist:
   1. Create a markdown file in /docs/components/<componentname>.md
   2. Add the header to the page:

   ---
   name: Visual Name to Appear on Sidebar (e.g. Text Fields)
   dirname: <directory name of the component e.g. textfield>
   ---

   3. Add this macro to the page to render the playground w/ stories

   {% playgroundexample dirname=dirname %}
   <!-- optional preview height and editor height args -->
   {% playgroundexample dirname=dirname, previewHeight=400, editorHeight=500 %}

   • Alternatively you can look at the implementation of /catalog/eleventy-helpers/shortcodes/playground-example.cjs
5. run npm run dev
6. Navigate to the page in the sidebar and expand the interactive demo
   • Note: The first load will take a long time since it needs to fetch the unbundled library from unpkg as well as the huge babel TSC binary to run on the browser. Subsequent navigations to the page will have caching

The Background

So internally at Google we have a stories system built by a few of us on the Lit team and we use these stories as a means of development and documentation for some of our internal clients. We wanted to provide, editable, live demos for 3rd party users externally but did not want to open source the stories system in its current form because it has a lot of google-specific or IE11 cruft in it. Additionally, we wanted to keep the same workflow internally as externally.

Material Stories Implementation

This implementation of the stories system is a slimmed down version of what we have internally, so the APIs match, but it's missing a lot of IE 11 stuff and Google testing hooks.

Additionally, it's all written in such a way that they are ingested by https://github.com/google/playground-elements. This means that it does not touch our component build system and pulls from https://unpkg.com (latest npm).

To get all this to work, the catalog build system does the following:

1. finds all the stories in the repo
2. copies them to /catalog/stories/<component dirname>/
3. simulataneously the build system finds all the markdown docs in /docs/components/
4. performs some transformations on the markdown files from github syntax -> 11ty markdown syntax
5. outputs the transformed the docs to /catalog/site/components/<component-name>.md
6. 11ty renders the markdown file and in particular the playgroundexample macro to point playground-elements to the right config files in /catalog/stories/<component dirname>/project.json

Potential features

Currently we do not have the stories hooked up to a build system externally, which is fine for us since internally it's hooked into a more robust build system and we develop from a google-source-of-truth (even for incoming PRs). Though incoming PRs seem to run into issues here since users can't seem to get build errors when making changes to the stories.

An evolution of hooking it up to a build step would be a dev server to simply just serve the individual playground.

Additionally there are issues with skew. The source code in the stories is a tip of github head, but the live environment inside of the playground pulls from @latest on NPM. This causes some issues with mismatch with file refactors and maybe new features. Probably can solve this with switching from GH pages to firebase and provide staging links / release only on npm release

I hope this answers your question, and I'd be interested to hear what you think and how helpful you find them.

[techanvil]

Hey @e111077, many thanks for the detailed overview of the stories system and implementation. Following your instructions I've been able to view the stories for components which aren't yet in the catalog.

I ran into one small issue getting it working - when running npm run dev, I got an ELOOP error as below. It turns out this is due to node_modules/@material/web being symlinked to the repo root, causing an infinite loop with some aspect of the tooling. I didn't spend too long digging into this, as I found simply deleting the symlink was sufficient to allow the catalog & stories to run. Not sure if it makes any odds but I am on a Linux machine (Ubuntu) and have not tried on another OS as yet.

Error: ELOOP: too many symbolic links encountered, stat '/home/tom/git-public/material-components/material-web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/@material/web/node_modules/material-web-catalog'

# Note that @material/web symlinks to the repo root:

$ ls -l node_modules/@material/web
lrwxrwxrwx 1 tom tom 5 Jun  6 11:34 node_modules/@material/web -> ../..

The stories (and the docs in general) are extremely helpful, and will save a lot of time in terms of discovery, particularly being able to view the stories for those components which are not yet documented, but also in general, it's a really useful aspect of the documentation.

Of course I note the issues with them you've highlighted, and it's again most useful to be aware of these things, notably the skew aspect with regard to my own usage to date, but it's all very good exposition. I will be following your progress with interest :)

Thanks again for all the help!

[e111077]

Great to hear you got it working. That error is troublesome, the only thing I can think that could be causing this is our introduction of NPM workspaces. What version of NPM are you running?

[techanvil]

Aha - good shout there. I'm using Node 18.14.0 and was on NPM 9.3.1. I've bumped to npm@latest, which has brought me up to 9.7.1, and despite the symlink still linking to the repo root, I don't get an error when running the catalog. Nice one!

[Aamir333]

Answer nothing Above there is a villa of something before, but in 2 i got that stuff 2nd goood work. Thank you

[e111077]

Hello, since this original comment the immensely intelligent @vdegenne has tracked down and fixed the invalid configs and memory leaks! Please file an issue if you are still seeing these problems

[techanvil]

Hey @e111077, thanks for the heads up. I figured I'd give it a quick spin, went back to NPM 9.3.1 and re-ran the catalog - no memory leak. Nice work @vdegenne! 🎉