@sit-onyx/nuxt-docs 0.6.0 → 0.7.0-dev-20260513141728

package/app/components/TableOfContentsLayout.vue

@@ -0,0 +1,73 @@
+<script lang="ts" setup>
+import type { TocLink } from "@nuxtjs/mdc";
+
+const props = defineProps<{
+  toc: TocLink[];
+  /**
+   * Whether the TOC should be hidden completely.
+   * By default, the content space is still limited even when the TOC is empty
+   * so the layout width is the same when switching between pages with and without a TOC.
+   *
+   * When set to `true`, the content will be full width.
+   */
+  hidden?: boolean;
+}>();
+
+defineSlots<{
+  /**
+   * Page content.
+   */
+  default(): unknown;
+}>();
+</script>
+
+<template>
+  <div v-if="props.hidden" class="layout__content">
+    <slot></slot>
+  </div>
+
+  <div v-else class="layout">
+    <div class="layout__content">
+      <slot></slot>
+    </div>
+
+    <TableOfContents v-if="props.toc.length" class="layout__toc" :links="props.toc" />
+  </div>
+</template>
+
+<style lang="scss" scoped>
+@use "sit-onyx/breakpoints.scss";
+
+.layout {
+  /** Gap between page content and TOC. Equivalent to one grid column + 2 * grid gutter/gap */
+  --onyx-content-toc-gap: calc(2 * var(--onyx-grid-gutter) + (100 / var(--onyx-grid-columns)) * 1%);
+  display: grid;
+  gap: var(--onyx-content-toc-gap);
+
+  // see: https://storybook.onyx.schwarz/?path=/docs/navigation-tableofcontents--docs
+  grid-template-columns: 1fr minmax(8rem, 15rem);
+
+  &__toc {
+    position: sticky;
+    top: var(--onyx-grid-margin-vertical);
+    height: calc(100vh - var(--onyx-nav-bar-height) - 2 * var(--onyx-grid-margin-vertical));
+  }
+
+  // hide TOC on smaller screens
+  @include breakpoints.container(max, md) {
+    display: flex;
+    flex-direction: column;
+
+    .layout__toc {
+      display: none;
+    }
+  }
+
+  &__content {
+    // remove the top margin of the first child since its redundant to the page padding
+    :deep(> div > :first-child) {
+      margin-top: 0;
+    }
+  }
+}
+</style>

package/app/composables/useCollection.ts

@@ -1,24 +1,75 @@
 import type { Collections } from "@nuxt/content";
 
+export type UseCollectionOptions<TCollection extends keyof Collections = keyof Collections> = {
+  /**
+   * Collection name to query.
+   */
+  collection: MaybeRef<TCollection>;
+  /**
+   * Path to query the collection item for.
+   *
+   * @default Current route.
+   */
+  path?: MaybeRef<string>;
+};
+
 /**
- * Composable for loading the collection content for the current route and locale.
+ * Composable for loading the collection data for the current route and locale.
+ * Will throw an 404 error if the collection item could not be found.
+ * Sets SEO data with `useSeoMeta()` automatically.
  */
-export const useCollection = () => {
-  const route = useRoute();
+export const useCollection = async <TCollection extends keyof Collections = keyof Collections>(
+  options: UseCollectionOptions<TCollection>,
+) => {
+  const nuxtApp = useNuxtApp();
   const { locale } = useI18n();
+  const route = useRoute();
 
-  const slug = computed(() => {
-    const path = Array.isArray(route.params.slug)
-      ? route.params.slug.join("/")
-      : (route.params.slug ?? "");
-    return path.startsWith("/") ? path : `/${path}`;
+  const collection = computed(() => toValue(options.collection));
+  const path = computed(() => {
+    let _path = toValue(options.path);
+    if (_path) return _path;
+
+    // get base path of current route (remove a potential locale prefix)
+    _path = route.path;
+    const localePrefix = `/${locale.value}`;
+
+    if (_path.startsWith(localePrefix)) return _path.slice(localePrefix.length);
+    return _path;
   });
 
-  return useAsyncData(
-    () => `page-${slug.value}-${locale.value}`,
-    () => {
-      const collection = `content_${locale.value}` as keyof Collections;
-      return queryCollection(collection).path(slug.value).first();
+  const { data: collectionData } = await useAsyncData(
+    () => `collection-${collection.value}-${path.value}`,
+    () => queryCollection(collection.value).path(path.value).first(),
+  );
+
+  const data = computed<Collections[TCollection] | undefined>(() => {
+    return collectionData.value as Collections[TCollection];
+  });
+
+  watch(
+    data,
+    async (newValue) => {
+      // if data is "null", the page content was not found. "undefined" means it is not loaded yet
+      if (newValue !== null) return;
+      await nuxtApp.runWithContext(() =>
+        showError({
+          message: "Page not found",
+          statusCode: 404,
+          fatal: true,
+        }),
+      );
     },
+    { immediate: true },
   );
+
+  // runWithContext is needed due to async usage above
+  await nuxtApp.runWithContext(() => {
+    useSeoMeta({
+      title: () => data.value?.seo.title,
+      description: () => data.value?.seo.description,
+    });
+  });
+
+  return { data };
 };

package/app/composables/useSidebarNavigation.ts

@@ -34,20 +34,25 @@ export type SidebarNavigationOptions = {
   collapsed?: boolean;
 };
 
-export const useSidebarNavigation = async () => {
+export type UseSidebarNavigationOptions = {
+  /**
+   * Collection name to use for querying the navigation.
+   */
+  collection: Ref<keyof Collections>;
+};
+
+/**
+ * Composable for querying and mapping the navigation items for a given collection.
+ */
+export const useSidebarNavigation = async (options: UseSidebarNavigationOptions) => {
   const { locale } = useI18n();
   const localePath = useLocalePath();
   const route = useRoute();
 
   const { data } = await useAsyncData(
-    () => `navigation-${locale.value}`,
-    () => {
-      const collection = `content_${locale.value}` as const;
-      return queryCollectionNavigation(collection as keyof Collections);
-    },
-    {
-      default: () => [],
-    },
+    () => `navigation-${options.collection.value}-${locale.value}`,
+    () => queryCollectionNavigation(options.collection.value),
+    { default: () => [] },
   );
 
   /**

package/app/layouts/sidebar.vue

@@ -1,6 +1,8 @@
 <script lang="ts" setup>
+import type { Collections } from "@nuxt/content";
 import { iconArrowSmallLeft } from "@sit-onyx/icons";
 import type { OnyxPageLayoutProps, OnyxSidebarProps } from "sit-onyx";
+import TableOfContentsLayout from "../components/TableOfContentsLayout.vue";
 import type { SidebarNavigationItem } from "../composables/useSidebarNavigation.js";
 
 const props = defineProps<
@@ -41,10 +43,13 @@ const slots = defineSlots<{
   sidebarFooter?(): unknown;
 }>();
 
-const { navigation, previousRootItem } = await useSidebarNavigation();
+const { locale } = useI18n();
+const collectionName = computed(() => `content_${locale.value}` as keyof Collections);
 
-const collection = await useCollection();
-const toc = computed(() => collection.data.value?.body.toc?.links ?? []);
+const { navigation, previousRootItem } = await useSidebarNavigation({ collection: collectionName });
+
+const { data: collection } = await useCollection({ collection: collectionName });
+const toc = computed(() => collection.value?.body.toc?.links ?? []);
 </script>
 
 <template>
@@ -85,13 +90,9 @@ const toc = computed(() => collection.data.value?.body.toc?.links ?? []);
 
     <slot name="hero"></slot>
 
-    <div class="main onyx-grid-layout">
-      <div class="content">
-        <slot></slot>
-      </div>
-
-      <TableOfContents v-if="toc.length" class="main__toc" :links="toc" />
-    </div>
+    <TableOfContentsLayout class="onyx-grid-layout" :toc>
+      <slot></slot>
+    </TableOfContentsLayout>
 
     <template v-if="!!slots.footer" #footer>
       <slot name="footer"></slot>
@@ -104,8 +105,6 @@ const toc = computed(() => collection.data.value?.body.toc?.links ?? []);
 </template>
 
 <style lang="scss" scoped>
-@use "sit-onyx/breakpoints.scss";
-
 .sidebar {
   &__empty {
     max-width: 100%;
@@ -116,36 +115,4 @@ const toc = computed(() => collection.data.value?.body.toc?.links ?? []);
     justify-content: flex-start;
   }
 }
-
-.main {
-  /** Gap between page content and TOC. Equivalent to one grid column + 2 * grid gutter/gap */
-  --onyx-content-toc-gap: calc(2 * var(--onyx-grid-gutter) + (100 / var(--onyx-grid-columns)) * 1%);
-  display: grid;
-  gap: var(--onyx-content-toc-gap);
-
-  // see: https://storybook.onyx.schwarz/?path=/docs/navigation-tableofcontents--docs
-  grid-template-columns: 1fr minmax(8rem, 15rem);
-
-  &__toc {
-    position: sticky;
-    top: var(--onyx-grid-margin-vertical);
-    height: calc(100vh - var(--onyx-nav-bar-height) - 2 * var(--onyx-grid-margin-vertical));
-  }
-
-  // hide TOC on smaller screens
-  @include breakpoints.container(max, md) {
-    grid-template-columns: 1fr;
-
-    .main__toc {
-      display: none;
-    }
-  }
-}
-
-.content {
-  // remove the top margin of the first child since its redundant to the page padding
-  :deep(> div > :first-child) {
-    margin-top: 0;
-  }
-}
 </style>

package/app/pages/[...slug].vue

@@ -1,30 +1,16 @@
 <script setup lang="ts">
-definePageMeta({ layout: "sidebar" });
-
-const collection = await useCollection();
+import type { Collections } from "@nuxt/content";
 
-watch(
-  () => collection.data.value,
-  (data) => {
-    // if data is "null", the page content was not found. "undefined" means it is not loaded yet
-    if (data !== null) return;
-    throw showError({
-      message: "Page not found",
-      statusCode: 404,
-    });
-  },
-  { immediate: true },
-);
+definePageMeta({ layout: "sidebar" });
 
-const data = computed(() => collection.data.value);
+const { locale } = useI18n();
 
-useSeoMeta({
-  title: computed(() => collection.data.value?.seo.title),
-  description: computed(() => collection.data.value?.seo.description),
+const { data } = await useCollection({
+  collection: computed(() => `content_${locale.value}` as keyof Collections),
 });
 </script>
 
-<!-- eslint-disable-next-line vue/no-root-v-if  -- the v-if here is theoretically not needed because we throw above it ifs undefined so the user will be redirected to the error page. However, there is still a console warning so we include the v-if here to prevent it. -->
+<!-- eslint-disable-next-line vue/no-root-v-if  -- The "useCollection" will already redirect to the error page when the data is undefined but the data might still be undefined while e.g. switching to another page -->
 <template>
   <ContentRenderer v-if="data" :value="data" />
 </template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sit-onyx/nuxt-docs",
-  "version": "0.6.0",
+  "version": "0.7.0-dev-20260513141728",
   "description": "Nuxt layer/template for creating documentations with the onyx design system",
   "type": "module",
   "author": "Schwarz IT KG",
@@ -33,9 +33,9 @@
     "@nuxtjs/i18n": ">= 10",
     "@nuxtjs/mdc": ">= 0.20.2",
     "sass-embedded": ">= 1",
-    "@sit-onyx/icons": "^1.9.0",
-    "@sit-onyx/nuxt": "^1.0.1",
-    "sit-onyx": "^1.13.0"
+    "@sit-onyx/icons": "^1.9.1",
+    "sit-onyx": "^1.14.0-dev-20260513141728",
+    "@sit-onyx/nuxt": "^1.0.1"
   },
   "devDependencies": {
     "@fontsource-variable/source-code-pro": "^5.2.7",
@@ -49,11 +49,11 @@
     "nuxt": "4.4.4",
     "sass-embedded": "1.99.0",
     "typescript": "5.9.3",
-    "vue": "3.5.33",
-    "@sit-onyx/icons": "^1.9.0",
+    "vue": "3.5.34",
     "@sit-onyx/nuxt": "^1.0.1",
-    "@sit-onyx/shared": "^0.1.0",
-    "sit-onyx": "^1.13.0"
+    "@sit-onyx/icons": "^1.9.1",
+    "sit-onyx": "^1.14.0-dev-20260513141728",
+    "@sit-onyx/shared": "^0.1.0"
   },
   "scripts": {
     "dev": "pnpm dev:prepare && nuxi dev playground",