@uxfront/layer-docs 0.4.0 → 0.5.0

package/app/components/app/AppHeader.vue

@@ -1,123 +0,0 @@
-<script setup lang="ts">
-import { useResizeObserver } from "@vueuse/core";
-import { useDocusI18n } from "../../composables/useDocusI18n";
-
-const appConfig = useAppConfig();
-const site = useSiteConfig();
-
-const { localePath, isEnabled, locales } = useDocusI18n();
-
-const route = useRoute();
-const isDocs = computed(() => route.path.startsWith("/docs"));
-
-const headerEl = ref<HTMLElement | null>(null);
-
-onMounted(() => {
-  headerEl.value = document.querySelector<HTMLElement>("header");
-});
-
-useResizeObserver(headerEl, ([entry]) => {
-  if (!isDocs.value || !entry) return;
-  const height = entry.contentRect.height;
-  if (height > 0) {
-    document.documentElement.style.setProperty("--ui-header-height", `${height}px`);
-  }
-});
-
-watch(isDocs, (docs) => {
-  if (!docs) {
-    document.documentElement.style.removeProperty("--ui-header-height");
-  }
-});
-
-const links = computed(() =>
-  appConfig.github && appConfig.github.url
-    ? [
-        {
-          icon: "i-simple-icons-github",
-          to: appConfig.github.url,
-          target: "_blank",
-          "aria-label": "GitHub",
-        },
-      ]
-    : [],
-);
-</script>
-
-<template>
-  <UHeader
-    :ui="{ center: 'flex-1', root: isDocs ? 'h-auto' : '', container: 'h-16' }"
-    :to="localePath('/')"
-    :title="appConfig.header?.title || site.name"
-  >
-    <AppHeaderCenter />
-
-    <!--
-      `#left` rather than `#title`: UHeader wraps the `#title` slot in its own
-      `<ULink :to>` home link, so an attribution link rendered there would be an
-      anchor nested in an anchor — invalid HTML that browsers unnest at parse
-      time. Owning `#left` lets the wordmark and the attribution sit as
-      siblings. The link classes restate UHeader's `title` slot theme, which the
-      slot itself does not expose.
-    -->
-    <template #left>
-      <div class="flex shrink-0 items-baseline gap-1.5">
-        <ULink
-          :to="localePath('/')"
-          :aria-label="appConfig.header?.title || site.name"
-          class="flex shrink-0 items-end gap-1.5 rounded-xs text-xl font-bold text-highlighted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
-        >
-          <AppHeaderLogo class="h-6 w-auto shrink-0" />
-        </ULink>
-
-        <AppHeaderAttribution />
-      </div>
-    </template>
-
-    <template #right>
-      <AppHeaderCTA class="max-sm:hidden" />
-
-      <template v-if="isEnabled && locales.length > 1">
-        <ClientOnly>
-          <LanguageSelect />
-
-          <template #fallback>
-            <div class="h-8 w-8 animate-pulse bg-neutral-200 dark:bg-neutral-800 rounded-md" />
-          </template>
-        </ClientOnly>
-
-        <USeparator orientation="vertical" class="h-8" />
-      </template>
-
-      <UContentSearchButton class="lg:hidden" />
-
-      <ClientOnly>
-        <UColorModeButton />
-
-        <template #fallback>
-          <div class="h-8 w-8 animate-pulse bg-neutral-200 dark:bg-neutral-800 rounded-md" />
-        </template>
-      </ClientOnly>
-
-      <template v-if="links?.length">
-        <UButton
-          v-for="(link, index) of links"
-          :key="index"
-          v-bind="{ color: 'neutral', variant: 'ghost', ...link }"
-        />
-      </template>
-    </template>
-
-    <template #toggle="{ open, toggle }">
-      <IconMenuToggle :open="open" class="lg:hidden" @click="toggle" />
-    </template>
-
-    <template #body>
-      <AppHeaderBody />
-    </template>
-
-    <template v-if="isDocs" #bottom>
-      <AppSubHeader />
-    </template>
-  </UHeader>
-</template>

package/app/components/app/AppHeaderAttribution.vue

@@ -1,45 +0,0 @@
-<script setup lang="ts">
-/**
- * Optional brand attribution rendered next to the header wordmark, e.g.
- * "uxd by UXFront" where only "UXFront" is a link.
- *
- * Declared by the consuming app as:
- *
- * ```ts
- * header: {
- *   title: "uxd",
- *   attribution: { prefix: "by", label: "UXFront", to: "https://uxfront.com" },
- * }
- * ```
- *
- * `prefix` stays plain text so the link's accessible name is exactly the brand
- * it points at — "by UXFront" would read as the link text otherwise.
- */
-type Attribution = { prefix?: string; label?: string; to?: string };
-
-const appConfig = useAppConfig();
-
-// Read through a local type, as `AppHeaderCTA` does for `header.links`: Nuxt's
-// generated `AppConfig` prefers the shape inferred from the merged
-// `app.config.ts` values over the `nuxt.schema.ts` type, so a consumer that
-// declares `header` without `attribution` erases the key from the type even
-// though the layer's own defaults supply it at runtime.
-const attribution = computed(
-  () => (appConfig.header as { attribution?: Attribution } | undefined)?.attribution,
-);
-</script>
-
-<template>
-  <p v-if="attribution?.label" class="shrink-0 text-sm text-muted">
-    <!-- Non-breaking space: Vue's `condense` whitespace handling drops a plain
-         trailing space before a newline, and the credit should not wrap. -->
-    <template v-if="attribution.prefix">{{ attribution.prefix }}&nbsp;</template>
-    <ULink
-      v-if="attribution.to"
-      :to="attribution.to"
-      class="rounded-xs font-medium text-toned underline underline-offset-2 hover:text-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
-      >{{ attribution.label }}</ULink
-    >
-    <template v-else>{{ attribution.label }}</template>
-  </p>
-</template>

package/app/components/app/AppHeaderBody.vue

@@ -1,14 +0,0 @@
-<script setup lang="ts">
-import type { ContentNavigationItem } from "@nuxt/content";
-
-const navigationMap = inject<Ref<Record<string, ContentNavigationItem[]> | null>>("navigation");
-
-const navigation = computed<ContentNavigationItem[]>(() =>
-  navigationMap?.value ? Object.values(navigationMap.value).flat() : [],
-);
-</script>
-
-<template>
-  <AppHeaderCTA highlight variant="link" orientation="vertical" class="min-sm:hidden mb-4 -ml-2" />
-  <UContentNavigation highlight variant="link" :navigation="navigation" />
-</template>

package/app/components/app/AppHeaderCTA.vue

@@ -1,31 +0,0 @@
-<script setup lang="ts">
-import type { NavigationMenuItem } from "@nuxt/ui";
-
-/**
- * Neutral header CTA menu. The links are brand data, so they come from the
- * consumer's `app.config.ts` under `header.links` — this layer ships none.
- * Each entry is a Nuxt UI `NavigationMenuItem`; a `startsWith` string on
- * `activeMatch` marks the item active for the current route prefix.
- */
-type HeaderLink = NavigationMenuItem & { activeMatch?: string };
-
-const route = useRoute();
-const appConfig = useAppConfig();
-
-// `header` is seeded partially in `modules/config.ts`, so defu's resolved
-// AppConfig type narrows it to `{ title, logo }` and drops the array-valued
-// `links`. Cast `header` itself (not the `.links` result) to read it safely.
-const items = computed<NavigationMenuItem[]>(() =>
-  ((appConfig.header as { links?: HeaderLink[] } | undefined)?.links ?? []).map((link) => {
-    const { activeMatch, ...rest } = link;
-    return {
-      ...rest,
-      active: rest.active ?? (activeMatch ? route.path.startsWith(activeMatch) : undefined),
-    };
-  }),
-);
-</script>
-
-<template>
-  <UNavigationMenu v-if="items.length" :items="items" />
-</template>

package/app/components/app/AppHeaderCenter.vue

@@ -1,10 +0,0 @@
-<template>
-  <UContentSearchButton
-    :collapsed="false"
-    class="w-full"
-    variant="soft"
-    :ui="{
-      leadingIcon: 'size-4 mr-1',
-    }"
-  />
-</template>

package/app/components/app/AppHeaderLogo.vue

@@ -1,16 +0,0 @@
-<script setup lang="ts">
-const appConfig = useAppConfig();
-</script>
-
-<template>
-  <UColorModeImage
-    v-if="appConfig.header?.logo?.dark || appConfig.header?.logo?.light"
-    :light="appConfig.header?.logo?.light || appConfig.header?.logo?.dark"
-    :dark="appConfig.header?.logo?.dark || appConfig.header?.logo?.light"
-    :alt="appConfig.header?.logo?.alt || appConfig.header?.title"
-    class="h-6 w-auto shrink-0"
-  />
-  <span v-else>
-    {{ appConfig.header?.title || "{appConfig.header.title}" }}
-  </span>
-</template>

package/app/components/app/AppOgDecoration.vue

@@ -1,27 +0,0 @@
-<script lang="ts" setup>
-/**
- * Decorative flourish behind the OG card — the "slot" of the OG templates.
- *
- * `defineOgImage(name, props)` serialises its props into the payload, so a real
- * Vue slot cannot cross that boundary. The Nuxt-native equivalent is app-dir
- * component precedence: a consumer shadows this file at the same path to supply
- * its own decoration, or ships an empty template to render nothing. That is the
- * same override mechanism consumers already use for `DocsAsideLeftBody`.
- *
- * Geometry only, no brand mark: a soft radial wash in the top-right corner.
- * Deliberately not the source SVG blob — satori implements a subset of SVG and
- * does not apply `filter` / `feGaussianBlur`, so the blurred shape would render
- * as a hard-edged starburst. A `radial-gradient` background is satori-native
- * and preserves what the blur was there for.
- *
- * Bound rather than written as a `style` attribute so it stays on one line:
- * satori's gradient parser rejects a value containing newlines, and a formatter
- * will wrap an attribute this long across lines given the chance.
- */
-const backgroundImage =
-  "radial-gradient(circle at 75% 15%, rgba(255, 255, 255, 0.28) 0%, rgba(255, 255, 255, 0.1) 35%, rgba(255, 255, 255, 0) 70%)";
-</script>
-
-<template>
-  <div class="absolute right-0 top-0 h-[593px] w-[629px]" :style="{ backgroundImage }" />
-</template>

package/app/components/app/AppOgLogo.vue

@@ -1,19 +0,0 @@
-<script lang="ts" setup>
-/**
- * Wordmark for the OG card. Overridable at the same path, like
- * {@link AppOgDecoration}.
- *
- * Text, not `AppHeaderLogo`: that component renders `UColorModeImage`, which
- * needs a colour mode and resolves relative image paths against the browser —
- * satori has neither, so it needs an absolute URL and no colour mode at all. A
- * brand that wants its mark here overrides this file with an `<img>` pointing
- * at an absolute URL; stating that limit rather than half-solving it.
- */
-const appConfig = useAppConfig();
-</script>
-
-<template>
-  <span class="text-[32px] font-semibold text-white">
-    {{ appConfig.header?.title }}
-  </span>
-</template>

package/app/components/app/AppSearch.vue

@@ -1,59 +0,0 @@
-<script setup lang="ts">
-import type { ContentNavigationItem, PageCollections } from "@nuxt/content";
-
-const props = defineProps<{
-  navigation?: ContentNavigationItem[];
-}>();
-
-const { locale, isEnabled } = useDocusI18n();
-
-// FTS5 indexes one collection at a time; our docs are split across a
-// collection per top-level section (and per locale), so we hand
-// `useSearchCollection` the whole set and let it index and query them together.
-const collections = computed(() =>
-  DOCS_SECTIONS.map(
-    (section) =>
-      (isEnabled.value
-        ? `docs_${section.key}_${locale.value}`
-        : `docs_${section.key}`) as keyof PageCollections,
-  ),
-);
-
-const {
-  search,
-  status: searchStatus,
-  init,
-} = useSearchCollection(collections, {
-  immediate: false,
-  ignoredTags: ["style"],
-});
-
-// Build the SQLite FTS5 index lazily: only when the palette first opens, so
-// the search payload never loads on pages the reader never searches from.
-const { open } = useContentSearch();
-watch(open, (value) => {
-  if (value && searchStatus.value === "idle") {
-    init();
-  }
-});
-
-// Empty-state shortcuts shown before the reader types anything.
-const links = computed(() =>
-  props.navigation
-    ?.filter((item) => item.children?.length)
-    .map((item) => ({
-      label: item.title,
-      icon: item.icon as string | undefined,
-      to: item.children![0]!.path,
-    })),
-);
-</script>
-
-<template>
-  <LazyUContentSearch
-    :search="search"
-    :search-status="searchStatus"
-    :links="links"
-    :navigation="navigation"
-  />
-</template>

package/app/components/app/AppSubHeader.vue

@@ -1,21 +0,0 @@
-<script setup lang="ts">
-import type { NavigationMenuItem } from "@nuxt/ui";
-
-const { sections, hasSectionSwitcher } = useDocsSections();
-
-const items = computed<NavigationMenuItem[]>(() =>
-  sections.value.map((section) => ({
-    label: section.label,
-    to: section.to,
-    active: section.active,
-  })),
-);
-</script>
-
-<template>
-  <div v-if="hasSectionSwitcher" class="border-t border-default max-lg:hidden">
-    <UContainer class="py-1">
-      <UNavigationMenu :items="items" :ui="{ root: 'overflow-x-auto no-scrollbar' }" />
-    </UContainer>
-  </div>
-</template>

package/app/components/content/BrowserFrame.vue

@@ -1,28 +0,0 @@
-<script setup lang="ts">
-interface Props {
-  title?: string;
-}
-
-defineProps<Props>();
-</script>
-
-<template>
-  <div class="p-1 border border-default rounded text-sm bg-default/70">
-    <div
-      v-if="title"
-      class="flex items-center bg-slate-100 dark:bg-slate-800 p-2 rounded font-bold"
-    >
-      <span class="flex gap-1 absolute">
-        <span class="rounded-full bg-error inline-flex w-3 h-3" />
-        <span class="rounded-full bg-warning inline-flex w-3 h-3" />
-        <span class="rounded-full bg-success inline-flex w-3 h-3" />
-      </span>
-      <span class="flex w-full align-center justify-center">
-        {{ title }}
-      </span>
-    </div>
-    <div class="px-3 overflow-auto">
-      <slot mdc-unwrap="p" />
-    </div>
-  </div>
-</template>

package/app/components/content/GradientPageHero.vue

@@ -1,35 +0,0 @@
-<script setup lang="ts">
-/**
- * `UPageHero` on the layer's `MorphingGradientBackground`, usable from MDC:
- *
- * ```mdc
- * ::gradient-page-hero
- * ---
- * ---
- * #title
- * Your headline
- * ::
- * ```
- *
- * Ships with `MorphingGradientBackground` rather than beside it: a package that
- * hands you the ingredient should hand you the recipe too. The gradient's own
- * base surface follows `--ui-bg`; its blob colours are the background
- * component's own fixed palette, overridable per consumer by restating the
- * `--color1..5` custom properties on an ancestor.
- */
-defineOptions({
-  inheritAttrs: false,
-});
-</script>
-
-<template>
-  <MorphingGradientBackground v-slot="{ onMousemove }">
-    <UPageHero v-bind="$attrs" @mousemove="onMousemove">
-      <slot />
-      <template #title><slot name="title" /></template>
-      <template #description><slot name="description" /></template>
-      <template #headline><slot name="headline" /></template>
-      <template #links><slot name="links" /></template>
-    </UPageHero>
-  </MorphingGradientBackground>
-</template>

package/app/components/content/StorybookEmbed.vue

@@ -1,160 +0,0 @@
-<script setup lang="ts">
-import { useIntersectionObserver } from "@vueuse/core";
-// Resolved through `#components` rather than imported by path so a consumer
-// that ships its own `BrowserFrame` overrides this one, as with any other
-// component in the layer.
-import { BrowserFrame } from "#components";
-import { docsEmbedMessageNames, readDocsEmbedHeight } from "../../../storybook";
-import {
-  buildStorybookEmbedUrl,
-  STORYBOOK_EMBED_DEFAULT_HEIGHTS,
-  storybookEmbedCssHeight,
-  type StorybookEmbedMode,
-} from "../../utils/storybookEmbed";
-
-/**
- * Embeds a single story from the consumer's deployed Storybook.
- *
- * The Storybook host is a consumer fact, never a layer one: it comes from
- * `runtimeConfig.public.storybookBaseUrl`, which is empty here and set per
- * consumer — in `nuxt.config.ts` or, without a rebuild,
- * `NUXT_PUBLIC_STORYBOOK_BASE_URL`.
- *
- * ```md
- * :storybook-embed{story="components-actions-button--default"}
- * :storybook-embed{story="components-forms-input--default" mode="panel"}
- * ```
- *
- * Three behaviours are always on, and all three degrade rather than fail:
- *
- * - **Lazy mount.** The iframe is not created until the embed comes near the
- *   viewport, so a page with twenty embeds loads one Storybook, not twenty.
- * - **Theme sync.** The page's colour mode is posted to the story on load and
- *   on every change, so an embed never sits light inside a dark page.
- * - **Auto-height.** The story reports what it needs and the frame follows.
- *
- * Theme and height both need `@uxfront/layer-docs/storybook` installed in the
- * Storybook config. Without it the frame keeps `height` (or the mode's
- * default) and the story renders in its own theme — degraded, not broken.
- */
-interface Props {
-  /** Storybook story id, e.g. `components-actions-button--default`. */
-  story: string;
-  /**
-   * Framework substituted into the base URL's `{framework}` placeholder.
-   * Defaults to the reader's selected framework, so an embed inside a
-   * `FrameworkSwitcher` tab needs it and a standalone one does not.
-   */
-  framework?: string;
-  /** Storybook surface to embed. */
-  mode?: StorybookEmbedMode;
-  /**
-   * Fixed height. Set this and auto-height is off — the story's own report is
-   * ignored, which is what you want for a story whose height oscillates.
-   */
-  height?: number | string;
-  /** Caption for the browser frame. Omit to render the story unframed. */
-  title?: string;
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  framework: undefined,
-  mode: "preview",
-  height: undefined,
-  title: undefined,
-});
-
-const config = useRuntimeConfig();
-const storybookBaseUrl = computed(() => (config.public.storybookBaseUrl as string) ?? "");
-const messageNames = computed(() =>
-  docsEmbedMessageNames(config.public.storybookLegacyMessageNamespace as string),
-);
-
-const { framework: selectedFramework } = useFramework();
-const framework = computed(() => props.framework ?? selectedFramework.value);
-
-const colorMode = useColorMode();
-const containerRef = useTemplateRef<HTMLElement>("container");
-const iframeRef = useTemplateRef<HTMLIFrameElement>("iframe");
-
-// Mount the iframe just before it is scrolled to, then stop observing — the
-// answer cannot change back.
-const visible = ref(false);
-const { stop } = useIntersectionObserver(
-  containerRef,
-  ([entry]) => {
-    if (!entry?.isIntersecting) return;
-    visible.value = true;
-    stop();
-  },
-  { rootMargin: "200px" },
-);
-
-const src = computed(() =>
-  buildStorybookEmbedUrl({
-    template: storybookBaseUrl.value,
-    story: props.story,
-    framework: framework.value,
-    mode: props.mode,
-  }),
-);
-
-const reportedHeight = ref<number | null>(null);
-const cssHeight = computed(() =>
-  storybookEmbedCssHeight(
-    props.height ?? reportedHeight.value ?? STORYBOOK_EMBED_DEFAULT_HEIGHTS[props.mode],
-  ),
-);
-
-// An iframe is an unlabelled frame to a screen reader. The caption names it
-// when there is one; otherwise say what it holds rather than leaving it silent.
-const frameTitle = computed(
-  () => props.title ?? `Storybook preview: ${props.story.replace(/-+/g, " ")}`,
-);
-
-const wrapper = computed(() => (props.title ? BrowserFrame : "div"));
-const wrapperProps = computed(() => (props.title ? { title: props.title } : {}));
-
-function sendTheme() {
-  const target = iframeRef.value?.contentWindow;
-  if (!target) return;
-
-  const theme = colorMode.value === "dark" ? "dark" : "light";
-  for (const type of messageNames.value.theme) {
-    target.postMessage({ type, theme }, "*");
-  }
-}
-
-function onMessage(event: MessageEvent) {
-  // Scope by source, not by origin: the Storybook host is consumer-configured
-  // and may differ per framework, but only one window can be this iframe.
-  if (event.source !== iframeRef.value?.contentWindow) return;
-
-  const height = readDocsEmbedHeight(event.data, messageNames.value.height);
-  if (height !== null) reportedHeight.value = height;
-}
-
-onMounted(() => window.addEventListener("message", onMessage));
-onUnmounted(() => window.removeEventListener("message", onMessage));
-
-watch(() => colorMode.value, sendTheme);
-</script>
-
-<template>
-  <component :is="wrapper" v-bind="wrapperProps">
-    <div
-      ref="container"
-      class="storybook-embed border border-default rounded overflow-hidden min-h-25 resize-y transition-[height] duration-150 ease-out motion-reduce:transition-none"
-      :style="{ height: cssHeight }"
-    >
-      <iframe
-        v-if="visible"
-        ref="iframe"
-        :src="src"
-        :title="frameTitle"
-        class="block w-full h-full border-0"
-        @load="sendTheme"
-      />
-    </div>
-  </component>
-</template>