chore: add storybook

.github/workflows/ci-docs.yml

@@ -31,3 +31,6 @@ jobs:
       - name: Test Docs
         run: |
           npm run test:docs
+      - name: Build Storybook
+        run: |
+          npm run story:build

.gitignore

@@ -4,4 +4,6 @@ coverage/
 dist/
 node_modules/
 .greenwood/
-public/
+public/
+*storybook.log
+storybook-static

.ls-lint.yml

@@ -19,3 +19,4 @@ ignore:
   - node_modules
   - public
   - .greenwood
+  - storybook-static

.storybook/main.ts

@@ -0,0 +1,14 @@
+import type { StorybookConfig } from '@storybook/web-components-vite';
+
+const config: StorybookConfig = {
+  stories: ['../docs/stories/**/*.mdx', '../docs/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: [
+    '@chromatic-com/storybook',
+    '@storybook/addon-vitest',
+    '@storybook/addon-a11y',
+    '@storybook/addon-docs',
+    'storybook-addon-fetch-mock',
+  ],
+  framework: '@storybook/web-components-vite',
+};
+export default config;

.storybook/preview.ts

@@ -0,0 +1,19 @@
+import '../docs/styles/theme.css';
+import './reset.css';
+import type { Preview } from '@storybook/web-components-vite';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    a11y: {
+      test: 'error',
+    },
+  },
+};
+
+export default preview;

.storybook/reset.css

@@ -0,0 +1,3 @@
+strong {
+  font-size: 14px;
+}

.storybook/vitest.setup.ts

@@ -0,0 +1,7 @@
+import * as a11yAddonAnnotations from '@storybook/addon-a11y/preview';
+import { setProjectAnnotations } from '@storybook/web-components-vite';
+import * as projectAnnotations from './preview';
+
+// This is an important step to apply the right configuration when testing your stories.
+// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
+setProjectAnnotations([a11yAddonAnnotations, projectAnnotations]);

CONTRIBUTING.md

@@ -28,22 +28,19 @@ $ nvm use
 
 ## Local Development
 
-The local development flow is based around building the docs website, using `wcc` in an SSG based workflow, and running tests.
+Below are the local development workflows for working on WCC itself:
 
-### Commands
-
-These are the main tasks, and you can see them all listed in _package.json#scripts_.
-
-- `npm run dev` - Builds the docs site for local development
 - `npm test` - Run all the tests
 - `npm test:tdd` - Run all the tests in watch mode
 - `npm run lint` - Run all linters
 - `npm run check:types` - Run `tsc` to validate TypeScript types
 - `npm run format` - Auto-format all file
 
+> You can see them all scripts in _package.json#scripts_.
+
 ## Website
 
-The website is built with [**Greenwood**](https://www.greenwoodjs.dev). To run the website locally, use one of the following commands:
+The documentation website for WCC is built with [**Greenwood**](https://www.greenwoodjs.dev). To run the website locally, use one of the following commands:
 
 - `npm run dev` - Start the dev server
 - `npm run build` - Generate a production build
@@ -54,6 +51,10 @@ To run tests for the website, first make sure you have at least run `npm run bui
 - `npm run test:docs` - Run a single suite of tests with Vitest
 - `npm run test:docs:tdd` - Run the test suite with Vitest in watch mode
 
+To run Storybook for the components used in the website, run:
+
+- `npm run story:dev`
+
 ### Sandbox
 
 To assist in local development of WCC, there is a "sandbox" app built into the website, that can be used to validate a number of examples in the browser. (think of it as a storybook for WCC).

docs/components/banner-cta/banner-cta.stories.ts

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+import BannerCta from './banner-cta.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Banner CTA',
+} satisfies Meta<typeof BannerCta>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-banner-cta></wcc-banner-cta>`;
+};

docs/components/banner-splash/banner-splash.stories.ts

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+import BannerSplash from './banner-splash.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Banner Splash',
+} satisfies Meta<typeof BannerSplash>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-banner-splash></wcc-banner-splash>`;
+};

docs/components/capability-box/capability-box.stories.ts

@@ -0,0 +1,17 @@
+import { html } from 'lit';
+import CapabilityBox from './capability-box.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Capability Box',
+} satisfies Meta<typeof CapabilityBox>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`
+    <wcc-capability-box heading="This is a title">
+      <p>This is some content</p>
+    </wcc-capability-box>
+  `;
+};

docs/components/ctc-block/ctc-block.stories.ts

@@ -0,0 +1,45 @@
+import { html } from 'lit';
+import CopyToClipboardBlock from './ctc-block.ts';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Copy to Clipboard Block',
+} satisfies Meta<typeof CopyToClipboardBlock>;
+
+export default meta;
+
+export const SnippetTemplate = () => `
+  <wcc-ctc-block variant="snippet" heading="src/components/greeting.js">
+    <pre class="language-js"><code class="language-js"><span class="token keyword module">import</span> <span class="token imports"><span class="token punctuation">{</span> html<span class="token punctuation">,</span> css<span class="token punctuation">,</span> <span class="token maybe-class-name">LitElement</span> <span class="token punctuation">}</span></span> <span class="token keyword module">from</span> <span class="token string">"lit"</span><span class="token punctuation">;</span>
+
+<span class="token keyword module">export</span> <span class="token keyword">class</span> <span class="token class-name">SimpleGreeting</span> <span class="token keyword">extends</span> <span class="token class-name">LitElement</span> <span class="token punctuation">{</span>
+  <span class="token keyword">static</span> styles <span class="token operator">=</span> css<span class="token template-string"><span class="token template-punctuation string">\`</span><span class="token css language-css">
+    <span class="token selector">p</span> <span class="token punctuation">{</span>
+      <span class="token property">color</span><span class="token punctuation">:</span> <span class="token color">blue</span><span class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+  </span><span class="token template-punctuation string">\`</span></span><span class="token punctuation">;</span>
+
+  <span class="token keyword">static</span> properties <span class="token operator">=</span> <span class="token punctuation">{</span>
+    <span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token punctuation">{</span> <span class="token literal-property property">type</span><span class="token operator">:</span> <span class="token known-class-name class-name">String</span> <span class="token punctuation">}</span><span class="token punctuation">,</span>
+  <span class="token punctuation">}</span><span class="token punctuation">;</span>
+
+  <span class="token function">constructor</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
+    <span class="token keyword">super</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
+    <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token property-access">name</span> <span class="token operator">=</span> <span class="token string">"Somebody"</span><span class="token punctuation">;</span>
+  <span class="token punctuation">}</span>
+
+  <span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
+    <span class="token keyword control-flow">return</span> html<span class="token template-string"><span class="token template-punctuation string">\`</span><span class="token html language-html"><span class="token tag"><span class="token tag"><span class="token punctuation">&#x3C;</span>p</span><span class="token punctuation">></span></span>Hello, <span class="token interpolation"><span class="token interpolation-punctuation punctuation">\${</span><span class="token keyword">this</span><span class="token punctuation">.</span><span class="token property-access">name</span><span class="token interpolation-punctuation punctuation">}</span></span>!<span class="token tag"><span class="token tag"><span class="token punctuation">&#x3C;/</span>p</span><span class="token punctuation">></span></span></span><span class="token template-punctuation string">\`</span></span><span class="token punctuation">;</span>
+  <span class="token punctuation">}</span>
+<span class="token punctuation">}</span></code></pre>
+  </wcc-ctc-block>
+`;
+
+export const ShellScriptTemplate = () => `
+  <wcc-ctc-block variant="shell" paste-contents="npm i -D wc-compiler">
+    <pre class="language-shell"><code class="language-shell">
+    <span class="token comment"># install WCC with this command</span>
+    $ npm i -D wc-compiler
+    </code></pre>
+  </wcc-ctc-block>
+`;

docs/components/ctc-button/ctc-button.stories.ts

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+import CopyToClipboardButton from './ctc-button.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Copy to Clipboard Button',
+} satisfies Meta<typeof CopyToClipboardButton>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-ctc-button content="npm i -D wc-compiler"></wcc-ctc-button>`;
+};

docs/components/feature-box/feature-box.stories.ts

@@ -0,0 +1,33 @@
+import { html } from 'lit';
+import FeatureBox from './feature-box.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Feature Box',
+} satisfies Meta<typeof FeatureBox>;
+
+export default meta;
+
+export const JSX = () => {
+  return html`
+    <wcc-feature-box heading="JSX">
+      <p>This is some JSX content</p>
+    </wcc-feature-box>
+  `;
+};
+
+export const TypeScript = () => {
+  return html`
+    <wcc-feature-box heading="TypeScript">
+      <p>This is some TypeScript content</p>
+    </wcc-feature-box>
+  `;
+};
+
+export const Pluggable = () => {
+  return html`
+    <wcc-feature-box heading="Pluggable">
+      <p>This is some content</p>
+    </wcc-feature-box>
+  `;
+};

docs/components/footer/footer.stories.ts

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+import Footer from './footer.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Footer',
+} satisfies Meta<typeof Footer>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-footer></wcc-footer>`;
+};

docs/components/header/header.stories.ts

@@ -0,0 +1,28 @@
+import { html } from 'lit';
+import Header from './header.tsx';
+import pages from '../../../.greenwood/graph.json' with { type: 'json' };
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Header',
+  parameters: {
+    fetchMock: {
+      mocks: [
+        {
+          matcher: {
+            url: 'http://localhost:1984/___graph.json',
+            response: {
+              body: pages.filter((page) => page.data.collection === 'nav'),
+            },
+          },
+        },
+      ],
+    },
+  },
+} satisfies Meta<typeof Header>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-header></wcc-header>`;
+};

docs/components/side-nav/side-nav.stories.ts

@@ -0,0 +1,94 @@
+import { html } from 'lit';
+import SideNav from './side-nav.tsx';
+import pages from '../../../.greenwood/graph.json' with { type: 'json' };
+import type { Meta } from '@storybook/web-components';
+
+const GRAPH = [
+  {
+    id: 'docs',
+    label: 'Docs',
+    title: 'Docs',
+    route: '/docs/',
+    layout: 'docs',
+    data: {
+      collection: 'nav',
+      order: 2,
+      tocHeading: 2,
+      tableOfContents: [
+        {
+          content: 'API',
+          slug: 'api',
+          lvl: 2,
+          i: 1,
+          seen: 0,
+        },
+        {
+          content: 'Metadata',
+          slug: 'metadata',
+          lvl: 2,
+          i: 4,
+          seen: 0,
+        },
+        {
+          content: 'Progressive Hydration',
+          slug: 'progressive-hydration',
+          lvl: 2,
+          i: 5,
+          seen: 0,
+        },
+        {
+          content: 'Data',
+          slug: 'data',
+          lvl: 2,
+          i: 6,
+          seen: 0,
+        },
+        {
+          content: 'Conventions',
+          slug: 'conventions',
+          lvl: 2,
+          i: 9,
+          seen: 0,
+        },
+        {
+          content: 'TypeScript',
+          slug: 'typescript',
+          lvl: 2,
+          i: 10,
+          seen: 0,
+        },
+        {
+          content: 'JSX',
+          slug: 'jsx',
+          lvl: 2,
+          i: 12,
+          seen: 0,
+        },
+      ],
+    },
+  },
+];
+
+const meta = {
+  title: 'Components/Side Nav',
+  parameters: {
+    fetchMock: {
+      mocks: [
+        {
+          matcher: {
+            url: 'http://localhost:1984/___graph.json',
+            response: {
+              body: GRAPH,
+            },
+          },
+        },
+      ],
+    },
+  },
+} satisfies Meta<typeof SideNav>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-side-nav route="/docs/" heading="Docs"></wcc-side-nav>`;
+};

docs/components/social-tray/social-tray.stories.ts

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+import SocialTray from './social-tray.tsx';
+import type { Meta } from '@storybook/web-components';
+
+const meta = {
+  title: 'Components/Social Tray',
+} satisfies Meta<typeof SocialTray>;
+
+export default meta;
+
+export const Primary = () => {
+  return html`<wcc-social-tray></wcc-social-tray>`;
+};