Enabler: Enable a way to preview complex components in documentation site.

[bryanpizzillo]

Enable a way to preview complex components in documentation site.

ESTIMATE TBD

There are components, specifically the NCI Header, that cannot be just added to a preview. There are a number of assumptions as to positioning (e.g., the header is at the top of the page) that should be made, but previews do not always appear in the perfect places as the previews show in the middle of the page. Also reflows based on breakpoints are also hard to handle within the previews.

We should take an approach like USWDS does for their header where the preview is actually a screenshot that links to a full HTML page with working JS.

NOTE: ❗❗ There should be no janky must build ncids-css/ncids-js and copy files first. This should ALL be done as part of the doc site build.

Notes

• Gatsby is a React app that builds static HTML, while also including a little Gatsby js within that static HTML. So this is not a straightforward just add a .js file to the head block on a gatsby page and everything works. We had to jump through many hoops to get HTML previews to display, React previews are even worse. So we should NOT try and have anything Gatsby related for generating these "full-preview" pages. Maybe we place .html files in the static Gatsby folder so they are copied over.
• Gatsby inlines all CSS into its pages. So it never generates a ncids.css or a site.css. You will need CSS, and built javascript on those pages.
  • You may be able to build a custom css & js using special rules in gatsby's web pack, publishing to the public static folder. Then you can just use those static files in the HTML.
• Sprites will most likely be a problem, both foreground and background. I recommend inlining for both if possible.

Note: This ticket is related to #938 and #945, as they both involve previewing both the component and the code for the component.

[bryanpizzillo]

I think the easiest solution for this is to publish the ncids-js-testing example site to a folder under the documentation site. (Like we did for Storybook) This way we can just use the pages we are actually using for tests. We probably should also add something to the component to handle correctly linking to the demo site, as well as providing a screenshot for the thing we are previewing.

[sarinapadilla]

We will continue to develop a solution for this ticket based on the findings from #1164 .

[sarinapadilla]

This story is blocked by #1224.