@uxfront/layer-docs 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,11 +4,50 @@
 
 ### 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.
+- Correct the changelog so it matches what was actually published. `0.1.1` shipped
+  with no entry of its own while an entry for a `0.1.2` that was never published
+  sat at the top of the file, so consumers had no way to learn from the changelog
+  that `0.1.1` contains accessibility fixes for `button-name` and
+  `nested-interactive` violations. `0.1.1` now has a complete entry, and the
+  `AppHeaderCTA.vue` typecheck fix previously filed under `0.1.2` is recorded
+  under `0.1.0`, the release it actually shipped in. No runtime code changed in
+  this release.
+
+## 0.1.1
+
+### Minor Changes
+
+- Add `header.attribution` so a consuming app can render a partially-linked
+  wordmark, e.g. "uxd by UXFront" where only "UXFront" links out. The header now
+  owns UHeader's `#left` slot instead of `#title`, because `#title` is rendered
+  inside UHeader's own home link and an attribution link there would nest
+  anchors. Apps that do not set `attribution` render exactly as before.
+
+### Patch Changes
+
+- Fix accessible names on icon-only navigation controls and hide the section
+  sub-header when there is nothing to switch between.
+
+  - The mobile menu toggle and the "copy page" dropdown trigger now expose
+    accessible names (sourced from the active locale), clearing two critical
+    `button-name` violations that shipped on every page. **Consumers on `0.1.0`
+    should upgrade** — those violations were present on every page of every
+    site extending this layer.
+  - The page footer separator is now `decorative`, clearing a serious
+    `nested-interactive` violation caused by focusable links inside an element
+    with `role="separator"`.
+  - The docs sub-header no longer renders when the consumer declares one section
+    or none, so a single-section site gets no empty bar and no extra header
+    height.
+
+- Skip PostHog initialisation when no key is provisioned
+  (`NUXT_PUBLIC_POSTHOG_KEY` unset), instead of initialising a client that fires
+  requests at nothing.
+
+Note: `0.1.1` was versioned by hand rather than through `changeset version`, so
+it published as a patch even though `header.attribution` is additive and would
+have produced `0.2.0`. The published number stands; the entry above is the
+accurate record of its contents. See UXF-67.
 
 ## 0.1.0
 
@@ -19,3 +58,16 @@
   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`.
+
+### 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.
+
+  This fix was previously filed under a `## 0.1.2` heading that no published
+  release ever carried. It was written while the package was still named
+  `@uxfront/docs-theme` — a name that was never published — and it shipped in
+  `@uxfront/layer-docs@0.1.0`, the first release under the current name.

package/README.md

@@ -42,6 +42,24 @@ export default defineAppConfig({
 });
 ```
 
+### Brand attribution
+
+`header.attribution` renders an optional credit beside the wordmark, where only
+the `label` is a link:
+
+```ts
+export default defineAppConfig({
+  header: {
+    title: "uxd",
+    attribution: { prefix: "by", label: "UXFront", to: "https://uxfront.com" },
+  },
+});
+```
+
+That renders `uxd by UXFront` — the wordmark still links home, `by` is plain
+text, and `UXFront` links out. Omit `attribution` (or leave `label` empty) to
+render the wordmark alone.
+
 ## Compatibility
 
 Pinned to the Nuxt 4 documentation stack (Nuxt 4.4, Nuxt UI 4.8, Content 3.14,

package/app/app.config.ts

@@ -13,6 +13,20 @@ export default defineAppConfig({
     title: "On this page",
   },
 
+  header: {
+    /**
+     * Optional brand attribution rendered beside the header wordmark.
+     * `title: "uxd"` plus `{ prefix: "by", label: "UXFront", to: "https://uxfront.com" }`
+     * renders "uxd by UXFront" with only "UXFront" linked. An empty `label`
+     * renders nothing, which is the neutral default.
+     */
+    attribution: {
+      prefix: "",
+      label: "",
+      to: "",
+    },
+  },
+
   /**
    * 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`.

package/app/components/IconMenuToggle.vue

@@ -1,11 +1,16 @@
 <script setup lang="ts">
 import { motion } from "motion-v";
 import type { VariantType } from "motion-v";
+import { useLocale } from "@nuxt/ui/composables/useLocale";
 
 const props = defineProps<{
   open: boolean;
 }>();
 
+// Same strings Nuxt UI's default `UHeader` toggle uses, so the accessible name
+// stays in sync with the app's locale instead of being hardcoded here.
+const { t } = useLocale();
+
 const variants: {
   [k: string]: VariantType | ((custom: unknown) => VariantType);
 } = {
@@ -33,7 +38,14 @@ const state = computed(() => (props.open ? "close" : "normal"));
 </script>
 
 <template>
-  <UButton size="sm" variant="ghost" color="neutral" class="-me-1.5" square>
+  <UButton
+    size="sm"
+    variant="ghost"
+    color="neutral"
+    class="-me-1.5"
+    square
+    :aria-label="open ? t('header.close') : t('header.open')"
+  >
     <svg
       xmlns="http://www.w3.org/2000/svg"
       class="size-5"
@@ -43,6 +55,7 @@ const state = computed(() => (props.open ? "close" : "normal"));
       stroke-width="2"
       stroke-linecap="round"
       stroke-linejoin="round"
+      aria-hidden="true"
     >
       <motion.line
         x1="4"

package/app/components/app/AppHeader.vue

@@ -52,8 +52,26 @@ const links = computed(() =>
   >
     <AppHeaderCenter />
 
-    <template #title>
-      <AppHeaderLogo class="h-6 w-auto shrink-0" />
+    <!--
+      `#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>

package/app/components/app/AppHeaderAttribution.vue

@@ -0,0 +1,45 @@
+<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/AppSubHeader.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { NavigationMenuItem } from "@nuxt/ui";
 
-const { sections } = useDocsSections();
+const { sections, hasSectionSwitcher } = useDocsSections();
 
 const items = computed<NavigationMenuItem[]>(() =>
   sections.value.map((section) => ({
@@ -13,7 +13,7 @@ const items = computed<NavigationMenuItem[]>(() =>
 </script>
 
 <template>
-  <div class="border-t border-default max-lg:hidden">
+  <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>

package/app/components/content/FrameworkSwitcher.vue

@@ -22,6 +22,7 @@ function select(value: string) {
 <template>
   <div class="framework-switcher">
     <div
+      v-if="frameworks.length"
       class="framework-switcher-tabs flex flex-wrap gap-1 mb-3 border-b border-default"
       role="tablist"
     >

package/app/components/content/GradientPageHero.vue

@@ -0,0 +1,35 @@
+<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/docs/DocsAsideLeftTop.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+/**
+ * Persistent framework selector above the docs sidebar navigation.
+ *
+ * Renders nothing unless the consumer declares `docsTheme.frameworks` in its
+ * `app.config.ts`. The in-content `FrameworkSwitcher` shares the same state,
+ * but per-page tabs alone scale poorly past a handful of frameworks — this is
+ * the always-visible control for the same preference.
+ */
+const { frameworks } = useFramework();
+const { t } = useDocusI18n();
+</script>
+
+<template>
+  <div v-if="frameworks.length">
+    <span
+      class="group relative w-full pr-2.5 py-1.5 flex items-center gap-1.5 text-sm text-muted cursor-default hover:text-highlighted transition-colors font-normal"
+    >
+      <span class="truncate">{{ t("docs.framework") }}</span>
+    </span>
+
+    <DocsFrameworkSelect class="mb-2" />
+  </div>
+</template>

package/app/components/docs/DocsFrameworkSelect.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+const { framework, frameworks } = useFramework();
+
+const current = computed(
+  () => frameworks.value.find((option) => option.value === framework.value) ?? frameworks.value[0],
+);
+</script>
+
+<template>
+  <USelect
+    v-model="framework"
+    :items="[...frameworks]"
+    variant="ghost"
+    color="neutral"
+    :icon="current?.icon"
+    class="w-full"
+  />
+</template>

package/app/components/docs/DocsPageHeaderLinks.vue

@@ -68,6 +68,7 @@ async function copyPage() {
         color="neutral"
         variant="soft"
         class="border-l border-muted"
+        :aria-label="t('docs.copy.options')"
       />
     </UDropdownMenu>
   </UFieldGroup>

package/app/composables/useDocsSections.ts

@@ -46,5 +46,12 @@ export function useDocsSections() {
 
   const activeSection = computed(() => sections.value.find((section) => section.active));
 
-  return { sections, activeSection };
+  /**
+   * Whether the section switcher is worth rendering. A single section (or none)
+   * gives the reader nothing to switch between, so the sub-header is suppressed
+   * entirely rather than rendering an empty bar.
+   */
+  const hasSectionSwitcher = computed(() => sections.value.length > 1);
+
+  return { sections, activeSection, hasSectionSwitcher };
 }

package/app/composables/useFramework.ts

@@ -1,11 +1,11 @@
 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.
+ * A single selectable framework in the docs `FrameworkSwitcher` and the sidebar
+ * `DocsFrameworkSelect`. `value` doubles as the slot name and the persisted
+ * storage token; `label` is the visible text; `icon` is an Iconify name.
+ * `value` is an open string so a consumer can declare any framework set
+ * (e.g. `svelte`, `solid`, `angular`).
  */
 export interface FrameworkOption {
   value: string;
@@ -13,9 +13,12 @@ export interface FrameworkOption {
   icon: string;
 }
 
+// Neutral, layer-owned storage key — not tied to any consuming product.
+const STORAGE_KEY = "docs-theme:framework";
+
 /**
- * Neutral, brand-agnostic default framework set. A consumer overrides the whole
- * list — in declared order — via its `app.config.ts`:
+ * Reads the framework list a consumer declares — in display order — in its
+ * `app.config.ts`:
  *
  * ```ts
  * export default defineAppConfig({
@@ -24,42 +27,30 @@ export interface FrameworkOption {
  *       { 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
  *     ],
  *   },
  * });
  * ```
  *
+ * `docsTheme.frameworks` is the only source. Which frameworks a product
+ * documents is the product's fact, not the theme's, so the layer ships no
+ * default list; a consumer that declares none gets an empty list and the
+ * framework UI renders nothing.
+ *
  * 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.
+ * would append to (not replace) the consumer's list.
  */
-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 frameworks = computed<readonly FrameworkOption[]>(
+    () => appConfig.docsTheme?.frameworks ?? [],
+  );
 
-  const framework = useLocalStorage<string>(STORAGE_KEY, frameworks.value[0]!.value, {
+  const framework = useLocalStorage<string>(STORAGE_KEY, frameworks.value[0]?.value ?? "", {
     initOnMounted: true,
   });
 

package/app/layouts/default.vue

@@ -11,6 +11,7 @@ const isDocs = computed(() => route.path.startsWith("/docs"));
       <UPage>
         <template #left>
           <UPageAside>
+            <DocsAsideLeftTop />
             <DocsAsideLeftBody />
           </UPageAside>
         </template>

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

@@ -128,7 +128,10 @@ const editLink = computed(() => {
     <UPageBody>
       <ContentRenderer v-if="page" :value="page" />
 
-      <USeparator>
+      <!-- `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"

package/app/plugins/posthog.client.ts

@@ -14,6 +14,12 @@ export default defineNuxtPlugin(() => {
 
   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;
+  }
+
   const posthogClient = posthog.init(runtimeConfig.public.posthog.key, {
     api_host: runtimeConfig.public.posthog.host,
     defaults: runtimeConfig.public.posthog.defaults as ConfigDefaults,

package/i18n/locales/ar.json

@@ -0,0 +1,24 @@
+{
+  "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

@@ -0,0 +1,24 @@
+{
+  "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

@@ -0,0 +1,24 @@
+{
+  "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

@@ -0,0 +1,24 @@
+{
+  "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

@@ -0,0 +1,24 @@
+{
+  "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/cs.json

@@ -0,0 +1,24 @@
+{
+  "common": {
+    "or": "nebo",
+    "error": {
+      "title": "Stránka nenalezena",
+      "description": "Je nám líto, ale stránka, kterou hledáte, nebyla nalezena."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Kopírovat stránku",
+      "options": "Další možnosti kopírování",
+      "link": "Kopírovat Markdown stránku",
+      "view": "Zobrazit jako Markdown",
+      "gpt": "Otevřít v ChatGPT",
+      "claude": "Otevřít v Claude"
+    },
+    "framework": "Framework",
+    "links": "Komunita",
+    "toc": "Na této stránce",
+    "report": "Nahlásit problém",
+    "edit": "Upravit tuto stránku"
+  }
+}