mattrosno
commented
1 year ago At this point, our Storybook demo links and live demos are nice because we just have to update URLs and not have a programatic dependency on CSF modules.
It's my recommendation that we don't pursue this until we know if there are any new embed options in Storybook v7. (For example, it would be great if we could embed controls.)
If we want to index sub-components for search purposes, that's something that we could add to the schema. But that doesn't seem high priority at the moment.
For now, when we have a component like Dropdown, that is actually built using multiple components, we could index that like this in the Carbon React library:
demoLinks:
- type: storybook
name: ComboBox
action: link
url: https://react.carbondesignsystem.com/?path=/story/components-combobox
- type: storybook
name: Dropdown
action: link
url: https://react.carbondesignsystem.com/?path=/story/components-dropdown
- type: storybook
name: MultiSelect
action: link
url: https://react.carbondesignsystem.com/?path=/story/components-multiselect
tay1orjones
Summary
Related to https://github.com/carbon-design-system/carbon-platform/issues/1443, I've been thinking about what (if any) benefits we could get out of consuming Component Storybook Format (CSF) ES6 modules.
Links:
CSF is an open standard based on ES6 modules. It's how we write our Storybook stories. It's supported for all JavaScript frameworks. It allows you to get information about a component without using Storybook, such as:
The Carbon React library does not export stories JS files in its code package, so I haven't tested this, but assuming that stories are exported and available for consumption in Carbon Platform... how could this help us?
Job stories
TableActionList, I want to find its parent component, so I can view the documentation for how to use the subcomponent.Subcomponents
Do we want to index subcomponents? For example, the
DataTablecomponent has these child components:Table,TableActionList,TableBatchAction,TableBatchActions,TableBody,TableCell,TableContainer,TableExpandHeader,TableExpandRow,TableExpandedRow,TableHead,TableHeader,TableRow,TableSelectAll,TableSelectRow,TableToolbar,TableToolbarAction,TableToolbarContent,TableToolbarSearch,TableToolbarMenu.This is information that we could get from CSF. E.g.:
API documentation
Carbon's website does not surface component API documentation. Storybook is good for this. For example, here is the API documentation for using
Accordion,AccordionItem, andAccordionSkeleton:https://react.carbondesignsystem.com/?path=/docs/components-accordion--default#component-api
At the time of writing this issue, that Storybook site is showing the latest version of Carbon React,
@carbon/react@1.16.0.What if you want to reference the component API for an older version of the Accordion? Our only option is to go all the way back to the last major version and reference this separate Storybook site:
https://v7-react.carbondesignsystem.com/?path=/docs/components-accordion--accordion-story
If we consumed component prop tables directly from source code and not from deployed Storybooks, then we could render a Code tab prop table for any library version, like:
https://next.carbondesignsystem.com/libraries/carbon-react/v11.16.0/assets/accordion
To reiterate the as-is: if you're using a library version that doesn't match deployed Storybook sites, your only option today to reference the exact component API is to reference source code.
Live demo properties
Let's say we wanted to add properties (and their values) to our live demo. We could manually set those in the MDX component, but that would become error-prone to stay up-to-date as the hosted Storybook is updated.
Is there any way that we could take the args table from CSF ES6 modules and use that in our live demos? In theory, yes, but there would still be multiple scenarios where those could get out of sync as the live demo embeds a hosted Storybook regardless of what library version that Storybook is using.