docs: fix charts not rendering because of version mismatch (#1823)

Closes #1822

- fix charts not rendering because of version mismatch
- **Cause:** This was caused by mismatching versions of the `chart.js`
package in our `docs` and the `@sit-onyx/chartjs-plugin` packages.
- **Fix:** We now make use of the [PNPM catalog
feature](https://pnpm.io/catalogs) to enforce usage of the same package
version. Added screenshot tests to ensure that we catch these issues in
the future.

- fix warning logged by vitepress about `gobalThis.document` not being
available
- **Cause:** Vitepress does server-side rendering, where the document is
not available. But we try to set a CSS variable.
- **Fix:** We use the optional chaining operator to ensure that we set
the CSS variable only when `gobalThis.document` is defined.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: JoCa96 <18483883+JoCa96@users.noreply.github.com>

apps/docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

apps/docs/package.json

@@ -9,9 +9,11 @@
  "build-only": "vitepress build src",
  "type-check": "vue-tsc --noEmit",
  "preview": "vitepress preview src",
- "storybook": "storybook dev -p 6006 --no-open"
+ "storybook": "storybook dev -p 6006 --no-open",
+ "test:integration": "playwright install && playwright test"
  },
  "devDependencies": {
+ "@playwright/test": "^1.46.1",
  "@sit-onyx/chartjs-plugin": "workspace:^",
  "@sit-onyx/icons": "workspace:^",
  "@sit-onyx/vitepress-theme": "workspace:^",

apps/docs/playwright.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig, devices } from "@playwright/test";
+
+// NOTE: You need to run "pnpm build" before running the tests
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+ testDir: "./tests",
+ snapshotDir: "./playwright/snapshots",
+ // custom snapshotPathTemplate to remove the testFileName folder that we don't want
+ snapshotPathTemplate: "{snapshotDir}/{testFileDir}/{arg}-{projectName}-{platform}{ext}",
+ // we don't want to update snapshots on the local machine of each developer.
+ // if you want to update snapshots for your branch, use the corresponding GitHub action:
+ // https://github.com/SchwarzIT/onyx/actions/workflows/playwright-screenshots.yml
+ ignoreSnapshots: !process.env.CI,
+ updateSnapshots: "none",
+ fullyParallel: true,
+ forbidOnly: !!process.env.CI, // fail build on CI if we left test.only in the source code
+ retries: process.env.CI ? 1 : 0, // retry on CI only
+ /* In the CI pipeline it generates dot (for the stdout) and blob reports, locally only a html report is generated */
+ reporter: process.env.CI ? [["dot"], ["blob"]] : [["html", { open: "never" }]],
+ use: {
+ baseURL: "http://localhost:3200/",
+ trace: process.env.CI ? "retain-on-failure" : "off",
+ video: process.env.CI ? "retain-on-failure" : "off",
+ },
+ /* Configure projects for major browsers */
+ projects: [
+ { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+ { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+ { name: "webkit", use: { ...devices["Desktop Safari"] } },
+ ],
+ /* Run your local dev server before starting the tests */
+ webServer: {
+ command: "pnpm preview --port 3200 --mode test",
+ port: 3200,
+ reuseExistingServer: false,
+ },
+});

apps/docs/src/.vitepress/config.ts

@@ -1,9 +1,9 @@
 import { fileURLToPath } from "node:url";
-import { defineConfig } from "vitepress";
-import packageJson from "../../../../packages/sit-onyx/package.json";
+import { defineConfig, type DefaultTheme, type UserConfig } from "vitepress";
+import packageJson from "../../../../packages/sit-onyx/package.json" with { type: "json" };
 
 // https://vitepress.dev/reference/site-config
-export default defineConfig({
+export const CONFIG = {
  vite: {
  resolve: {
  alias: {
@@ -214,7 +214,9 @@ export default defineConfig({
  ],
  },
  },
-});
+} as const satisfies UserConfig<DefaultTheme.Config>;
+
+export default defineConfig(CONFIG);
 
 /** Gets the given path while ensuring cross-platform and correct decoding */
 function getFilePath(path: string) {

apps/docs/tests/hide-non-main.css

@@ -0,0 +1,5 @@
+header,
+footer,
+.VPLocalNav {
+ visibility: hidden;
+}

apps/docs/tests/pages.spec.ts

@@ -0,0 +1,53 @@
+import { expect, test } from "@playwright/test";
+import { join } from "node:path";
+import { DefaultTheme } from "../node_modules/vitepress/types/default-theme";
+import { CONFIG } from "../src/.vitepress/config";
+
+test("has title", async ({ page }) => {
+ await page.goto("/");
+
+ await expect(page).toHaveTitle(/onyx/);
+});
+
+const BLACKLIST_PATHS = [/changelog/i, /icons/i];
+
+/**
+ * maps links listed in the vitepress config to their respective absolute url
+ */
+const mapToLinks = (
+ navItem: DefaultTheme.NavItem | DefaultTheme.SidebarItem,
+ baseParm?: string,
+): string[] => {
+ const base = baseParm ?? (navItem as DefaultTheme.SidebarItem).base ?? "";
+ const links: string[] = [];
+ if ("link" in navItem && navItem.link && navItem.link.startsWith("/")) {
+ links.push(`${base}${navItem.link}`);
+ }
+ if ("items" in navItem && navItem.items) {
+ navItem.items.forEach((item) => links.push(...mapToLinks(item, navItem["base"])));
+ }
+ return links;
+};
+
+const navItems = CONFIG.themeConfig.nav;
+const sidebarItems = Object.values(CONFIG.themeConfig.sidebar).flat(1);
+
+const items = [...navItems, ...sidebarItems].map((item) => mapToLinks(item)).flat(1);
+const uniqueItems = new Set(items);
+const pathsTotTest = Array.from(uniqueItems).filter(
+ (p) => !BLACKLIST_PATHS.some((bl) => p.match(bl)),
+);
+
+pathsTotTest.forEach((path) => {
+ test(`screenshot content of ${path}`, async ({ page }) => {
+ const name = path
+ .replace(/^\//, "")
+ .replace(/\.html$/, "")
+ .replace(/[_/ ]/g, "_");
+ await page.goto(path);
+ const main = page.getByRole("main");
+ await expect(main).toHaveScreenshot(`${name}.png`, {
+ stylePath: join(import.meta.dirname, "hide-non-main.css"),
+ });
+ });
+});

packages/chartjs-plugin/package.json

@@ -36,6 +36,7 @@
  "devDependencies": {
  "@vue/compiler-dom": "catalog:",
  "vue": "catalog:",
- "vue-chartjs": "^5.3.1"
+ "vue-chartjs": "^5.3.1",
+ "chart.js": "catalog:"
  }
 }

packages/sit-onyx/src/utils/plugin.ts

@@ -32,5 +32,5 @@ export const createOnyx = (options: OnyxPluginOptions = {}): Plugin => ({
 });
 
 const syncGlobalOptionalText = (text: string) => {
- globalThis.document.body.style.setProperty("--onyx-global-optional-text", text);
+ globalThis.document?.body.style.setProperty("--onyx-global-optional-text", text);
 };

pnpm-workspace.yaml

@@ -3,5 +3,6 @@ packages:
  - "packages/*"
 
 catalog:
- vue: ~3.4.0
  "@vue/compiler-dom": ~3.4.0
+ chart.js: "^4.4.4"
+ vue: ~3.4.0