@uxfront/layer-docs 0.1.1 → 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/app/components/app/AppHeaderAttribution.vue

@@ -15,9 +15,18 @@
  * `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();
 
-const attribution = computed(() => appConfig.header?.attribution);
+// 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>

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/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/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"
+  }
+}

package/i18n/locales/da.json

@@ -0,0 +1,24 @@
+{
+  "common": {
+    "or": "eller",
+    "error": {
+      "title": "Side ikke fundet",
+      "description": "Vi beklager, men siden du leder efter kunne ikke findes."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Kopier side",
+      "options": "Flere kopieringsmuligheder",
+      "link": "Kopier Markdown side",
+      "view": "Vis som Markdown",
+      "gpt": "Åbn i ChatGPT",
+      "claude": "Åbn i Claude"
+    },
+    "framework": "Framework",
+    "links": "Fællesskab",
+    "toc": "På denne side",
+    "report": "Rapporter et problem",
+    "edit": "Rediger denne side"
+  }
+}

package/i18n/locales/de.json

@@ -0,0 +1,24 @@
+{
+  "common": {
+    "or": "oder",
+    "error": {
+      "title": "Seite nicht gefunden",
+      "description": "Es tut uns leid, aber diese Seite konnte nicht gefunden werden."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Seite kopieren",
+      "options": "Weitere Kopieroptionen",
+      "link": "Markdown-Seite kopieren",
+      "view": "Als Markdown anzeigen",
+      "gpt": "In ChatGPT öffnen",
+      "claude": "In Claude öffnen"
+    },
+    "framework": "Framework",
+    "links": "Community",
+    "toc": "Auf dieser Seite",
+    "report": "Problem melden",
+    "edit": "Diese Seite bearbeiten"
+  }
+}

package/i18n/locales/el.json

@@ -0,0 +1,24 @@
+{
+  "common": {
+    "or": "ή",
+    "error": {
+      "title": "Η σελίδα δεν βρέθηκε",
+      "description": "Λυπούμαστε, αλλά η σελίδα που αναζητάτε δεν υπάρχει."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Αντιγραφή σελίδας",
+      "options": "Περισσότερες επιλογές αντιγραφής",
+      "link": "Αντιγραφή σελίδας Markdown",
+      "view": "Προβολή ως Markdown",
+      "gpt": "Άνοιγμα στο ChatGPT",
+      "claude": "Άνοιγμα στο Claude"
+    },
+    "framework": "Framework",
+    "links": "Κοινότητα",
+    "toc": "Σε αυτή τη σελίδα",
+    "report": "Αναφορά προβλήματος",
+    "edit": "Επεξεργασία αυτής της σελίδας"
+  }
+}

package/i18n/locales/en.json

@@ -15,6 +15,7 @@
       "gpt": "Open in ChatGPT",
       "claude": "Open in Claude"
     },
+    "framework": "Framework",
     "links": "Community",
     "toc": "On this page",
     "report": "Report an issue",

package/i18n/locales/et.json

@@ -0,0 +1,24 @@
+{
+  "common": {
+    "or": "või",
+    "error": {
+      "title": "Lehekülge ei leitud",
+      "description": "Vabandame, kuid otsitavat lehekülge ei leitud."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Kopeeri lehekülg",
+      "options": "Rohkem kopeerimisvalikuid",
+      "link": "Kopeeri Markdown lehekülg",
+      "view": "Vaata Markdownina",
+      "gpt": "Ava ChatGPT-s",
+      "claude": "Ava Claude'is"
+    },
+    "framework": "Raamistik",
+    "links": "Kogukond",
+    "toc": "Sellel lehel",
+    "report": "Teata probleemist",
+    "edit": "Muuda seda lehekülge"
+  }
+}

package/i18n/locales/fr.json

@@ -0,0 +1,24 @@
+{
+  "common": {
+    "or": "ou",
+    "error": {
+      "title": "Page non trouvée",
+      "description": "Nous sommes désolés, mais la page que vous cherchez n'existe pas."
+    }
+  },
+  "docs": {
+    "copy": {
+      "page": "Copier la page",
+      "options": "Plus d'options de copie",
+      "link": "Copier le lien Markdown",
+      "view": "Voir en Markdown",
+      "gpt": "Ouvrir dans ChatGPT",
+      "claude": "Ouvrir dans Claude"
+    },
+    "framework": "Framework",
+    "links": "Communauté",
+    "toc": "Sur cette page",
+    "report": "Signaler un problème",
+    "edit": "Éditer cette page"
+  }
+}

package/i18n/locales/he.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/hi.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/hy.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": "Խմբագրել այս էջը"
+  }
+}