@uxfront/layer-docs 0.1.0

package/app/components/content/Video.vue

@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { useIntersectionObserver } from "@vueuse/core";
+
+interface Props {
+  poster?: string;
+  src?: string;
+  sources?: string[];
+  controls?: boolean;
+  autoplay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  playsinline?: boolean;
+  pauseOnExit?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  poster: "",
+  src: "",
+  sources: undefined,
+  controls: false,
+  autoplay: false,
+  loop: false,
+  muted: true,
+  playsinline: true,
+  pauseOnExit: true,
+});
+
+const playing = ref(false);
+const loaded = ref(false);
+const isIntersecting = ref(false);
+const posterLoaded = ref(false);
+
+const videoRef = useTemplateRef<HTMLVideoElement | null>("video");
+
+const { stop } = useIntersectionObserver(videoRef, ([entry], observerElement) => {
+  isIntersecting.value = entry?.isIntersecting || false;
+});
+
+const allSources = computed(() => props.sources ?? [props.src]);
+
+const lazyPoster = computed(() => {
+  if (isIntersecting.value && !posterLoaded.value) {
+    posterLoaded.value = true;
+    return props.poster;
+  } else if (posterLoaded.value) {
+    return props.poster;
+  } else {
+    return "";
+  }
+});
+
+onUnmounted(() => {
+  stop();
+});
+
+watch(isIntersecting, (currentValue, previousValue) => {
+  // Pause video if it was playing and is no longer intersecting
+  if (props.pauseOnExit) {
+    if (previousValue && playing.value) {
+      videoRef.value?.pause();
+    } else if (currentValue && !playing.value) {
+      videoRef.value?.play();
+    }
+  }
+
+  // Load if video is intersecting
+  if (currentValue && !loaded.value) {
+    videoRef.value?.load();
+  }
+});
+
+const onPlay = () => {
+  playing.value = true;
+};
+
+const onPause = () => {
+  playing.value = false;
+};
+
+const onLoaded = () => {
+  loaded.value = true;
+};
+</script>
+
+<template>
+  <video
+    ref="video"
+    class="w-full h-full object-cover"
+    preload="none"
+    :poster="lazyPoster"
+    :src="allSources[0]"
+    :controls="controls"
+    :autoplay="autoplay"
+    :loop="loop"
+    :muted="muted"
+    playsinline
+    @play="onPlay"
+    @pause="onPause"
+    @loadeddata="onLoaded"
+  >
+    <source v-for="source in allSources" :src="source" :key="source" />
+  </video>
+</template>

package/app/components/docs/DocsAsideLeftBody.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import type { ContentNavigationItem } from "@nuxt/content";
+
+const route = useRoute();
+const navigationMap = inject<Ref<Record<string, ContentNavigationItem[]> | null>>("navigation");
+
+const navigation = computed<ContentNavigationItem[]>(() => {
+  const section = findDocsSectionBySlug(route.params.section as string);
+  if (!section) return [];
+  return navigationMap?.value?.[section.key] ?? [];
+});
+</script>
+
+<template>
+  <UContentNavigation :key="route.params.section as string" highlight :navigation="navigation">
+    <template #link-title="{ link }">
+      {{ link.title }}
+    </template>
+  </UContentNavigation>
+</template>

package/app/components/docs/DocsAsideRightBottom.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+const appConfig = useAppConfig();
+const { t } = useDocusI18n();
+</script>
+
+<template>
+  <div v-if="appConfig.toc?.bottom?.links?.length" class="hidden lg:block space-y-6">
+    <USeparator type="dashed" />
+
+    <UPageLinks
+      :title="appConfig.toc?.bottom?.title || t('docs.links')"
+      :links="appConfig.toc?.bottom?.links"
+    />
+  </div>
+</template>

package/app/components/docs/DocsPageHeaderLinks.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import { useClipboard } from "@vueuse/core";
+
+const route = useRoute();
+
+const { copy, copied } = useClipboard();
+const { t } = useDocusI18n();
+
+const markdownLink = computed(() => `${window?.location?.origin}/raw${route.path}.md`);
+const items = [
+  {
+    label: t("docs.copy.link"),
+    icon: "i-lucide-link",
+    onSelect() {
+      copy(markdownLink.value);
+    },
+  },
+  {
+    label: t("docs.copy.view"),
+    icon: "i-simple-icons:markdown",
+    target: "_blank",
+    to: markdownLink.value,
+  },
+  {
+    label: t("docs.copy.gpt"),
+    icon: "i-simple-icons:openai",
+    target: "_blank",
+    to: `https://chatgpt.com/?hints=search&q=${encodeURIComponent(`Read ${markdownLink.value} so I can ask questions about it.`)}`,
+  },
+  {
+    label: t("docs.copy.claude"),
+    icon: "i-simple-icons:anthropic",
+    target: "_blank",
+    to: `https://claude.ai/new?q=${encodeURIComponent(`Read ${markdownLink.value} so I can ask questions about it.`)}`,
+  },
+];
+
+async function copyPage() {
+  const page = await $fetch<string>(`/raw${route.path}.md`);
+  copy(page);
+}
+</script>
+
+<template>
+  <UFieldGroup size="sm">
+    <UButton
+      :label="t('docs.copy.page')"
+      :icon="copied ? 'i-lucide-check' : 'i-lucide-copy'"
+      color="neutral"
+      variant="soft"
+      :ui="{
+        leadingIcon: 'text-neutral size-3.5',
+      }"
+      @click="copyPage"
+    />
+
+    <UDropdownMenu
+      size="sm"
+      :items="items"
+      :content="{
+        align: 'end',
+        side: 'bottom',
+        sideOffset: 8,
+      }"
+    >
+      <UButton
+        icon="i-lucide-chevron-down"
+        color="neutral"
+        variant="soft"
+        class="border-l border-muted"
+      />
+    </UDropdownMenu>
+  </UFieldGroup>
+</template>

package/app/composables/useDocsSections.ts

@@ -0,0 +1,50 @@
+import type { ContentNavigationItem } from "@nuxt/content";
+
+export type DocsSectionLink = {
+  label: string;
+  icon: string;
+  slug: string;
+  to: string;
+  active: boolean;
+};
+
+function findFirstLeafPath(items: ContentNavigationItem[] | undefined): string | undefined {
+  if (!items?.length) return undefined;
+  for (const item of items) {
+    if (item.page !== false && item.path) return item.path;
+    if (item.children?.length) {
+      const nested = findFirstLeafPath(item.children);
+      if (nested) return nested;
+    }
+  }
+  return items[0]?.path;
+}
+
+/**
+ * Flattens the consumer's `DOCS_SECTIONS` descriptor into the sub-header link
+ * list, resolving each section's first content leaf as its landing target.
+ * `DOCS_SECTIONS` / `findDocsSectionBySlug` are auto-imported from the
+ * consumer's `app/constants/` directory (declared via `imports.dirs`).
+ */
+export function useDocsSections() {
+  const route = useRoute();
+  const navigation = inject<Ref<Record<string, ContentNavigationItem[]> | null>>("navigation");
+
+  const sections = computed<DocsSectionLink[]>(() =>
+    DOCS_SECTIONS.map((section): DocsSectionLink => {
+      const tree = navigation?.value?.[section.key];
+      const firstPath = findFirstLeafPath(tree);
+      return {
+        label: section.label,
+        icon: section.icon,
+        slug: section.slug,
+        to: firstPath || `/docs/${section.slug}`,
+        active: route.params.section === section.slug,
+      };
+    }),
+  );
+
+  const activeSection = computed(() => sections.value.find((section) => section.active));
+
+  return { sections, activeSection };
+}

package/app/composables/useDocusI18n.ts

@@ -0,0 +1,49 @@
+import type { LocaleObject } from "@nuxtjs/i18n";
+import type { Ref } from "vue";
+import en from "../../i18n/locales/en.json";
+
+/**
+ * `@nuxtjs/i18n` auto-imports. This layer ships with i18n disabled by default —
+ * the module is not registered unless the consumer opts in — so the enabled
+ * branch below is inert until then. These declarations let the file typecheck
+ * without the module generating the globals; when i18n is enabled (the consumer
+ * registers `@nuxtjs/i18n`) the real composables are used.
+ */
+declare function useI18n(): { locale: Ref<string>; t: (key: string) => string };
+declare function useLocalePath(): (route: string, locale?: string) => string;
+declare function useSwitchLocalePath(): (locale: string) => string;
+
+export const useDocusI18n = () => {
+  const config = useRuntimeConfig().public;
+  const isEnabled = ref(!!config.i18n);
+
+  if (!isEnabled.value) {
+    return {
+      isEnabled,
+      locale: ref("en"),
+      locales: [],
+      localePath: (path: string) => path,
+      switchLocalePath: (_locale?: string): string => "",
+      t: (key: string): string => {
+        const path = key.split(".");
+        return path.reduce(
+          (acc: unknown, curr) => (acc as Record<string, unknown>)?.[curr],
+          en,
+        ) as string;
+      },
+    };
+  }
+
+  const { locale, t } = useI18n();
+  const filteredLocales =
+    (config.docus as { filteredLocales: LocaleObject<string>[] })?.filteredLocales || [];
+
+  return {
+    isEnabled,
+    locale,
+    locales: filteredLocales,
+    t,
+    localePath: useLocalePath(),
+    switchLocalePath: useSwitchLocalePath(),
+  };
+};

package/app/composables/useFramework.ts

@@ -0,0 +1,70 @@
+import { useLocalStorage } from "@vueuse/core";
+
+/**
+ * A single selectable framework tab in the docs `FrameworkSwitcher`.
+ * `value` doubles as the slot name and the persisted storage token; `label` is
+ * the visible tab text; `icon` is an Iconify name. `value` is an open string so
+ * a consumer can declare any framework set (e.g. `svelte`, `solid`, `angular`),
+ * not just the layer's neutral default.
+ */
+export interface FrameworkOption {
+  value: string;
+  label: string;
+  icon: string;
+}
+
+/**
+ * Neutral, brand-agnostic default framework set. A consumer overrides the whole
+ * list — in declared order — via its `app.config.ts`:
+ *
+ * ```ts
+ * export default defineAppConfig({
+ *   docsTheme: {
+ *     frameworks: [
+ *       { value: "react", label: "React", icon: "i-mdi-react" },
+ *       { value: "vue", label: "Vue", icon: "i-mdi-vuejs" },
+ *       { value: "svelte", label: "Svelte", icon: "i-mdi-svelte" },
+ *       // ...N frameworks
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * The list is read from app config rather than merged as a layer default on
+ * purpose: Nuxt's `defu` layer merge *concatenates* arrays, so a shipped default
+ * would append to (not replace) the consumer's list. Keeping the default here
+ * and only reading a consumer-supplied override guarantees a clean replacement,
+ * while an app with no `frameworks` configured keeps the original behaviour.
+ */
+export const DEFAULT_FRAMEWORKS: readonly FrameworkOption[] = [
+  { value: "react", label: "React", icon: "i-mdi-react" },
+  {
+    value: "other",
+    label: "Vanilla",
+    icon: "i-mdi-language-typescript",
+  },
+  { value: "vue", label: "Vue", icon: "i-mdi-vuejs" },
+] as const;
+
+// Neutral, layer-owned storage key — not tied to any consuming product.
+const STORAGE_KEY = "docs-theme:framework";
+
+export const useFramework = () => {
+  const appConfig = useAppConfig() as {
+    docsTheme?: { frameworks?: FrameworkOption[] };
+  };
+
+  const frameworks = computed<readonly FrameworkOption[]>(() => {
+    const configured = appConfig.docsTheme?.frameworks;
+    return configured?.length ? configured : DEFAULT_FRAMEWORKS;
+  });
+
+  const framework = useLocalStorage<string>(STORAGE_KEY, frameworks.value[0]!.value, {
+    initOnMounted: true,
+  });
+
+  return {
+    framework,
+    frameworks,
+  };
+};

package/app/constants/sections.ts

@@ -0,0 +1,25 @@
+import type { DocsSectionDescriptor } from "../../utils/content";
+
+/**
+ * Section descriptor as consumed by the theme's runtime nav/search components.
+ * Extends the build-time {@link DocsSectionDescriptor} with the UI-only fields
+ * (`icon`) those components read.
+ */
+export interface DocsSectionItem extends DocsSectionDescriptor {
+  /** Icon name (e.g. `i-lucide-book-open`) shown next to the section link. */
+  icon: string;
+}
+
+/**
+ * Neutral default topology: no sections. The consuming app supplies the real
+ * `DOCS_SECTIONS` by placing its own `app/constants/sections.ts`; Nuxt
+ * auto-import precedence (consumer app dir > layer dir) makes the consumer's
+ * array win at build time. Shipping an empty default here keeps the layer's own
+ * type-check and build green in isolation without leaking any brand topology.
+ */
+export const DOCS_SECTIONS: readonly DocsSectionItem[] = [];
+
+/** Resolve a section by its URL slug, or `undefined` when none matches. */
+export function findDocsSectionBySlug(slug: string): DocsSectionItem | undefined {
+  return DOCS_SECTIONS.find((section) => section.slug === slug);
+}

package/app/error.vue

@@ -0,0 +1,140 @@
+<script setup lang="ts">
+import type { NuxtError } from "#app";
+import type { ContentNavigationItem, PageCollections } from "@nuxt/content";
+import * as nuxtUiLocales from "@nuxt/ui/locale";
+
+const props = defineProps<{
+  error: NuxtError;
+}>();
+
+const { locale, locales, isEnabled, t, switchLocalePath } = useDocusI18n();
+const appConfig = useAppConfig();
+
+const lang = computed(
+  () => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.code || "en",
+);
+const dir = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales]?.dir || "ltr");
+useHead({
+  htmlAttrs: {
+    lang,
+    dir,
+  },
+});
+
+const localizedError = computed(() => {
+  return {
+    ...props.error,
+    statusMessage: t("common.error.title"),
+  };
+});
+
+useSeoMeta({
+  title: () => t("common.error.title"),
+  description: () => t("common.error.description"),
+});
+
+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 getCollectionName = (key: string) =>
+  (isEnabled.value ? `docs_${key}_${locale.value}` : `docs_${key}`) as keyof PageCollections;
+
+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>
+    <AppHeader />
+
+    <UError :error="localizedError" />
+
+    <AppFooter />
+
+    <ClientOnly>
+      <AppSearch :navigation="flatNavigation" />
+    </ClientOnly>
+  </UApp>
+</template>

package/app/layouts/default.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+const route = useRoute();
+const isDocs = computed(() => route.path.startsWith("/docs"));
+</script>
+
+<template>
+  <AppHeader />
+  <UMain>
+    <slot v-if="!isDocs" />
+    <UContainer v-else>
+      <UPage>
+        <template #left>
+          <UPageAside>
+            <DocsAsideLeftBody />
+          </UPageAside>
+        </template>
+
+        <slot />
+      </UPage>
+    </UContainer>
+  </UMain>
+  <AppFooter />
+</template>

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

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import type { Collections } from "@nuxt/content";
+import { kebabCase } from "scule";
+
+definePageMeta({
+  layout: "default",
+});
+
+const route = useRoute();
+const { locale, isEnabled } = useDocusI18n();
+
+// Dynamic collection name based on i18n status
+const collectionName = computed(() => (isEnabled.value ? `landing_${locale.value}` : "landing"));
+
+const { data: page } = await useAsyncData(kebabCase(route.path), () =>
+  queryCollection(collectionName.value as keyof Collections)
+    .path(route.path)
+    .first(),
+);
+if (!page.value) {
+  throw createError({
+    statusCode: 404,
+    statusMessage: "Page not found",
+    fatal: true,
+  });
+}
+
+const title = page.value.seo?.title || page.value.title;
+const description = page.value.seo?.description || page.value.description;
+
+useSeoMeta({
+  title,
+  description,
+  ogTitle: title,
+  ogDescription: description,
+});
+
+if (page.value?.seo?.ogImage) {
+  useSeoMeta({
+    ogImage: page.value.seo.ogImage,
+    twitterImage: page.value.seo.ogImage,
+  });
+}
+</script>
+
+<template>
+  <ContentRenderer v-if="page" :value="page" />
+</template>