@uxfront/layer-docs 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,54 @@
 # @uxfront/layer-docs
 
-## 0.1.2
+## 0.2.1
+
+### Patch Changes
+
+- Stop the optional `posthog-js` peer from killing the client bundle of every consumer that omits it.
+
+  `app/plugins/posthog.client.ts` imported `posthog-js` statically at module scope while declaring it an **optional** `peerDependency`. Rollup has no module to resolve for a consumer that skipped the optional peer, so it emits the specifier as a module-scope throw:
+
+  ```js
+  const HB = {};
+  throw new Error('Could not resolve "posthog-js" imported by "@uxfront/layer-docs".');
+  ```
+
+  That throw runs on evaluation, before the plugin body — so neither the `analytics.enabled` guard nor the `posthog.key` guard ever executed, and the failure was not confined to analytics. The whole client entry died with it: **the site did not hydrate at all**. Every page served as a dead static document — theme toggle stuck on its loading skeleton, framework tabs inert, no client-side routing, `localStorage` never written — with one console error per route as the only signal. Present in `0.1.0`, `0.1.1` and `0.2.0`.
+
+  `posthog-js` is now imported dynamically, inside the branch that has already confirmed analytics is enabled and a key is provisioned. The unresolvable specifier moves out of the client entry into its own lazy chunk that a consumer without the peer never evaluates — it is emitted, prefetched at most, and never run. The import is also wrapped, which keeps the failure proportional to what failed: a missing or broken module degrades to a console warning and no analytics, instead of a dead app.
+
+  `modules/optimizeDeps` carried the same assumption from the other direction — it named `posthog-js` in `optimizeDeps.include` unconditionally, which is a hard dev-server error when the package is not installed. The hint is now added only when the dependency actually resolves.
+
+  Consumers who do not use PostHog need no changes and should upgrade. Consumers who do use it are unaffected: `$posthog()` is provided exactly as before once the client initialises.
+
+## 0.2.0
+
+### Minor Changes
+
+- Absorb documentation-site plumbing that consumers were re-declaring by hand.
+
+  - `defineDocsCollections(sections, options)` gains `{ sitemap?, changelog? }`. With
+    `sitemap: true` the landing and docs collections carry `defineSitemapSchema()`;
+    with `changelog: true` a `changelog` collection is registered over
+    `changelog/*.md`. Both default to `false`, so existing single-argument calls are
+    unchanged. Per-locale collections are now gated on `locales.length > 0` rather
+    than the array's mere presence.
+  - 30 additional locales ship with the layer (ar, be, bn, ca, ckb, cs, da, de, el,
+    et, fr, he, hi, hy, it, ja, kk, km, ko, ky, lb, ms, nb, pl, ru, sl, sv, uk, ur,
+    vi), each complete against `en.json`.
+  - `nuxt.schema.ts` ships with the layer, so the Content Studio preview schema for
+    `app.config.ts` is described once instead of per consumer.
+  - New `modules/optimizeDeps` module pre-bundles the layer's own heavier runtime
+    dependencies; registered automatically.
+  - New `DocsAsideLeftTop` / `DocsFrameworkSelect` render a persistent framework
+    selector above the sidebar navigation, and `GradientPageHero` puts `UPageHero`
+    on `MorphingGradientBackground`. Both render only when the consumer opts in.
+
+  **Breaking-ish:** `useFramework()` no longer ships a built-in React/Vue/Vanilla
+  default list. `frameworks` is now `appConfig.docsTheme.frameworks ?? []`, making
+  app config the single source of truth. Sites that relied on the implicit default
+  must declare `docsTheme.frameworks` in their own `app.config.ts`; `FrameworkSwitcher`
+  renders no tab bar when the list is empty.
 
 ### Patch Changes
 
@@ -10,8 +58,16 @@
   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.
+  under `0.1.0`, the release it actually shipped in.
+
+Note: `0.2.0` was versioned by a hand `chore: bump version` commit that bypassed
+`changeset version`, so it published with no changelog entry at all — the tarball
+topped out at a `## 0.1.2` heading for a version that was versioned but never
+published. The entry above is the accurate, reconstructed record of what `0.2.0`
+actually contains, and the changelog-only correction previously filed under
+`0.1.2` is folded in here because `0.2.0` is the release it shipped in. Every
+heading in this file now corresponds to a version that exists on the registry.
+Second occurrence of UXF-67; see UXF-168.
 
 ## 0.1.1
 

package/app/plugins/posthog.client.ts

@@ -1,15 +1,14 @@
 import type { ConfigDefaults } from "posthog-js";
-import posthog from "posthog-js";
 import { defineNuxtPlugin } from "#app";
 
-export default defineNuxtPlugin(() => {
+export default defineNuxtPlugin(async () => {
   if (import.meta.dev) {
-    return;
+    return {};
   }
 
   // Consumers opt out via `app.config` (`analytics.enabled: false`).
   if (!useAppConfig().analytics?.enabled) {
-    return;
+    return {};
   }
 
   const runtimeConfig = useRuntimeConfig();
@@ -17,7 +16,27 @@ export default defineNuxtPlugin(() => {
   // 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;
+    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, {

package/modules/optimizeDeps.ts

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { defineNuxtModule, extendViteConfig } from "@nuxt/kit";
 
 /**
@@ -13,16 +14,32 @@ export default defineNuxtModule({
   meta: {
     name: "optimize-deps",
   },
-  setup() {
+  setup(_options, nuxt) {
+    const include = ["@nuxt/content > slugify", "@vueuse/core", "motion-v"];
+
+    // `posthog-js` is an OPTIONAL peer. Naming an uninstalled package in
+    // `optimizeDeps.include` is a hard dev-server error, so hint it only when
+    // the consumer actually has it.
+    if (canResolve("posthog-js", nuxt.options.rootDir)) {
+      include.push("posthog-js");
+    }
+
     extendViteConfig((config) => {
       config.optimizeDeps ||= {};
       config.optimizeDeps.include ||= [];
-      config.optimizeDeps.include.push(
-        "@nuxt/content > slugify",
-        "@vueuse/core",
-        "motion-v",
-        "posthog-js",
-      );
+      config.optimizeDeps.include.push(...include);
     });
   },
 });
+
+function canResolve(id: string, fromDir: string): boolean {
+  for (const parent of [`${fromDir}/`, import.meta.url]) {
+    try {
+      createRequire(parent).resolve(id);
+      return true;
+    } catch {
+      // try the next resolution root
+    }
+  }
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxfront/layer-docs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Neutral, brandable Nuxt-layer documentation theme. Consumers extend it and supply their own branding, content and section topology.",
   "keywords": [
     "docs",