@uxfront/layer-docs 0.4.0 → 0.5.0

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

@@ -1,180 +0,0 @@
-<script setup lang="ts">
-import { kebabCase } from "scule";
-import type { ContentNavigationItem, Collections, PageCollectionItemBase } from "@nuxt/content";
-
-type DocsPageItem = PageCollectionItemBase & {
-  links?: Array<{
-    label: string;
-    icon: string;
-    to: string;
-    target?: string;
-  }>;
-  seo?: { title?: string; description?: string };
-};
-import { findPageHeadline } from "@nuxt/content/utils";
-
-definePageMeta({
-  layout: "default",
-});
-
-const route = useRoute();
-const { locale, isEnabled, t } = useDocusI18n();
-const appConfig = useAppConfig();
-const navigationMap = inject<Ref<Record<string, ContentNavigationItem[]>>>("navigation");
-
-const sectionSlug = computed(() => route.params.section as string);
-const section = computed(() => findDocsSectionBySlug(sectionSlug.value));
-
-if (!section.value) {
-  throw createError({
-    statusCode: 404,
-    statusMessage: "Page not found",
-    fatal: true,
-  });
-}
-
-const collectionName = computed(() =>
-  isEnabled.value ? `docs_${section.value!.key}_${locale.value}` : `docs_${section.value!.key}`,
-);
-
-const navigation = computed(() => navigationMap?.value?.[section.value!.key] ?? []);
-
-const [{ data: page }, { data: surround }] = await Promise.all([
-  useAsyncData(
-    kebabCase(route.path),
-    () =>
-      queryCollection(collectionName.value as keyof Collections)
-        .path(route.path)
-        .first() as Promise<DocsPageItem>,
-  ),
-  useAsyncData(`${kebabCase(route.path)}-surround`, () => {
-    return queryCollectionItemSurroundings(collectionName.value as keyof Collections, route.path, {
-      fields: ["description"],
-    });
-  }),
-]);
-
-if (!page.value) {
-  throw createError({
-    statusCode: 404,
-    statusMessage: "Page not found",
-    fatal: true,
-  });
-}
-
-// Add the page path to the prerender list
-addPrerenderPath(`/raw${route.path}.md`);
-
-const title = page.value.seo?.title || page.value.title;
-const description = page.value.seo?.description || page.value.description;
-
-useSeoMeta({
-  title,
-  ogTitle: title,
-  description,
-  ogDescription: description,
-});
-
-const headline = ref(findPageHeadline(navigation.value, page.value?.path));
-watch(
-  () => navigation.value,
-  () => {
-    headline.value = findPageHeadline(navigation.value, page.value?.path) || headline.value;
-  },
-);
-
-defineOgImage("DocsSatori", {
-  headline: headline.value,
-  title,
-  description,
-});
-
-const github = computed(() => (appConfig.github ? appConfig.github : null));
-
-const editLink = computed(() => {
-  if (!github.value) {
-    return;
-  }
-
-  return [
-    github.value.url,
-    "edit",
-    github.value.branch,
-    github.value.rootDir,
-    "content",
-    `${page.value?.stem}.${page.value?.extension}`,
-  ]
-    .filter(Boolean)
-    .join("/");
-});
-</script>
-
-<template>
-  <UPage v-if="page">
-    <UPageHeader
-      :title="page.title"
-      :description="page.description"
-      :headline="headline"
-      :ui="{
-        wrapper: 'flex-row items-center flex-wrap justify-between',
-      }"
-    >
-      <template #links>
-        <UButton
-          v-for="(link, index) in (page as DocsPageItem).links"
-          :key="index"
-          size="sm"
-          v-bind="link"
-        />
-
-        <DocsPageHeaderLinks />
-      </template>
-    </UPageHeader>
-
-    <UPageBody>
-      <ContentRenderer v-if="page" :value="page" />
-
-      <!-- `decorative` drops the `separator` role: the rule is decoration around
-           the edit/report actions, and a separator with focusable descendants is
-           a `nested-interactive` violation. -->
-      <USeparator decorative>
-        <div v-if="github" class="flex items-center gap-2 text-sm text-muted">
-          <UButton
-            variant="link"
-            color="neutral"
-            :to="editLink"
-            target="_blank"
-            icon="i-lucide-pen"
-            :ui="{ leadingIcon: 'size-4' }"
-          >
-            {{ t("docs.edit") }}
-          </UButton>
-          <span>{{ t("common.or") }}</span>
-          <UButton
-            variant="link"
-            color="neutral"
-            :to="`${github.url}/issues/new/choose`"
-            target="_blank"
-            icon="i-lucide-alert-circle"
-            :ui="{ leadingIcon: 'size-4' }"
-          >
-            {{ t("docs.report") }}
-          </UButton>
-        </div>
-      </USeparator>
-      <UContentSurround :surround="surround" />
-    </UPageBody>
-
-    <template v-if="page?.body?.toc?.links?.length" #right>
-      <UContentToc
-        highlight
-        :title="appConfig.toc?.title || t('docs.toc')"
-        :links="page.body?.toc?.links"
-      >
-        <template #bottom>
-          <DocsAsideRightBottom />
-        </template>
-      </UContentToc>
-    </template>
-  </UPage>
-</template>

package/app/plugins/i18n.ts

@@ -1,21 +0,0 @@
-export default defineNuxtPlugin(() => {
-  // Consumers opt out via `app.config` (`i18nRedirect.enabled: false`).
-  if (!useAppConfig().i18nRedirect?.enabled) {
-    return;
-  }
-
-  const nuxtApp = useNuxtApp();
-
-  const i18nConfig = nuxtApp.$config.public.i18n as { defaultLocale?: string } | undefined;
-  if (!i18nConfig) {
-    return;
-  }
-
-  addRouteMiddleware((to) => {
-    if (to.path === "/") {
-      const cookieLocale = useCookie("i18n_redirected").value || i18nConfig.defaultLocale || "en";
-
-      return navigateTo(`/${cookieLocale}`);
-    }
-  });
-});

package/app/plugins/posthog.client.ts

@@ -1,56 +0,0 @@
-import type { ConfigDefaults } from "posthog-js";
-import { defineNuxtPlugin } from "#app";
-
-export default defineNuxtPlugin(async () => {
-  if (import.meta.dev) {
-    return {};
-  }
-
-  // Consumers opt out via `app.config` (`analytics.enabled: false`).
-  if (!useAppConfig().analytics?.enabled) {
-    return {};
-  }
-
-  const runtimeConfig = useRuntimeConfig();
-
-  // No key provisioned (`NUXT_PUBLIC_POSTHOG_KEY` unset) — no-op instead of
-  // initialising a client that would fire requests at nothing.
-  if (!runtimeConfig.public.posthog.key) {
-    return {};
-  }
-
-  // `posthog-js` is an OPTIONAL peer dependency. A static top-level import
-  // compiles to a module-scope `throw` for every consumer that omits it, and
-  // that throw runs before any of the guards above — killing the entire client
-  // bundle, not just analytics, so the site serves as a dead static document.
-  // Importing here keeps the unresolvable specifier behind the opt-in, and the
-  // catch keeps a missing or broken module a no-analytics degradation rather
-  // than a dead app.
-  let posthog;
-  try {
-    ({ default: posthog } = await import("posthog-js"));
-  } catch (error) {
-    console.warn(
-      "[layer-docs] analytics is enabled and a PostHog key is set, but " +
-        "`posthog-js` could not be loaded — continuing without analytics. " +
-        "Install `posthog-js` to enable it.",
-      error,
-    );
-    return {};
-  }
-
-  const posthogClient = posthog.init(runtimeConfig.public.posthog.key, {
-    api_host: runtimeConfig.public.posthog.host,
-    defaults: runtimeConfig.public.posthog.defaults as ConfigDefaults,
-    person_profiles: "identified_only", // or 'always' to create profiles for anonymous users as well
-    loaded: (posthog) => {
-      if (import.meta.env.MODE === "development") posthog.debug();
-    },
-  });
-
-  return {
-    provide: {
-      posthog: () => posthogClient,
-    },
-  };
-});

package/app/types/non-route-categories.ts

@@ -1,12 +0,0 @@
-export interface NonRouteCategoryMeta {
-  title: string;
-  icon?: string | false;
-  defaultOpen?: boolean;
-  order: number;
-}
-
-declare module "nuxt/schema" {
-  interface AppConfig {
-    nonRouteCategories?: Record<string, NonRouteCategoryMeta>;
-  }
-}

package/app/utils/flattenNavigation.ts

@@ -1,22 +0,0 @@
-import type { ContentNavigationItem } from "@nuxt/content";
-
-/**
- * Flatten navigation items that are false-positive groups.
- * Nuxt Content's index detection regex matches filenames containing "index"
- * as a substring (e.g. "z-index"), incorrectly nesting them as groups.
- * This flattens groups with a single child sharing the same path.
- */
-export function flattenNavigation(items: ContentNavigationItem[]): ContentNavigationItem[] {
-  return items.map((item) => {
-    if (item.children?.length === 1 && item.children[0]?.path === item.path) {
-      const { children: _, ...parent } = item;
-      return { ...parent, ...item.children[0], children: undefined };
-    }
-
-    if (item.children?.length) {
-      return { ...item, children: flattenNavigation(item.children) };
-    }
-
-    return item;
-  });
-}

package/app/utils/foldNonRouteCategories.ts

@@ -1,47 +0,0 @@
-import type { ContentNavigationItem } from "@nuxt/content";
-import type { NonRouteCategoryMeta } from "~/types/non-route-categories";
-
-/**
- * Rebuilds the sidebar grouping for non-route categories.
- *
- * Pages under a `route: false` folder are flattened in the URL, so the native
- * navigation tree lists them as direct children with the category level gone.
- * This re-nests each such page under a synthetic group node (rendered as a
- * non-navigating accordion header), matching pages to categories by `stem`.
- */
-export function foldNonRouteCategories(
-  items: ContentNavigationItem[],
-  categories: Record<string, NonRouteCategoryMeta>,
-): ContentNavigationItem[] {
-  return items.map((node) => {
-    if (!node.children?.length) {
-      return node;
-    }
-    const passthrough: ContentNavigationItem[] = [];
-    const groups = new Map<
-      string,
-      { meta: NonRouteCategoryMeta; children: ContentNavigationItem[] }
-    >();
-    for (const child of node.children) {
-      const dir = child.stem ? child.stem.split("/").slice(0, -1).join("/") : "";
-      const meta = categories[dir];
-      if (meta && child.page !== false) {
-        const group = groups.get(dir) ?? { meta, children: [] };
-        group.children.push(child);
-        groups.set(dir, group);
-      } else {
-        passthrough.push(foldNonRouteCategories([child], categories)[0]!);
-      }
-    }
-    const groupNodes = [...groups.values()]
-      .sort((a, b) => a.meta.order - b.meta.order || a.meta.title.localeCompare(b.meta.title))
-      .map(({ meta, children }) => ({
-        title: meta.title,
-        ...(meta.icon ? { icon: meta.icon } : {}),
-        ...(meta.defaultOpen !== undefined ? { defaultOpen: meta.defaultOpen } : {}),
-        page: false as const,
-        children,
-      })) as ContentNavigationItem[];
-    return { ...node, children: [...passthrough, ...groupNodes] };
-  });
-}

package/app/utils/prerender.ts

@@ -1,9 +0,0 @@
-export const addPrerenderPath = (path: string) => {
-  const event = useRequestEvent();
-  if (event) {
-    event.node.res.setHeader(
-      "x-nitro-prerender",
-      [event.node.res.getHeader("x-nitro-prerender"), path].filter(Boolean).join(","),
-    );
-  }
-};

package/app/utils/storybookEmbed.test.ts

@@ -1,98 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  buildStorybookEmbedUrl,
-  resolveStorybookBaseUrl,
-  STORYBOOK_EMBED_DEFAULT_HEIGHTS,
-  storybookEmbedCssHeight,
-} from "./storybookEmbed";
-
-const TEMPLATE = "https://{framework}.storybook.example.com";
-const STORY = "components-actions-button--default";
-
-describe("resolveStorybookBaseUrl", () => {
-  it("substitutes every occurrence of the framework placeholder", () => {
-    expect(resolveStorybookBaseUrl("https://{framework}.example.com/{framework}", "vue")).toBe(
-      "https://vue.example.com/vue",
-    );
-  });
-
-  it("passes a template without a placeholder through, for a single Storybook", () => {
-    expect(resolveStorybookBaseUrl("https://storybook.example.com", "vue")).toBe(
-      "https://storybook.example.com",
-    );
-  });
-
-  it("trims trailing slashes so the built URL never doubles them", () => {
-    expect(resolveStorybookBaseUrl("https://storybook.example.com//")).toBe(
-      "https://storybook.example.com",
-    );
-  });
-});
-
-describe("buildStorybookEmbedUrl", () => {
-  it("addresses the preview surface by default and marks itself as a direct embed", () => {
-    expect(buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue" })).toBe(
-      `https://vue.storybook.example.com/iframe.html?id=${STORY}&viewMode=story&docsEmbed=1`,
-    );
-  });
-
-  // `full` and `panel` reproduce the manager URLs the migrating docs site
-  // already ships; a changed parameter here is a changed rendering there.
-  it("addresses the manager in full mode", () => {
-    expect(
-      buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue", mode: "full" }),
-    ).toBe(
-      `https://vue.storybook.example.com/?path=/story/${STORY}&full=1&shortcuts=false&singleStory=true`,
-    );
-  });
-
-  it("addresses the manager with its addon panel in panel mode", () => {
-    expect(
-      buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue", mode: "panel" }),
-    ).toBe(
-      `https://vue.storybook.example.com/?path=/story/${STORY}&shortcuts=false&singleStory=true`,
-    );
-  });
-
-  it("only marks the preview surface — a manager embed is relayed, not direct", () => {
-    for (const mode of ["full", "panel"] as const) {
-      expect(buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, mode })).not.toContain(
-        "docsEmbed",
-      );
-    }
-  });
-
-  it("encodes the story id rather than splicing it into the query raw", () => {
-    expect(
-      buildStorybookEmbedUrl({ template: "https://sb.example.com", story: "a&b=c" }),
-    ).toContain("id=a%26b%3Dc&");
-  });
-
-  it("degrades to a same-origin URL when no consumer configured a host", () => {
-    expect(buildStorybookEmbedUrl({ template: "", story: STORY })).toBe(
-      `/iframe.html?id=${STORY}&viewMode=story&docsEmbed=1`,
-    );
-  });
-});
-
-describe("STORYBOOK_EMBED_DEFAULT_HEIGHTS", () => {
-  // Reserved before the story reports anything — the space that keeps the embed
-  // from shifting the page. Panel carries the addon panel on top of the story.
-  it("reserves more room for the panel surface than the bare story", () => {
-    expect(STORYBOOK_EMBED_DEFAULT_HEIGHTS).toEqual({ preview: 320, full: 320, panel: 600 });
-  });
-});
-
-describe("storybookEmbedCssHeight", () => {
-  it("reads a bare number as pixels, in either type markdown may deliver", () => {
-    expect(storybookEmbedCssHeight(420)).toBe("420px");
-    expect(storybookEmbedCssHeight("420")).toBe("420px");
-    expect(storybookEmbedCssHeight(" 420 ")).toBe("420px");
-  });
-
-  it("passes a CSS length through untouched", () => {
-    expect(storybookEmbedCssHeight("30rem")).toBe("30rem");
-    expect(storybookEmbedCssHeight("420px")).toBe("420px");
-    expect(storybookEmbedCssHeight("min(80vh, 600px)")).toBe("min(80vh, 600px)");
-  });
-});

package/app/utils/storybookEmbed.ts

@@ -1,93 +0,0 @@
-import { DOCS_EMBED_PARAM } from "../../storybook";
-
-/**
- * Which Storybook surface a `StorybookEmbed` addresses.
- *
- * The three values are not styling choices — each is a different URL against a
- * different Storybook surface, and the height signal reaches the page by a
- * different route in each. See `@uxfront/layer-docs/storybook`.
- *
- * - `preview` — `iframe.html`, the story on its own with no Storybook UI.
- * - `full` — the manager in full-canvas mode: story plus toolbar, no panel.
- * - `panel` — the manager with its addon panel, for stories documented through
- *   controls or actions.
- */
-export type StorybookEmbedMode = "preview" | "full" | "panel";
-
-/**
- * Height an embed occupies before Storybook reports its own, and the height it
- * keeps if no bridge is installed on the Storybook side.
- *
- * The panel default is taller because the addon panel is a fixed cost on top of
- * the story. Reserving the space up front is what keeps the embed from shifting
- * the page when the real height arrives.
- */
-export const STORYBOOK_EMBED_DEFAULT_HEIGHTS: Record<StorybookEmbedMode, number> = {
-  preview: 320,
-  full: 320,
-  panel: 600,
-};
-
-/**
- * Resolve a Storybook base URL from a template.
- *
- * A `{framework}` placeholder addresses a per-framework Storybook deployment
- * (`https://{framework}.storybook.example.com`); a template without one is used
- * as-is, so a single-Storybook site needs no placeholder.
- */
-export function resolveStorybookBaseUrl(template: string, framework?: string): string {
-  return template.replaceAll("{framework}", framework ?? "").replace(/\/+$/, "");
-}
-
-export interface StorybookEmbedUrlOptions {
-  /** Base URL template, optionally containing `{framework}`. */
-  template: string;
-  /** Storybook story id, e.g. `components-actions-button--default`. */
-  story: string;
-  /** Framework substituted into the template's `{framework}` placeholder. */
-  framework?: string;
-  /** Storybook surface to address. Defaults to `preview`. */
-  mode?: StorybookEmbedMode;
-}
-
-/**
- * Build the `src` for an embedded story.
- *
- * `preview` is marked with `docsEmbed=1`: embedded that way the docs page is
- * the preview's direct parent, so the preview bridge must post the final height
- * itself rather than the intermediate one it sends to a manager.
- *
- * An empty template yields a root-relative URL rather than a broken absolute
- * one, which is what an unconfigured consumer gets — a same-origin 404 it can
- * see, not a silent request to nowhere.
- */
-export function buildStorybookEmbedUrl(options: StorybookEmbedUrlOptions): string {
-  const { template, story, framework, mode = "preview" } = options;
-
-  const base = resolveStorybookBaseUrl(template, framework);
-  const id = encodeURIComponent(story);
-
-  if (mode === "preview") {
-    return `${base}/iframe.html?id=${id}&viewMode=story&${DOCS_EMBED_PARAM}=1`;
-  }
-
-  // `singleStory` hides the sidebar, `shortcuts` stops the embed from
-  // swallowing keystrokes meant for the page around it, and `full` drops the
-  // addon panel.
-  const full = mode === "full" ? "&full=1" : "";
-
-  return `${base}/?path=/story/${id}${full}&shortcuts=false&singleStory=true`;
-}
-
-/**
- * Coerce an author-supplied height to a CSS length. A bare number — in either
- * type, since markdown attributes arrive as strings — means pixels; anything
- * else is already a CSS length and is passed through.
- */
-export function storybookEmbedCssHeight(height: number | string): string {
-  if (typeof height === "number") return `${height}px`;
-
-  const trimmed = height.trim();
-
-  return /^\d+(\.\d+)?$/.test(trimmed) ? `${trimmed}px` : trimmed;
-}

package/i18n/locales/ar.json

@@ -1,24 +0,0 @@
-{
-  "common": {
-    "or": "أو",
-    "error": {
-      "title": "الصفحة غير موجودة",
-      "description": "نأسف، لكن الصفحة التي تبحث عنها غير موجودة."
-    }
-  },
-  "docs": {
-    "copy": {
-      "page": "نسخ الصفحة",
-      "options": "خيارات نسخ إضافية",
-      "link": "نسخ صفحة Markdown",
-      "view": "عرض كـ Markdown",
-      "gpt": "فتح في ChatGPT",
-      "claude": "فتح في Claude"
-    },
-    "framework": "إطار العمل",
-    "links": "المجتمع",
-    "toc": "في هذه الصفحة",
-    "report": "الإبلاغ عن مشكلة",
-    "edit": "تحرير هذه الصفحة"
-  }
-}

package/i18n/locales/be.json

@@ -1,24 +0,0 @@
-{
-  "common": {
-    "or": "або",
-    "error": {
-      "title": "Старонка не знойдзена",
-      "description": "Прабачце, але старонка, якую вы шукаеце, не знойдзена."
-    }
-  },
-  "docs": {
-    "copy": {
-      "page": "Скапіраваць старонку",
-      "options": "Дадатковыя параметры капіравання",
-      "link": "Скапіраваць Markdown-старонку",
-      "view": "Праглядзець як Markdown",
-      "gpt": "Адкрыць у ChatGPT",
-      "claude": "Адкрыць у Claude"
-    },
-    "framework": "Фреймворк",
-    "links": "Супольнасць",
-    "toc": "На гэтай старонцы",
-    "report": "Паведаміць пра праблему",
-    "edit": "Рэдагаваць гэтую старонку"
-  }
-}

package/i18n/locales/bn.json

@@ -1,24 +0,0 @@
-{
-  "common": {
-    "or": "অথবা",
-    "error": {
-      "title": "পেজ খুঁজে পাওয়া যায়নি",
-      "description": "দুঃখিত, আপনি যে পেজটি খুঁজছেন সেটি পাওয়া যায়নি।"
-    }
-  },
-  "docs": {
-    "copy": {
-      "page": "পেজ কপি করুন",
-      "options": "আরও কপি অপশন",
-      "link": "Markdown পেজ কপি করুন",
-      "view": "Markdown হিসেবে দেখুন",
-      "gpt": "ChatGPT এ খুলুন",
-      "claude": "Claude এ খুলুন"
-    },
-    "framework": "ফ্রেমওয়ার্ক",
-    "links": "কমিউনিটি",
-    "toc": "এই পেজে",
-    "report": "সমস্যা রিপোর্ট করুন",
-    "edit": "এই পেজ সম্পাদনা করুন"
-  }
-}

package/i18n/locales/ca.json

@@ -1,24 +0,0 @@
-{
-  "common": {
-    "or": "o",
-    "error": {
-      "title": "Pàgina no trobada",
-      "description": "Ho sentim, però la pàgina que cerques no existeix."
-    }
-  },
-  "docs": {
-    "copy": {
-      "page": "Copiar pàgina",
-      "options": "Més opcions de còpia",
-      "link": "Copiar pàgina Markdown",
-      "view": "Veure com a Markdown",
-      "gpt": "Obrir a ChatGPT",
-      "claude": "Obrir a Claude"
-    },
-    "framework": "Framework",
-    "links": "Comunitat",
-    "toc": "En aquesta pàgina",
-    "report": "Informar d'un problema",
-    "edit": "Editar aquesta pàgina"
-  }
-}

package/i18n/locales/ckb.json

@@ -1,24 +0,0 @@
-{
-  "common": {
-    "or": "یان",
-    "error": {
-      "title": "پەڕە نەدۆزرایەوە",
-      "description": "بەداخەوە، ئەم پەڕەیە نەدۆزرایەوە."
-    }
-  },
-  "docs": {
-    "copy": {
-      "page": "کۆپیکردنی پەڕە",
-      "options": "بژاردەی زیاتری لەبەرگرتنەوە",
-      "link": "کۆپیکردنی پەڕەی Markdown",
-      "view": "بینین وەک Markdown",
-      "gpt": "کردنەوە لە ChatGPT",
-      "claude": "کردنەوە لە Claude"
-    },
-    "framework": "چوارچێوە",
-    "links": "کۆمەڵگا",
-    "toc": "لەم پەڕەدا",
-    "report": "ڕاپۆرتکردنی کێشە",
-    "edit": "دەستکاریکردنی ئەم پەڕەیە"
-  }
-}