@uxfront/layer-docs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @uxfront/layer-docs
+
+## 0.1.2
+
+### Patch Changes
+
+- Fix `nuxt typecheck` failure in `AppHeaderCTA.vue`: the config module seeds a
+  partial `header` (`{ title }`), so defu narrows the resolved `AppConfig` header
+  to `{ title, logo }` and drops the array-valued `links`. Read `links` through a
+  cast on `header` itself instead of the `.links` result, so consumers extending
+  the layer typecheck cleanly. Runtime behaviour is unchanged.
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial scaffold of the neutral Nuxt-layer docs theme: auto-config module
+  (site metadata / SEO / git inference), neutral `app.config` defaults and UI
+  polish, base `main.css` (Tailwind + Nuxt UI wiring, palette-free),
+  `MorphingGradientBackground`, and opt-out-gated i18n-redirect and PostHog
+  plugins. Nuxt documentation stack declared as pinned `peerDependencies`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 uxfront
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @uxfront/layer-docs
+
+A neutral, brandable **Nuxt layer** documentation theme. Extend it, supply your
+own branding and content, and get a Docus-shaped docs site — header, footer,
+sidebar, SEO, i18n routing, OG images and analytics — without copying boilerplate
+between repos.
+
+The layer ships **no product branding**. Consuming apps provide title, logos,
+socials, GitHub, footer, table-of-contents links and colour palette via their own
+`app.config.ts`, merged over the layer's neutral defaults by Nuxt's `defu` layer
+merge. Site metadata, SEO and git info are auto-inferred from the consumer's
+`package.json` + git when not supplied.
+
+## Install
+
+```bash
+npm install -D @uxfront/layer-docs
+```
+
+Then install the peer dependencies the layer expects (the Nuxt documentation
+stack — see [`package.json`](./package.json) `peerDependencies` for pinned
+ranges): `nuxt`, `vue`, `@nuxt/ui`, `@nuxt/image`, `@nuxt/scripts`,
+`@nuxtjs/robots`, `nuxt-og-image`, `nuxt-llms`, `tailwindcss`, and — for content
+and translation — `@nuxt/content`, `@nuxtjs/i18n`, `@nuxtjs/mdc`.
+
+## Usage
+
+Extend the layer from your app's `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  extends: ["@uxfront/layer-docs"],
+});
+```
+
+Supply your branding from your app's `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+  header: { title: "My Docs" },
+  // logos, socials, footer, toc links, ui.colors …
+});
+```
+
+## Compatibility
+
+Pinned to the Nuxt 4 documentation stack (Nuxt 4.4, Nuxt UI 4.8, Content 3.14,
+i18n 10.4, og-image 6, llms 0.2). TypeScript is pinned to the range the Nuxt
+stack supports (`^6.0.3`). See `peerDependencies` for the authoritative ranges.
+
+## License
+
+[MIT](./LICENSE)

package/app/app.config.ts

@@ -0,0 +1,82 @@
+export default defineAppConfig({
+  /**
+   * Neutral shell defaults. This layer ships NO product branding — consuming
+   * apps supply title, logos, socials, GitHub, footer, TOC links and palette
+   * via their own `app.config.ts` (merged over these defaults by Nuxt's `defu`
+   * layer merge). `modules/config.ts` also fills `seo`/`header`/`github` from
+   * the consumer's `package.json` + git as fallbacks.
+   *
+   * @docs https://www.docus.dev/concepts/configuration#global-configuration
+   */
+  toc: {
+    // Title of the main table of contents
+    title: "On this page",
+  },
+
+  /**
+   * Opt-out flags for the layer's client plugins. Defaults keep them on so an
+   * existing consumer is unchanged; a consumer opts out by setting `false`.
+   */
+  analytics: {
+    // PostHog analytics plugin (production only, requires a runtime key).
+    enabled: true,
+  },
+  i18nRedirect: {
+    // Redirect `/` to `/{locale}` (only fires when i18n is configured).
+    enabled: true,
+  },
+
+  ui: {
+    // Palette-free type discriminant — NOT branding. Nuxt UI's wide
+    // `AppConfigUI` type (which permits the component slot overrides below)
+    // only applies to `ui` when a `colors` key is present; without it the
+    // narrow `nuxt.schema.ts` Studio type wins and the slots fail
+    // excess-property checks. The empty object bakes in no palette; each
+    // consumer supplies the real `colors` (merged over this by `defu`).
+    colors: {},
+    // Neutral Nuxt UI Pro component polish — reusable shell defaults every
+    // consumer inherits, not product branding.
+    commandPalette: {
+      slots: {
+        input: "[&_.iconify]:size-4 [&_.iconify]:mx-0.5",
+        itemLeadingIcon: "size-4 mx-0.5",
+      },
+    },
+    contentNavigation: {
+      slots: {
+        trigger: "font-normal text-muted data-[state=open]:text-muted cursor-pointer",
+        linkLeadingIcon: "size-4 mr-1",
+        linkTrailing: "hidden",
+      },
+      compoundVariants: [
+        {
+          variant: "link",
+          active: false,
+          disabled: false,
+          class: {
+            linkLeadingIcon: "group-data-[state=open]:text-dimmed",
+          },
+        },
+      ],
+      defaultVariants: {
+        variant: "link",
+      },
+    },
+    pageLinks: {
+      slots: {
+        linkLeadingIcon: "size-4",
+        linkLabelExternalIcon: "size-2.5",
+      },
+    },
+    pageCard: {
+      slots: {
+        root: "rounded-xl",
+      },
+    },
+    pricingTable: {
+      slots: {
+        tierTitle: "text-highlighted text-2xl sm:text-3xl text-pretty font-semibold",
+      },
+    },
+  },
+});

package/app/app.vue

@@ -0,0 +1,138 @@
+<script setup lang="ts">
+import type { ContentNavigationItem, PageCollections } from "@nuxt/content";
+import * as nuxtUiLocales from "@nuxt/ui/locale";
+
+const appConfig = useAppConfig();
+const { seo } = appConfig;
+const site = useSiteConfig();
+const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n();
+
+const lang = computed(
+  () => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.code || "en",
+);
+const dir = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.dir || "ltr");
+
+const getCollectionName = (key: string) =>
+  (isEnabled.value ? `docs_${key}_${locale.value}` : `docs_${key}`) as keyof PageCollections;
+
+useHead({
+  meta: [{ name: "viewport", content: "width=device-width, initial-scale=1" }],
+  link: [{ rel: "icon", href: "/favicon.ico" }],
+  htmlAttrs: {
+    lang,
+    dir,
+  },
+});
+
+useSeoMeta({
+  titleTemplate: seo?.titleTemplate,
+  title: seo?.title,
+  description: seo?.description,
+  ogSiteName: site.name,
+  twitterCard: "summary_large_image",
+});
+
+if (isEnabled.value) {
+  const route = useRoute();
+  const defaultLocale = (useRuntimeConfig().public.i18n as { defaultLocale: string }).defaultLocale;
+  onMounted(() => {
+    const currentLocale = route.path.split("/")[1];
+    if (!locales.some((locale) => locale.code === currentLocale)) {
+      return navigateTo(switchLocalePath(defaultLocale) as string);
+    }
+  });
+}
+
+const { data: navigation } = await useAsyncData(
+  () => `navigation_${locale.value}`,
+  async () => {
+    const results = await Promise.all(
+      DOCS_SECTIONS.map(async (section) => {
+        const collectionName = getCollectionName(section.key);
+        const data = await queryCollectionNavigation(collectionName);
+        const rootResult =
+          data.find((item) => item.path === `/docs/${section.slug}`)?.children ||
+          data.find((item) => item.path === "/docs")?.children ||
+          data ||
+          [];
+        const localeResult =
+          rootResult.find((item) => item.path === `/${locale.value}`)?.children || rootResult;
+        const sectionPath = `/docs/${section.slug}`;
+        let result: ContentNavigationItem[];
+        if (Array.isArray(section.folder)) {
+          const rootIdx = "rootFolder" in section ? (section.rootFolder as number) : -1;
+          const rootWrapper =
+            localeResult.length === 1 && localeResult[0]?.path === sectionPath
+              ? localeResult[0]
+              : null;
+          const allItems = rootWrapper ? (rootWrapper.children ?? []) : localeResult;
+
+          if (rootIdx >= 0) {
+            const nonRootPaths = new Set(
+              section.folder
+                .filter((_: string, i: number) => i !== rootIdx)
+                .map((f: string) => `${sectionPath}/${f.replace(/^\d+\./, "")}`),
+            );
+            const items: ContentNavigationItem[] = [];
+            for (let i = 0; i < section.folder.length; i++) {
+              if (i === rootIdx) {
+                items.push({
+                  ...rootWrapper,
+                  title: rootWrapper?.title ?? section.label,
+                  path: sectionPath,
+                  children: allItems.filter((item) => !nonRootPaths.has(item.path)),
+                } as ContentNavigationItem);
+              } else {
+                const found = allItems.find(
+                  (item) =>
+                    item.path === `${sectionPath}/${section.folder[i]?.replace(/^\d+\./, "")}`,
+                );
+                if (found) items.push(found);
+              }
+            }
+            result = items;
+          } else {
+            result = section.folder
+              .map((folder: string) =>
+                allItems.find(
+                  (item) => item.path === `${sectionPath}/${folder.replace(/^\d+\./, "")}`,
+                ),
+              )
+              .filter((item): item is ContentNavigationItem => item !== undefined);
+          }
+        } else {
+          result = localeResult;
+        }
+        return [
+          section.key,
+          foldNonRouteCategories(flattenNavigation(result), appConfig.nonRouteCategories ?? {}),
+        ] as const;
+      }),
+    );
+    return Object.fromEntries(results) as Record<string, ContentNavigationItem[]>;
+  },
+  {
+    watch: [locale],
+  },
+);
+
+const flatNavigation = computed(() =>
+  navigation.value ? Object.values(navigation.value).flat() : [],
+);
+
+provide("navigation", navigation);
+</script>
+
+<template>
+  <UApp :locale="nuxtUiLocales[locale as keyof typeof nuxtUiLocales]">
+    <NuxtLoadingIndicator color="var(--ui-primary)" />
+
+    <NuxtLayout>
+      <NuxtPage />
+    </NuxtLayout>
+
+    <ClientOnly>
+      <AppSearch :navigation="flatNavigation" />
+    </ClientOnly>
+  </UApp>
+</template>

package/app/assets/css/main.css

@@ -0,0 +1,15 @@
+@import "tailwindcss";
+@import "@nuxt/ui";
+
+@source "../../../content/**/*";
+@source "../../../layers/**/*";
+@source "../../app.config.ts";
+
+/*
+ * Neutral shell styling only. The brand palette (the `--color-*` scale and the
+ * `--ui-primary` mapping) is consumer-supplied — each consuming app defines its
+ * own `@theme` in its CSS entrypoint, layered over this neutral base.
+ */
+.prose-container {
+  --ui-container: 760px;
+}

package/app/components/IconMenuToggle.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { motion } from "motion-v";
+import type { VariantType } from "motion-v";
+
+const props = defineProps<{
+  open: boolean;
+}>();
+
+const variants: {
+  [k: string]: VariantType | ((custom: unknown) => VariantType);
+} = {
+  normal: {
+    rotate: 0,
+    y: 0,
+    opacity: 1,
+  },
+  close: (custom: unknown) => {
+    const c = custom as number;
+    return {
+      rotate: c === 1 ? 45 : c === 3 ? -45 : 0,
+      y: c === 1 ? 6 : c === 3 ? -6 : 0,
+      opacity: c === 2 ? 0 : 1,
+      transition: {
+        type: "spring",
+        stiffness: 260,
+        damping: 20,
+      },
+    };
+  },
+};
+
+const state = computed(() => (props.open ? "close" : "normal"));
+</script>
+
+<template>
+  <UButton size="sm" variant="ghost" color="neutral" class="-me-1.5" square>
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      class="size-5"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+    >
+      <motion.line
+        x1="4"
+        y1="6"
+        x2="20"
+        y2="6"
+        :variants="variants"
+        :animate="state"
+        :custom="1"
+        class="outline-none"
+      />
+      <motion.line
+        x1="4"
+        y1="12"
+        x2="20"
+        y2="12"
+        :variants="variants"
+        :animate="state"
+        :custom="2"
+        class="outline-none"
+      />
+      <motion.line
+        x1="4"
+        y1="18"
+        x2="20"
+        y2="18"
+        :variants="variants"
+        :animate="state"
+        :custom="3"
+        class="outline-none"
+      />
+    </svg>
+  </UButton>
+</template>

package/app/components/LanguageSelect.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+const { locale, locales, switchLocalePath } = useDocusI18n();
+
+function getEmojiFlag(locale: string): string {
+  const languageToCountry: Record<string, string> = {
+    ar: "sa", // Arabic -> Saudi Arabia
+    bn: "bd", // Bengali -> Bangladesh
+    ca: "es", // Catalan -> Spain
+    ckb: "iq", // Central Kurdish -> Iraq
+    cs: "cz", // Czech -> Czech Republic (note: modern country code is actually 'cz')
+    da: "dk", // Danish -> Denmark
+    el: "gr", // Greek -> Greece
+    en: "gb", // English -> Great Britain
+    et: "ee", // Estonian -> Estonia
+    he: "il", // Hebrew -> Israel
+    hi: "in", // Hindi -> India
+    hy: "am", // Armenian -> Armenia
+    ja: "jp", // Japanese -> Japan
+    kk: "kz", // Kazakh -> Kazakhstan
+    km: "kh", // Khmer -> Cambodia
+    ko: "kr", // Korean -> South Korea
+    ky: "kg", // Kyrgyz -> Kyrgyzstan
+    lb: "lu", // Luxembourgish -> Luxembourg
+    ms: "my", // Malay -> Malaysia
+    nb: "no", // Norwegian Bokmål -> Norway
+    sl: "si", // Slovenian -> Slovenia
+    sv: "se", // Swedish -> Sweden
+    uk: "ua", // Ukrainian -> Ukraine
+    ur: "pk", // Urdu -> Pakistan
+    vi: "vn", // Vietnamese -> Vietnam
+  };
+
+  const baseLanguage = locale.split("-")[0]?.toLowerCase() || locale;
+  const countryCode = languageToCountry[baseLanguage] || locale.replace(/^.*-/, "").slice(0, 2);
+
+  return countryCode
+    .toUpperCase()
+    .split("")
+    .map((char) => String.fromCodePoint(0x1f1a5 + char.charCodeAt(0)))
+    .join("");
+}
+</script>
+
+<template>
+  <UPopover mode="hover" :content="{ align: 'end' }">
+    <UButton color="neutral" variant="ghost" class="size-8">
+      <template #trailing>
+        <span class="text-lg">
+          {{ getEmojiFlag(locale) }}
+        </span>
+      </template>
+    </UButton>
+
+    <template #content>
+      <ul class="flex flex-col">
+        <li v-for="localeItem in locales" :key="localeItem.code">
+          <NuxtLink
+            class="flex justify-between py-1.5 px-2 gap-1 hover:bg-muted"
+            :to="switchLocalePath(localeItem.code) as string"
+            :aria-label="localeItem.name"
+          >
+            <span class="text-sm">
+              {{ localeItem.name }}
+            </span>
+            <span class="size-5 text-center">
+              {{ getEmojiFlag(localeItem.code) }}
+            </span>
+          </NuxtLink>
+        </li>
+      </ul>
+    </template>
+  </UPopover>
+</template>