mattrosno
commented
2 years ago Hey team! Please add your planning poker estimate with ZenHub @alisonjoseph @francinelucca @jdharvey-ibm
Closed alisonjoseph closed 2 years ago
mattrosno
commented
2 years ago Hey team! Please add your planning poker estimate with ZenHub @alisonjoseph @francinelucca @jdharvey-ibm
mattrosno
commented
2 years ago Notes from today:
Outstanding questions:
v0.55.1 like Carbon platform.)
alisonjoseph
commented
2 years ago @mattrosno
- Would we have to support Storybook embed height configuration to hardcode heights? Or would we be able to dynamically set iframe heights (example)? Would there be any cross-origin blockers in doing so?
Need to test this, ideally we could dynamically set height.
- How would we handle versioning if we rely on Storybook embeds for documentation live demos? Even if we host versioned Storybook sites (which is no small ask), Carbon website versioning will be more robust. For example, let's say you're viewing an older version of a component docs like v0.55.1 Area component. For every embed, in our wrapper, do we need to call out that the embed is demonstrating the latest version of the component? (Storybook embed URLs aren't versioned v0.55.1 like Carbon platform.)
Could we have an asterisk when viewing older versions with a note that the demo is the latest version? I think its unrealistic for storybook to have all the versions published.
- How long will it take for Storybook embeds to render? Will it be noticeably bad? Acceptably bad? Non-issue
There is a slight delay, I put together a quick demo updating storybook url parameters
https://user-images.githubusercontent.com/2753488/173480154-033a30bb-f10f-41f9-8c68-aa5b947fa0eb.mov
- Does this mean we'd need a story for every non-image example shown in website? Because Storybook doesn't expose subcomponent controls, we can't put a component in any state through URL alone. We'd need a bespoke story in Storybook for each unique demo shown in website. Is that a bad thing? Could we have a convention in Storybook that stories in a "Demos" directory per component exist for website documentation?
Yes, we'd need a story for an demo we want to show, but I think thats ok. We have flexibility here on what makes the most sense to demo per component.
What sanitization would be needed so Storybook embeds aren't misused? 🤔
If we wanted to demo specific code versions, are there other good options like CodeSandbox or StackBlitz that act as instant, just-in-time, dev environments?
StackBlitz seems to be a no-go, and codesandbox is slow, but doable.
tay1orjones
commented
2 years ago @alisonjoseph Since we know the predefined parameters available via the dropdowns, could we preload or prefetch them to eliminate the delay?
In theory we could dynamically add link tags to the page with something like
<link rel="preload" href="https://storybookurl.com/iframe.html¶meter=something" as="document">@tay1orjones just tried that and I still see a white flash as the iframe src updates, however if I drop 4 iframes on the page it works seamlessly. Will need to test this with more than 4 variations, wondering if it might make the initial page load too slow?
https://user-images.githubusercontent.com/2753488/173594373-c03b5c09-e76f-4424-9450-8ec4d19c4825.mov
alisonjoseph
commented
2 years ago alisonjoseph
commented
2 years ago @mattrosno brought up an interesting question in slack.
how are you getting the variants? hardcoded for now or are you reading storybook source to get those (so that second dropdown is populated with what you see in storybook side nav)?
Would there be a way to dynamically pull what we want to show in the demo dropdowns from storybook, vs. the user having to define that I assume in the schema?
alisonjoseph
commented
2 years ago mattrosno
commented
2 years ago Loading options - let's say we do a fade loading animation where the iframe is opacity 0 and there's an opacity transition and when the iframe is loaded, we set opacity 100. (@carbon-design-system/carbon-platform-designers will probably have something better... but any loading animation could help so loading is smoother...)
Option 1 - onload
We could listen for iframe onload() event. That's easiest, but that might be longer than what we want. Worth trying.
Option 2 - postMessage()
https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
We listen for messages posted from the child iframes and then the parent acts accordingly. Some quick tests:
Our React Storybook isn't posting messages.
But the Angular Storybook is.
(I had to install a browser extension to print posted messages to console.)
If we wanted to go down this route, Storybook has an official package that we could use for each story to post a message (to the parent iframe) when the story has rendered. We could potentially also use this for the story to post messages on its required window height, etc.
https://www.npmjs.com/package/@storybook/channel-postmessage
If we go down this route, then every Storybook would need to emit messages according to our spec, so our demo iframes could listen for those posted messages, so it seems like if we want a loading animation, let's try option 1 first with the iframe onload() event.
mattrosno
commented
2 years ago Embed heights - for simplicity, it seems like we'd want to support a small, medium, and large embed heights and be comfortable knowing that embed scrollbars will happen on occasion. Then, later on we attempt to optimize with that postMessage() idea above if we want.
If we're supporting various embed sizes:
alisonjoseph
commented
2 years ago @mattrosno I think I'm going to need a demo to visualize what you mean for loading, the way you're describing it there would still be flash when you switched iframes before it faded in? or would we fade out then in? Would that be any better?
mattrosno
commented
2 years ago @alisonjoseph on iframe loading - I recommend quickly trying the frame onload() event and if that fires well after the iframe's component visibly renders... then it's not a dependable way for us to hide/show any sort of loading animation, and if that's the case I recommend no loading and we look into postMessage() optimizations later.
mattrosno
commented
2 years ago Version disclaimer - the only thing that platform will know is embed URL. Example:
https://react.carbondesignsystem.com/iframe.html?id=components-button--default&globals=theme:g10
That embed URL doesn't encode a version anywhere.
It would be nice for there to be a version disclaimer that we show in the footer of all embed frames that says something to the extent of:
View full demo for additional information such as its version, controls, and API documentation.
That "View full demo" would link you to this:
It's important to let our users know that the demo might not exactly match the version of the documentation that they are viewing. It's also nice to link out to the full canvas so they can play with the controls, view the API docs, etc.
mattrosno
commented
2 years ago Schema considerations - how will we get this on the asset overview page?
Option 1 - Add to schema
We could add an asset key to the schema like storybookEmbedUrl. But it'd actually be more complicated than that, because we'd need to specify options like embed height, embed width (number of columns), etc. It also brings up questions:
I believe there's a better option...
Option 2 - StorybookEmbed MDX component
We'll likely want to make a custom MDX component for Storybook embeds so we can embed demos throughout pages. The MDX component would have props to set the embed URL and its dimensions.
That means we'd add an overviewPath to the asset docs key so there's an MDX file that would fill a slot in the overview pages. That slot would go between the dashboard and the structured data at the bottom of the page for schema-driven content (related assets, etc.)
By doing this, an asset could just put a static image in there if needed when there isn't a Storybook embed (e.g. patterns) so the asset overview pages still show the asset (even if it's not "live").
This also sets us up to support other demos in the future if we want MDX components for CodeSandboxEmbed, etc. embeds.
Having an MDX "slot" in the middle of the overview page opens it up for asset maintainers to put other content in there, but especially during this first release, we can actively monitor that to ensure the markdown portion of the asset overview page just gets used as intended (live demos.)
alisonjoseph
commented
2 years ago Agreed that option 2 feels like a better choice, the amount of configuration options we would need to add the demo to the schema doesn't seem scalable.
kingtraceyj
commented
2 years ago I agree that MDX feels like the way to go.
alisonjoseph
commented
2 years ago Closing this as done ✅
Will open a new issue to build this component when design spec https://github.com/carbon-design-system/carbon-platform/issues/882 is done.
Collaborate with system squad and determine solution to replace component demos on the site.
Should we use Storybook embeds? Something else?
Do we need:
Acceptance criteria: