New documentation website

.cem.yaml

@@ -0,0 +1,9 @@
+sourceControlRootUrl: 'https://github.com/sl-design-system/components/tree/main'
+
+generate:
+  files:
+    - 'packages/components/*/src/**/*.ts'
+  exclude:
+    - 'packages/components/*/src/**/*.spec.ts'
+    - 'packages/components/*/src/**/*.stories.ts'
+  output: 'custom-elements.json'

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "docs/website-v2" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "docs/website-v2" ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

.github/workflows/website.yml

@@ -4,13 +4,15 @@ on:
   pull_request:
     branches:
       - main
+      - docs/website-v2
     paths-ignore:
       - 'packages/tokens/src/**'
     types: [opened, synchronize, reopened, closed]
 
   push:
     branches:
       - main
+      - docs/website-v2
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -47,7 +49,7 @@ jobs:
       - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: 'website/dist'
+          path: 'docs/website/dist'
       - id: deployment
         uses: actions/deploy-pages@v4
 
@@ -67,7 +69,7 @@ jobs:
         with:
           azure_static_web_apps_api_token: ${{ secrets.WEBSITE_AZURE_STATIC_WEB_APPS_API_TOKEN }}
           action: upload
-          app_location: website/dist
+          app_location: docs/website/dist
           production_branch: main
           skip_api_build: true
           skip_app_build: true

.gitignore

@@ -108,3 +108,5 @@ __snapshots__
 
 # Intellij
 .idea/
+
+*storybook.log

docs/components/.storybook/main.ts

@@ -0,0 +1,39 @@
+import { importCSSSheet } from '@roenlie/vite-plugin-import-css-sheet'
+import { type StorybookConfig } from '@storybook/web-components-vite';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * This function is used to resolve the absolute path of a package.
+ * It is needed in projects that use Yarn PnP or are set up within a monorepo.
+ */
+function getAbsolutePath(value: string) {
+  return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)))
+}
+
+const config: StorybookConfig = {
+  stories: [
+    '../src/**/*.stories.ts'
+  ],
+  addons: [
+    getAbsolutePath('@storybook/addon-vitest'),
+    getAbsolutePath('@storybook/addon-a11y'),
+    getAbsolutePath('@storybook/addon-docs')
+  ],
+  core: {
+    disableTelemetry: true
+  },
+  framework: getAbsolutePath('@storybook/web-components-vite'),
+  staticDirs: [
+    { from: '../../../packages/themes', to: '/themes' },
+  ],
+  async viteFinal(config) {
+    const { mergeConfig } = await import('vite');
+
+    return mergeConfig(config, {
+      plugins: [importCSSSheet()]
+    });
+  }
+};
+
+export default config;

docs/components/.storybook/preview-head.html

@@ -0,0 +1,10 @@
+<link rel="stylesheet" href="https://use.typekit.net/kes1hoh.css" />
+<link rel="stylesheet" href="/themes/sanoma-learning/global.css" />
+<link rel="stylesheet" href="/themes/sanoma-learning/light.css" />
+<style>
+  body {
+    background: var(--sl-elevation-surface-base-default);
+    color: var(--sl-color-foreground-plain);
+    font: var(--sl-text-new-body-md);
+  }
+</style>

docs/components/.storybook/preview.ts

@@ -0,0 +1,25 @@
+import '@webcomponents/scoped-custom-element-registry/scoped-custom-element-registry.min.js';
+import { setup } from '@sl-design-system/sanoma-learning';
+import { type Preview } from '@storybook/web-components-vite';
+
+setup();
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i
+      }
+    },
+
+    a11y: {
+      // 'todo' - show a11y violations in the test UI only
+      // 'error' - fail CI on a11y violations
+      // 'off' - skip a11y checks entirely
+      test: 'todo'
+    }
+  }
+};
+
+export default preview;

docs/components/.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]);

docs/components/env.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+  const css: CSSStyleSheet;
+  export default css;
+}

docs/components/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@sl-design-system/doc-components",
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "description": "Web components used in the documentation of the SL Design System",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sl-design-system/components.git"
+  },
+  "exports": {
+    "./code-block/code-block.js": "./dist/code-block/code-block.js",
+    "./code-example/code-example.js": "./dist/code-example/code-example.js",
+    "./code/code.js": "./dist/code/code.js",
+    "./copy-button/copy-button.js": "./dist/copy-button/copy-button.js",
+    "./heading/heading.js": "./dist/heading/heading.js",
+    "./install-info/install-info.js": "./dist/install-info/install-info.js",
+    "./open-issue-count/open-issue-count.js": "./dist/open-issue-count/open-issue-count.js",
+    "./page-toc/page-toc.js": "./dist/page-toc/page-toc.js",
+    "./search/search.js": "./dist/search/search.js",
+    "./sidebar/sidebar.js": "./dist/sidebar/sidebar.js",
+    "./site-nav/nav-group.js": "./dist/site-nav/nav-group.js",
+    "./site-nav/nav-item.js": "./dist/site-nav/nav-item.js",
+    "./site-nav/site-nav.js": "./dist/site-nav/site-nav.js",
+    "./theme-switch/theme-switch.js": "./dist/theme-switch/theme-switch.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "wireit",
+    "start": "wireit",
+    "watch": "tsdown --watch"
+  },
+  "wireit": {
+    "build": {
+      "command": "tsdown",
+      "dependencies": [
+        "../..:build"
+      ]
+    },
+    "start": {
+      "command": "storybook dev -p 6009 --no-open",
+      "service": {
+        "readyWhen": {
+          "lineMatches": "Storybook ready!"
+        }
+      },
+      "files": [
+        ".storybook/main.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@open-wc/scoped-elements": "^3.0.6",
+    "@sl-design-system/icon": "workspace:^",
+    "@sl-design-system/search-field": "workspace:^",
+    "@sl-design-system/switch": "workspace:^",
+    "prismjs": "^1.30.0"
+  },
+  "devDependencies": {
+    "@roenlie/vite-plugin-import-css-sheet": "^0.0.7",
+    "@storybook/addon-a11y": "^10.3.5",
+    "@storybook/addon-docs": "^10.3.5",
+    "@storybook/addon-vitest": "^10.3.5",
+    "@storybook/web-components": "^10.3.5",
+    "@storybook/web-components-vite": "^10.3.5",
+    "@tsdown/css": "^0.21.7",
+    "@types/prismjs": "^1.26.6",
+    "@typescript/native-preview": "^7.0.0-dev.20260413.1",
+    "lit": "^3.3.2",
+    "sass-embedded": "^1.99.0",
+    "storybook": "^10.3.5",
+    "tsdown": "^0.21.7",
+    "typescript": "^5.9.3",
+    "wireit": "^0.14.12"
+  },
+  "peerDependencies": {
+    "lit": "^3.3.2"
+  },
+  "inlinedDependencies": {
+    "@floating-ui/core": "1.7.5",
+    "@floating-ui/dom": "1.7.6",
+    "@floating-ui/utils": "0.2.11",
+    "@fortawesome/free-brands-svg-icons": "7.2.0",
+    "@fortawesome/pro-regular-svg-icons": "7.2.0",
+    "@fortawesome/pro-solid-svg-icons": "7.2.0"
+  }
+}

docs/components/src/code-block/code-block.css

@@ -0,0 +1,27 @@
+:host {
+  background: var(--sl-color-background-accent-grey-subtlest);
+  border-radius: var(--sl-size-borderRadius-default);
+  display: block;
+  overflow-x: auto;
+  padding: var(--sl-size-200);
+  position: relative;
+}
+
+:host(:hover) doc-copy-button,
+doc-copy-button:focus-within {
+  opacity: 1;
+}
+
+::slotted(pre) {
+  background: transparent !important;
+  margin: 0 !important;
+  padding: 0 !important;
+}
+
+doc-copy-button {
+  inset-block-start: var(--sl-size-100);
+  inset-inline-end: var(--sl-size-100);
+  opacity: 0;
+  position: absolute;
+  transition: opacity 0.15s;
+}

docs/components/src/code-block/code-block.spec.ts

@@ -0,0 +1,70 @@
+import { fixture } from '@sl-design-system/vitest-browser-lit';
+import { html } from 'lit';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Code } from './code-block.js';
+
+try {
+  customElements.define('doc-code-block', Code);
+} catch {
+  /* empty */
+}
+
+describe('doc-code-block', () => {
+  let el: Code;
+
+  describe('defaults', () => {
+    beforeEach(async () => {
+      el = await fixture(html`
+        <doc-code-block>
+          <pre><code>const foo = 'bar';</code></pre>
+        </doc-code-block>
+      `);
+    });
+
+    it('should render', () => {
+      expect(el).to.exist;
+      expect(el).to.be.instanceOf(Code);
+    });
+
+    it('should render a default slot', () => {
+      const slot = el.renderRoot.querySelector<HTMLSlotElement>('slot:not([name])');
+
+      expect(slot).to.exist;
+      expect(slot?.assignedElements()).to.have.length.greaterThan(0);
+    });
+
+    it('should render a copy button', () => {
+      expect(el.renderRoot.querySelector('doc-copy-button')).to.exist;
+    });
+
+    it('should set the copy button content from the slotted pre element', () => {
+      const copyButton = el.renderRoot.querySelector<HTMLElement & { content?: string }>('doc-copy-button');
+
+      expect(copyButton?.content).to.equal("const foo = 'bar';");
+    });
+
+    it('should copy the source to the clipboard on click', async () => {
+      const writeText = vi.spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined);
+
+      const copyButtonHost = el.renderRoot.querySelector('doc-copy-button')! as Element & { renderRoot: ShadowRoot };
+      copyButtonHost.renderRoot.querySelector<HTMLElement>('sl-button')!.click();
+      await el.updateComplete;
+
+      expect(writeText).toHaveBeenCalledWith("const foo = 'bar';");
+
+      writeText.mockRestore();
+    });
+  });
+
+  describe('without pre element', () => {
+    beforeEach(async () => {
+      el = await fixture(html`<doc-code-block><span>some text</span></doc-code-block>`);
+    });
+
+    it('should render a copy button with no content', () => {
+      const copyButton = el.renderRoot.querySelector<HTMLElement & { content?: string }>('doc-copy-button');
+
+      expect(copyButton?.content).to.equal('');
+    });
+  });
+});

docs/components/src/code-block/code-block.stories.ts

@@ -0,0 +1,48 @@
+import { type Meta, type StoryObj } from '@storybook/web-components-vite';
+import { html } from 'lit';
+import { Code } from './code-block.js';
+
+type Story = StoryObj;
+
+try {
+  customElements.define('doc-code-block', Code);
+} catch {
+  /* empty */
+}
+
+export default {
+  title: 'Code',
+  render: () => html`
+    <doc-code-block>
+      <pre><code class="language-typescript">import { LitElement, html } from 'lit';
+
+export class MyElement extends LitElement {
+  override render() {
+    return html\`&lt;p&gt;Hello world!&lt;/p&gt;\`;
+  }
+}</code></pre>
+    </doc-code-block>
+  `
+} satisfies Meta;
+
+export const Basic: Story = {};
+
+export const MultiLine: Story = {
+  render: () => html`
+    <doc-code-block>
+      <pre><code class="language-html">&lt;sl-button variant="primary"&gt;Click me&lt;/sl-button&gt;
+&lt;sl-button variant="default"&gt;Cancel&lt;/sl-button&gt;</code></pre>
+    </doc-code-block>
+  `
+};
+
+export const CSS: Story = {
+  render: () => html`
+    <doc-code-block>
+      <pre><code class="language-css">:host {
+  display: block;
+  color: red;
+}</code></pre>
+    </doc-code-block>
+  `
+};