@eox/pages-theme-eox 0.11.5 → 1.1.0

package/.gitlab-ci.yml

@@ -0,0 +1,30 @@
+image: cypress/base:20.14.0
+
+stages:
+  - test
+
+cache:
+  key:
+    files:
+      - package-lock.json
+  paths:
+    - .npm/
+
+variables:
+  npm_config_cache: "$CI_PROJECT_DIR/.npm"
+
+format:
+  stage: test
+  script:
+    - npm ci
+    - npm run format:check
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event' && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == 'main'
+
+test:
+  stage: test
+  script:
+    - npm ci
+    - npm run test:component
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event' && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == 'main'

package/.release-it.json

@@ -0,0 +1,15 @@
+{
+  "git": {
+    "commitMessage": "chore: release v${version}",
+    "tagName": "v${version}"
+  },
+  "npm": {
+    "publish": false
+  },
+  "plugins": {
+    "@release-it/conventional-changelog": {
+      "preset": "angular",
+      "infile": "CHANGELOG.md"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+# [1.1.0](https://gitlab.eox.at/eox/hub/eoxhub-portal/compare/v1.0.0...v1.1.0) (2026-02-16)
+
+### Bug Fixes
+
+- **style:** css adjustments ([f2dc9a1](https://gitlab.eox.at/eox/hub/eoxhub-portal/commit/f2dc9a1db294b018e49c07acdb0f030bd98e03bf))
+
+### Features
+
+- i18n support ([27af579](https://gitlab.eox.at/eox/hub/eoxhub-portal/commit/27af579611046e81baac7f49e4dd05db8e1cac12))
+- introduce tutorial component ([158c7fd](https://gitlab.eox.at/eox/hub/eoxhub-portal/commit/158c7fdeb137f7b5598e0aa9819cf4793a5c8d81))
+
+# [1.0.0](https://gitlab.eox.at/eox/hub/eoxhub-portal/compare/v0.11.5...v1.0.0) (2026-01-20)
+
+### Features
+
+- add support for TOC, socialLinks, sidebar and outline ([c512361](https://gitlab.eox.at/eox/hub/eoxhub-portal/commit/c51236122a65faf2edb6e8a575d5ef53d86c25af))
+- support for (nested) dropdown nav entries ([71b531e](https://gitlab.eox.at/eox/hub/eoxhub-portal/commit/71b531e1193b18e1fa33397916d0b5a0d35df128))

package/README.md

@@ -16,3 +16,277 @@ export default {
 ```
 
 See also the [Vitepress Docs](https://vitepress.dev/guide/custom-theme#consuming-a-custom-theme).
+
+## Configuration
+
+This theme supports standard [VitePress Default Theme Configuration](https://vitepress.dev/reference/default-theme-config) with some specific adaptations.
+
+### Navigation Bar
+
+The Navigation Bar follows the [Default Theme Nav](https://vitepress.dev/reference/default-theme-nav) structure with the following differences:
+
+| Feature           | Supported | Notes                                                                                       |
+| :---------------- | :-------- | :------------------------------------------------------------------------------------------ |
+| Links             | ✅        | Standard `{ text, link }` structure.                                                        |
+| Dropdowns         | ✅        | Standard `{ text, items: [] }` structure, supports nesting.                                 |
+| Active Match      | ✅        | `activeMatch` regex strings are supported.                                                  |
+| Target/Rel        | ✅        | `target` and `rel` attributes are supported.                                                |
+| Buttons           | ✨        | **Custom**: Add `action: 'primary'` (or 'secondary') to a nav item to style it as a button. |
+| Logo              | ⚠️        | Must be an object with light/dark paths: `{ light: '...', dark: '...' }`.                   |
+| Social Links      | ✅        | Valid `socialLinks` will be displayed in the navbar.                                        |
+| Custom Components | ❌        | Embedding custom components directly in the nav array is not supported.                     |
+
+#### Example Configuration
+
+```javascript
+// .vitepress/config.js
+export default {
+  themeConfig: {
+    logo: {
+      light: "/logo-light.svg",
+      dark: "/logo-dark.svg",
+    },
+    nav: [
+      { text: "Home", link: "/" },
+      {
+        text: "Products",
+        items: [
+          { text: "Product A", link: "/a" },
+          { text: "Product B", link: "/b" },
+        ],
+      },
+      // Custom generic button style
+      { text: "Contact Us", link: "/contact", action: "primary" },
+    ],
+  },
+};
+```
+
+### General Configuration
+
+The following standard VitePress configurations are handled as follows:
+
+- **Site Title**: Explicitly disabled (`siteTitle: false`). The theme relies on the logo for branding.
+- **Logo**: Used for branding. Must be configured as an object `{ light: string, dark: string }`.
+- **Nav**: Fully supported (see above).
+- **Footer**: Supported. The theme uses `theme.footer.copyright` for the copyright text.
+- **Dark Mode**: The theme enforces a specific appearance. `appearance: false` is set in the base config.
+
+### Internationalization (i18n)
+
+This theme leverages VitePress's native [i18n capabilities](https://vitepress.dev/guide/i18n) and extends them with a simplified configuration via `brandConfig`.
+
+#### Multi-language Routing
+
+You can define multiple locales in your `brandConfig`. The theme will automatically generate the corresponding VitePress routes and display a language switcher in the navigation bar.
+
+```javascript
+// brandConfig
+{
+  i18n: {
+    locale: {
+      en: {
+        "Read more about": "Read more about",
+        "Contact us": "Contact us"
+      },
+      de: {
+        "Read more about": "Mehr lesen über",
+        "Contact us": "Kontaktieren Sie uns"
+      }
+    },
+    currentLocale: "en" // This language will be at the root URL (/)
+  }
+}
+```
+
+#### Translation Pattern
+
+The theme uses a "string-as-key" pattern. Most hardcoded UI elements (buttons, footer labels, etc.) use their English text as a lookup key. If a translation is provided in the `brandConfig.i18n.locale` object, it will be used; otherwise, it falls back to the original English text.
+
+Nested keys are also supported via dot-notation if needed (e.g., `legal.privacy`).
+
+#### Language Switcher
+
+- **Desktop**: Appears as a translate icon in the top navigation bar.
+- **Mobile**: Appears as a dedicated section within the mobile menu.
+- The current language is automatically detected based on the URL path (e.g., `/de/` for German).
+
+**Note on Documentation Features**:
+This theme is primarily designed for landing pages and product showcases.
+
+- **Social Links** and **TOC** are supported as described in the VitePress documentation.
+- **Sidebar** and **Outline** are automatically enabled for the `doc` layout, whereas the `page` layout doesn't have them.
+- Other features like **Edit Link**, **Last Updated**, and **Algolia Search** are **not** currently integrated into the custom `Layout.vue` and may not function as expected if configured.
+
+### Cookie Consent
+
+This theme includes built-in cookie consent management integrated with Matomo (Piwik) analytics.
+
+- **Cookie Banner**: Automatically displayed if `brandConfig.analytics` is present.
+- **Cookie Settings**: a `/cookie-settings` page is automatically handled to allow users to review and toggle optional cookies.
+
+#### Analytics Configuration
+
+To enable the cookie banner and analytics tracking, ensure your brand config includes:
+
+```javascript
+// brandConfig
+{
+  analytics: {
+    siteId: "YOUR_MATOMO_SITE_ID";
+    // The tracker URL is hardcoded to "https://nix.eox.at/piwik/" in vitepressConfig.mjs
+  }
+}
+```
+
+## Layout & Components
+
+The theme provides several built-in components and layout features. Some are driven by frontmatter configuration, while others can be used directly in your Markdown files.
+
+### Hero Section
+
+To add a Hero section to the top of a page, use the `hero` frontmatter object.
+
+```yaml
+---
+hero:
+  title: "Welcome to My Site"
+  tagline: "Building the future of things"
+  image:
+    src: "/hero-image.png"
+    alt: "Hero Image"
+  actions:
+    - text: "Get Started"
+      link: "/start"
+      type: "primary"
+    - text: "Learn More"
+      link: "/about"
+      type: "secondary"
+---
+```
+
+### Feature Section
+
+Use the `<FeatureSection>` component to highlight specific features.
+
+```html
+<FeatureSection
+  title="My Feature"
+  tagline="This is an amazing feature"
+  icon="mdi-star"
+  flipped
+>
+  <template #default>
+    <p>Detailed description of the feature.</p>
+  </template>
+  <template #actions>
+    <a href="/docs" class="btn">Documentation</a>
+  </template>
+</FeatureSection>
+```
+
+### Pricing Table
+
+A flexible pricing table component.
+
+```html
+<PricingTable
+  :config="{
+    plans: [
+      {
+        title: 'Basic',
+        price: '€0',
+        features: ['Feature 1', 'Feature 2'],
+        link: { text: 'Sign Up', href: '/signup' }
+      },
+      {
+        title: 'Pro',
+        price: '€99',
+        features: ['Everything in Basic', 'Feature 3'],
+        link: { text: 'Go Pro', href: '/pro' },
+        active: true
+      }
+    ]
+  }"
+/>
+```
+
+### Other Components
+
+#### CTA Section
+
+A Call-to-Action section typically placed at the bottom of a page to encourage user engagement.
+
+```html
+<CTASection
+  title="Ready to get started?"
+  tagline="Join thousands of others today."
+  primary-button="Sign Up Now"
+  primary-link="/register"
+  secondary-button="Contact Sales"
+  secondary-link="/sales"
+  alt-button="Read Documentation"
+  alt-link="/docs"
+  dark
+/>
+```
+
+#### Logo Section
+
+Displays a grid of client or partner logos. It automatically handles logo sizing.
+
+```html
+<LogoSection
+  :logos="[
+    { image: '/logos/client1.png', alt: 'Client 1', link: 'https://client1.com' },
+    { image: '/logos/client2.png', alt: 'Client 2' }
+  ]"
+  base-height="4"
+  strength="1"
+/>
+```
+
+#### Data Table
+
+An interactive table with expandable rows. The `summary` object keys must match the `headers` provided.
+
+```html
+<DataTable
+  :headers="['Name', 'Type', 'Status']"
+  :data="[
+    {
+      summary: { Name: 'Task A', Type: 'Cron', Status: 'Active' },
+      content: 'Detailed description of Task A...'
+    },
+    {
+      summary: { Name: 'Task B', Type: 'Trigger', Status: 'Paused' },
+      content: 'Detailed description of Task B...'
+    }
+  ]"
+/>
+```
+
+#### Features Gallery
+
+A grid layout for feature cards. Automatically used on pages under `features/`, but can be used manually with custom cards.
+
+```html
+<FeaturesGallery
+  section-title="All Features"
+  background="surface-container-low"
+  :cards="[
+    {
+      id: 1,
+      title: 'Global Coverage',
+      content: 'Access data from anywhere.',
+      icon: 'mdi-earth'
+    },
+    {
+      id: 2,
+      title: 'Real-time',
+      content: 'Updates as they happen.',
+      link: { text: 'Learn more', href: '/real-time' }
+    }
+  ]"
+/>
+```

package/cypress/support/commands.js

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add('login', (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })

package/cypress/support/component-index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+    <title>Components App</title>
+  </head>
+  <body>
+    <div data-cy-root></div>
+  </body>
+</html>

package/cypress/support/component.js

@@ -0,0 +1,22 @@
+// Import commands.js using ES2015 syntax:
+import "./commands";
+
+// Alternatively you can use CommonJS syntax:
+// require('./commands')
+
+import { mount } from "cypress/vue";
+
+// Import global styles
+import "../../src/style.css";
+
+// Import EOX UI web components
+import "@eox/ui";
+
+// Ensure global styles are applied
+// This might be needed if vite config doesn't pick up the CSS the same way
+// But importing it here usually works for component testing
+
+Cypress.Commands.add("mount", mount);
+
+// Example use:
+// cy.mount(MyComponent)

package/cypress/support/mocks/features.data.js

@@ -0,0 +1,9 @@
+export const data = [
+  {
+    id: 1,
+    title: "Mock Feature 1",
+    content: "Content 1",
+    html: "<featuresection><h1>Mock Feature 1</h1><p>Content 1</p></featuresection>",
+    link: { text: "Read more", href: "#" },
+  },
+];

package/cypress/support/mocks/helpers.js

@@ -0,0 +1,63 @@
+// Mock generic helpers
+// We delegate to a global object to allow spying in tests
+window.__helpersMock = {
+  trackEvent: (details) => {},
+  acceptCookies: (router) => {},
+  declineCookies: (router) => {},
+  enableTracking: (enable, router) => {},
+  showBanner: (show) => {
+    // Basic DOM simulation for banner visibility
+    if (typeof document !== "undefined") {
+      const banner = document.querySelector(".cookie-banner");
+      if (banner) {
+        banner.style.display = show ? "block" : "none";
+      }
+    }
+  },
+  isActive: (item, path) => {
+    if (item.link === path) return true;
+    if (item.items) {
+      return item.items.some((sub) => window.__helpersMock.isActive(sub, path));
+    }
+    return false;
+  },
+  getFlatList: (items) => {
+    let list = [];
+    items?.forEach((item) => {
+      if (item.link) {
+        list.push(item);
+      }
+      if (item.items) {
+        list = [...list, ...window.__helpersMock.getFlatList(item.items)];
+      }
+    });
+    return list;
+  },
+  t: (key, i18n) => {
+    if (!i18n) return key;
+    const keys = key.split(".");
+    let result = i18n;
+    for (const k of keys) {
+      if (result && Object.prototype.hasOwnProperty.call(result, k)) {
+        result = result[k];
+      } else {
+        result = null;
+        break;
+      }
+    }
+    return result ? result : key;
+  },
+};
+
+export const trackEvent = (...args) => window.__helpersMock.trackEvent(...args);
+export const acceptCookies = (...args) =>
+  window.__helpersMock.acceptCookies(...args);
+export const declineCookies = (...args) =>
+  window.__helpersMock.declineCookies(...args);
+export const enableTracking = (...args) =>
+  window.__helpersMock.enableTracking(...args);
+export const showBanner = (...args) => window.__helpersMock.showBanner(...args);
+export const isActive = (...args) => window.__helpersMock.isActive(...args);
+export const getFlatList = (...args) =>
+  window.__helpersMock.getFlatList(...args);
+export const t = (...args) => window.__helpersMock.t(...args);

package/cypress/support/mocks/vitepress.js

@@ -0,0 +1,83 @@
+import { reactive, ref } from "vue";
+
+const site = ref({
+  title: "Test Site",
+  description: "Test Description",
+});
+
+const page = ref({
+  relativePath: "index.md",
+  title: "Test Page",
+  frontmatter: {},
+});
+
+const theme = ref({
+  logo: { light: "/logo.png", dark: "/logo-dark.png" },
+  nav: [],
+  footer: { copyright: "Test Copyright" },
+  theme: {
+    brandConfig: {},
+  },
+});
+
+const frontmatter = ref({});
+
+export function useData() {
+  return {
+    site,
+    page,
+    theme,
+    frontmatter,
+    lang: ref("en-US"),
+    localeIndex: ref("root"),
+  };
+}
+
+export function withBase(path) {
+  return path;
+}
+
+// Helper to update mock data from tests
+export function __setMockData(newData) {
+  if (newData.site) site.value = { ...site.value, ...newData.site };
+  if (newData.page) page.value = { ...page.value, ...newData.page };
+  if (newData.theme) theme.value = { ...theme.value, ...newData.theme };
+  if (newData.frontmatter)
+    frontmatter.value = { ...frontmatter.value, ...newData.frontmatter };
+}
+
+// Mock route
+const route = reactive({
+  path: "/",
+  data: {
+    title: "Test Page",
+    relativePath: "index.md",
+  },
+});
+
+export function useRoute() {
+  return route;
+}
+
+// Mock useRouter
+export function useRouter() {
+  return {
+    route,
+    go: () => {},
+    // Mock onBeforeRouteChange hook registry
+    onBeforeRouteChange: (fn) => {
+      // We can expose this to tests if needed to trigger it manually
+      window.__mockOnBeforeRouteChange = fn;
+    },
+  };
+}
+
+export function createContentLoader() {
+  return {
+    load: () => Promise.resolve([]),
+  };
+}
+
+export function __setRouteMock(newRoute) {
+  Object.assign(route, newRoute);
+}

package/cypress.config.js

@@ -0,0 +1,46 @@
+import { defineConfig } from "cypress";
+import vue from "@vitejs/plugin-vue";
+import path from "path";
+
+export default defineConfig({
+  component: {
+    devServer: {
+      framework: "vue",
+      bundler: "vite",
+      viteConfig: {
+        resolve: {
+          alias: {
+            // Alias vitepress to our mock
+            vitepress: path.resolve(
+              __dirname,
+              "cypress/support/mocks/vitepress.js",
+            ),
+            // Alias helpers to our mock
+            "../helpers": path.resolve(
+              __dirname,
+              "cypress/support/mocks/helpers.js",
+            ),
+            "../helpers.js": path.resolve(
+              __dirname,
+              "cypress/support/mocks/helpers.js",
+            ),
+            // Alias features.data.js to our mock
+            "../features.data.js": path.resolve(
+              __dirname,
+              "cypress/support/mocks/features.data.js",
+            ),
+          },
+        },
+        plugins: [
+          vue({
+            template: {
+              compilerOptions: {
+                isCustomElement: (tag) => tag.includes("-"),
+              },
+            },
+          }),
+        ],
+      },
+    },
+  },
+});

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@eox/pages-theme-eox",
-  "version": "0.11.5",
+  "version": "1.1.0",
   "type": "module",
   "description": "Vitepress Theme with EOX branding",
   "main": "src/index.js",
   "author": "EOX",
   "license": "MIT",
   "scripts": {
-    "format": "npx prettier --write ."
+    "format": "npx prettier --write .",
+    "format:check": "npx prettier --check .",
+    "test:component": "cypress run --component",
+    "release": "release-it"
   },
   "dependencies": {
     "@eox/eslint-config": "^2.0.0",
     "@eox/ui": "^0.3.7",
     "vitepress": "^1.6.3"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^10.0.4",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "cypress": "^15.9.0",
+    "release-it": "^19.2.3",
+    "vue": "^3.5.26"
   }
 }