@f5-sales-demo/docs-theme 4.11.7 → 4.13.0

package/src/shared/contract.mjs

@@ -0,0 +1,110 @@
+export const ROOT = 'https://f5-sales-demo.github.io/shared/';
+export const CONTRACT = 'v1';
+const hash = /^[a-f0-9]{64}$/;
+export function validateAsset(asset) {
+  if (!asset || !hash.test(asset.sha256) || !Number.isSafeInteger(asset.bytes) || asset.bytes < 1) {
+    throw new Error('Invalid shared asset receipt');
+  }
+  const url = new URL(asset.url);
+  if (
+    url.href !== `${ROOT}assets/${asset.sha256}.${asset.extension}` ||
+    !/^(css|js|json|woff2|svg|png|txt)$/.test(asset.extension)
+  ) {
+    throw new Error('Shared asset must use its canonical content-addressed root URL');
+  }
+  return asset;
+}
+export function validatePointer(pointer) {
+  if (pointer?.contract !== CONTRACT) throw new Error('Unsupported shared contract');
+  const release = pointer.release;
+  if (
+    !release ||
+    !hash.test(release.sha256) ||
+    !Number.isSafeInteger(release.bytes) ||
+    release.bytes < 1 ||
+    release.url !== `${ROOT}v1/releases/${release.sha256}.json`
+  )
+    throw new Error('Invalid shared release pointer');
+  return pointer;
+}
+export function validateManifest(manifest) {
+  if (manifest?.contract !== CONTRACT || !manifest.assets || typeof manifest.assets !== 'object')
+    throw new Error('Unsupported shared manifest');
+  for (const required of ['css', 'runtime', 'data', 'logo', 'favicon']) {
+    if (!manifest.assets[required]) throw new Error(`Missing shared asset: ${required}`);
+  }
+  const types = { css: 'css', runtime: 'js', data: 'json', logo: 'svg', favicon: 'svg' };
+  for (const [name, asset] of Object.entries(manifest.assets)) {
+    validateAsset(asset);
+    if (types[name] && asset.extension !== types[name]) throw new Error(`Incorrect shared asset type: ${name}`);
+  }
+  return manifest;
+}
+export function validateConsumer(consumer) {
+  if (
+    consumer?.contract !== CONTRACT ||
+    !/^f5-sales-demo\/[a-z0-9_.-]+$/.test(consumer.repository) ||
+    !/^\/(?:[a-zA-Z0-9_.-]+\/)*$/.test(consumer.documentBase) ||
+    typeof consumer.locale !== 'string' ||
+    !consumer.mounts ||
+    !['desktop', 'mobile'].every(
+      (key) => typeof consumer.mounts[key] === 'string' && /^#[a-z][a-z0-9-]*$/.test(consumer.mounts[key]),
+    )
+  ) {
+    throw new Error('Invalid shared consumer contract');
+  }
+  return consumer;
+}
+export function validateData(data) {
+  if (
+    !Array.isArray(data?.menu?.items) ||
+    !data.menu.items.length ||
+    !Array.isArray(data.searchSources) ||
+    !data.routing
+  )
+    throw new Error('Invalid shared menu data');
+  const labels = new Set();
+  const destinations = new Set();
+  const visit = (value) => {
+    if (!value || typeof value !== 'object') return;
+    for (const [key, child] of Object.entries(value)) {
+      if (key === 'href') {
+        const url = new URL(child);
+        if (url.protocol !== 'https:' || url.username || url.password)
+          throw new Error('Menu destinations require public HTTPS URLs');
+      } else if (/translations$/i.test(key)) {
+        if (
+          !child ||
+          typeof child !== 'object' ||
+          Object.values(child).some((text) => typeof text !== 'string' || !text.trim())
+        )
+          throw new Error('Invalid supplied translation');
+      } else visit(child);
+    }
+  };
+  visit(data.menu);
+  for (const item of data.menu.items) {
+    if (!item.label?.trim() || labels.has(item.label)) throw new Error('Duplicate or missing menu label');
+    labels.add(item.label);
+    for (const category of item.content?.categories || []) {
+      const links = new Set();
+      for (const link of category.items) {
+        if (!link.label?.trim() || links.has(link.href)) throw new Error('Duplicate or missing menu entry');
+        links.add(link.href);
+        if (destinations.has(link.href)) throw new Error('Duplicate global menu destination');
+        destinations.add(link.href);
+      }
+    }
+  }
+  const sources = new Set();
+  for (const source of data.searchSources) {
+    if (!source.repo || !source.label || sources.has(source.repo))
+      throw new Error('Duplicate or missing Search source');
+    sources.add(source.repo);
+  }
+  for (const key of ['locales', 'unlocalized', 'englishOnly']) {
+    if (!Array.isArray(data.routing[key]) || data.routing[key].some((value) => typeof value !== 'string'))
+      throw new Error('Invalid locale routing');
+  }
+  return data;
+}

package/src/shared/localize.mjs

@@ -0,0 +1,15 @@
+export function langToSlug(lang) {
+  return lang.toLowerCase();
+}
+export function localizeEcosystemHref(href, locale) {
+  const routing = globalThis.F5SharedRoutingV1;
+  if (!routing?.locales.includes(locale)) return href;
+  const url = new URL(href, document.baseURI);
+  if (url.hostname !== 'f5-sales-demo.github.io') return href;
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (!parts.length || routing.locales.includes(parts[0]) || routing.unlocalized.includes(parts[0])) return href;
+  if (parts[1] && routing.locales.includes(parts[1])) return href;
+  parts.splice(1, 0, routing.englishOnly.includes(parts[0]) ? 'en' : locale);
+  url.pathname = `/${parts.join('/')}/`;
+  return url.href;
+}

package/src/shared/runtime.tsx

@@ -0,0 +1,124 @@
+import type { MegaMenuConfig } from '@f5-sales-demo/starlight-mega-menu';
+import MegaMenu from '@f5-sales-demo/starlight-mega-menu/components/MegaMenu.tsx';
+import MegaMenuMobile from '@f5-sales-demo/starlight-mega-menu/components/MegaMenuMobile.tsx';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { searchSource } from '../utils/search-source.ts';
+
+interface Consumer {
+  repository: string;
+  mounts: { desktop: string; mobile: string };
+}
+interface Asset {
+  url: string;
+}
+interface Release {
+  data: {
+    menu: MegaMenuConfig;
+    routing: { locales: string[]; unlocalized: string[]; englishOnly: string[] };
+    searchSources: Array<{ repo: string; label: string }>;
+  };
+  manifest: { assets: Record<string, Asset> };
+}
+interface Prepared {
+  commit(): void;
+  dispose(): void;
+}
+declare global {
+  interface Window {
+    F5SharedV1: Map<string, { prepare(consumer: Consumer, release: Release): Prepared }>;
+    F5SharedSearchV1: { mergeIndex: Array<{ bundlePath: string }> };
+  }
+  var F5SharedRoutingV1: Release['data']['routing'];
+}
+// All imports are bundled once by the publisher. No downstream React island is involved.
+window.F5SharedV1 ||= new Map();
+const registry = window.F5SharedV1;
+registry.set(import.meta.url, {
+  prepare(consumer: Consumer, release: Release) {
+    const desktop = document.querySelector(consumer.mounts.desktop);
+    const mobile = document.querySelector(consumer.mounts.mobile);
+    if (!desktop || !mobile) throw new Error('Missing ecosystem mount');
+    const desktopStage = document.createElement('div');
+    const mobileStage = document.createElement('div');
+    const roots = [createRoot(desktopStage), createRoot(mobileStage)];
+    globalThis.F5SharedRoutingV1 = release.data.routing;
+    flushSync(() => {
+      roots[0].render(<MegaMenu config={release.data.menu} />);
+      roots[1].render(<MegaMenuMobile config={release.data.menu} />);
+    });
+    let observer: MutationObserver;
+    const dismissPreferences = (event: KeyboardEvent) => {
+      const preferences = document.querySelector<HTMLDetailsElement>(
+        '.compact-preferences[open], .provider-local-nav[open]',
+      );
+      if (event.key === 'Escape' && preferences) {
+        preferences.open = false;
+        preferences.querySelector('summary')?.focus();
+      }
+    };
+    return {
+      commit() {
+        desktop.replaceChildren(desktopStage);
+        mobile.replaceChildren(mobileStage);
+        // Branding URLs switch only with the coordinated shell release.
+        for (const element of document.querySelectorAll<HTMLImageElement>('[data-f5-shared-brand]')) {
+          const asset = release.manifest.assets[element.dataset.f5SharedBrand || ''];
+          if (asset) element.src = asset.url;
+        }
+        const favicon = document.querySelector<HTMLLinkElement>('[data-f5-shared-favicon]');
+        if (favicon) favicon.href = release.manifest.assets.favicon.url;
+        const annotate = () => {
+          for (const link of document.querySelectorAll<HTMLAnchorElement>('.pagefind-ui__result-link')) {
+            const title = link.closest('.pagefind-ui__result-title');
+            if (!title || title.querySelector('.search-project-source')) continue;
+            const label = searchSource(link.href, release.data.searchSources);
+            if (!label) continue;
+            const source = document.createElement('span');
+            source.className = 'search-project-source';
+            source.textContent = label;
+            title.append(source);
+          }
+        };
+        observer = new MutationObserver(annotate);
+        observer.observe(document.body, { childList: true, subtree: true });
+        annotate();
+        // Pagefind remains the local Starlight implementation. Its merge bundles are supplied here.
+        const current = consumer.repository.split('/')[1];
+        window.F5SharedSearchV1 = {
+          mergeIndex: release.data.searchSources
+            .filter((source) => source.repo !== current)
+            .map((source) => ({
+              bundlePath: `https://f5-sales-demo.github.io/${source.repo === 'f5-sales-demo.github.io' ? '' : `${source.repo}/`}pagefind/`,
+            })),
+        };
+        document.addEventListener('keydown', dismissPreferences);
+        // Supply the focus trap missing in the archived mobile renderer.
+        document.addEventListener('keydown', trap);
+      },
+      dispose() {
+        for (const root of roots) root.unmount();
+        observer?.disconnect();
+        document.removeEventListener('keydown', dismissPreferences);
+        document.removeEventListener('keydown', trap);
+      },
+    };
+  },
+});
+function trap(event: KeyboardEvent) {
+  if (event.key !== 'Tab') return;
+  const dialog = document.querySelector<HTMLElement>('.smm-mobile-overlay');
+  if (!dialog) return;
+  const controls = Array.from(dialog.querySelectorAll<HTMLElement>('button, a, summary, [tabindex="0"]')).filter(
+    (element) => element.getClientRects().length,
+  );
+  const first = controls[0],
+    last = controls.at(-1);
+  if (event.shiftKey && (document.activeElement === first || document.activeElement === dialog)) {
+    event.preventDefault();
+    last?.focus();
+  } else if (!event.shiftKey && (document.activeElement === last || document.activeElement === dialog)) {
+    event.preventDefault();
+    first?.focus();
+  }
+}

package/src/shared/search-integration.mjs

@@ -0,0 +1,16 @@
+// Keep Starlight's Search and Pagefind implementation local; inject only release-owned federation.
+export function sharedSearchIntegration() {
+  return {
+    name: 'f5-shared-search',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!id.includes('/@astrojs/starlight/components/Search.astro')) return;
+      return code
+        .replace('...pagefindUserConfig,', '...pagefindUserConfig, ...(window.F5SharedSearchV1 || {}),')
+        .replace(
+          'const { PagefindUI } = await import',
+          'await window.F5SharedReadyV1; const { PagefindUI } = await import',
+        );
+    },
+  };
+}

package/src/shared/settings.mjs

@@ -0,0 +1,19 @@
+import baseline from './baseline.json' with { type: 'json' };
+
+export { baseline };
+export function sharedMode(repository = process.env.GITHUB_REPOSITORY || '') {
+  const requested = process.env.DOCS_SHARED_MODE || 'auto';
+  if (!['auto', 'local', 'publish', 'consume'].includes(requested)) throw new Error('Invalid DOCS_SHARED_MODE');
+  const root = repository === 'f5-sales-demo/f5-sales-demo.github.io';
+  const mode =
+    requested === 'auto'
+      ? root
+        ? 'publish'
+        : repository.startsWith('f5-sales-demo/')
+          ? 'consume'
+          : 'local'
+      : requested;
+  if ((mode === 'publish') !== root && mode !== 'local')
+    throw new Error('Only the landing repository publishes the shared tree');
+  return mode;
+}

package/src/utils/canada-sidebar-plugin.test.ts

@@ -25,3 +25,14 @@ describe('Canada-only sidebar override', () => {
     expect(configuredComponents('f5-sales-demo/multi-cloud-networking')).not.toHaveProperty('Sidebar');
   });
 });
+
+describe('Statistics sidebar override', () => {
+  it('selects the sidebar that restores the active reading path', () => {
+    expect(configuredComponents('f5-sales-demo/statistics').Sidebar).toBe(
+      '@f5-sales-demo/docs-theme/components/StatisticsSidebar.astro',
+    );
+  });
+  it('preserves unrelated repository sidebars', () => {
+    expect(configuredComponents('f5-sales-demo/statistics-extra')).not.toHaveProperty('Sidebar');
+  });
+});

package/src/utils/publication-profiles.test.ts

@@ -66,9 +66,9 @@ describe('Statistics publication', () => {
     });
     expect(repositoryPublicationProfile('statistics')?.favicon).toBeUndefined();
   });
-  it('preserves 13 existing routes and places Shell Scripts before Infrastructure', () => {
+  it('preserves existing routes and places Shell Scripts before Infrastructure', () => {
     const sidebar = publicationSidebar('f5-sales-demo/statistics', []);
-    expect(sidebar?.slice(0, 11)).toEqual([
+    expect(sidebar?.slice(0, 9)).toEqual([
       { slug: 'index' },
       { slug: 'access-logs' },
       { slug: 'service-graph' },
@@ -78,9 +78,33 @@ describe('Statistics publication', () => {
       { slug: 'firewall-metrics' },
       { slug: 'security-events' },
       { slug: 'troubleshooting' },
-      { slug: 'api-catalog' },
-      { slug: 'setup' },
     ]);
+    const catalog = sidebar?.[9];
+    expect(catalog).toMatchObject({ label: 'Statistics APIs', collapsed: true });
+    if (!catalog || !('items' in catalog)) throw new Error('Statistics APIs must be a submenu');
+    const expected = [
+      'api-catalog',
+      'api-catalog/query-concepts',
+      'api-catalog/application-traffic',
+      'api-catalog/api-analytics',
+      'api-catalog/application-security',
+      'api-catalog/bot-defense',
+      'api-catalog/client-side-defense',
+      'api-catalog/device-data-intelligence',
+      'api-catalog/ddos-protection',
+      'api-catalog/dns',
+      'api-catalog/cdn',
+      'api-catalog/networking',
+      'api-catalog/kubernetes-storage',
+      'api-catalog/logs-events-alerts',
+      'api-catalog/synthetic-monitoring',
+      'api-catalog/billing-usage',
+    ];
+    expect(catalog.items.map((item) => ('slug' in item ? item.slug : ''))).toEqual(expected);
+    expect(catalog.items.every((item) => 'label' in item && item.label.split(/\s+/).length <= 3)).toBe(true);
+    expect(catalog.items[0]).toEqual({ label: 'Overview', slug: 'api-catalog' });
+    expect(catalog.items[1]).toEqual({ label: 'Query concepts', slug: 'api-catalog/query-concepts' });
+    expect(sidebar?.[10]).toEqual({ slug: 'setup' });
     expect(sidebar?.[11]).toEqual({ slug: 'shell-scripts' });
     expect(sidebar?.[12]).toEqual({
       label: 'Infrastructure',
@@ -95,8 +119,8 @@ describe('Statistics publication', () => {
           ? item.items.map((child) => ('slug' in child ? child.slug : ''))
           : [],
     );
-    expect(routes).toHaveLength(14);
-    expect(new Set(routes).size).toBe(14);
+    expect(routes).toHaveLength(29);
+    expect(new Set(routes).size).toBe(29);
   });
   it('preserves supplied fallback navigation for other repositories', () => {
     const fallback = [{ slug: 'index' }, { label: 'Existing', items: [{ slug: 'existing' }] }];

package/src/utils/publication-profiles.ts

@@ -24,7 +24,28 @@ export const publicationProfiles: Record<string, PublicationProfile> = {
       { slug: 'firewall-metrics' },
       { slug: 'security-events' },
       { slug: 'troubleshooting' },
-      { slug: 'api-catalog' },
+      {
+        label: 'Statistics APIs',
+        collapsed: true,
+        items: [
+          { label: 'Overview', slug: 'api-catalog' },
+          { label: 'Query concepts', slug: 'api-catalog/query-concepts' },
+          { label: 'Application traffic', slug: 'api-catalog/application-traffic' },
+          { label: 'API analytics', slug: 'api-catalog/api-analytics' },
+          { label: 'Application security', slug: 'api-catalog/application-security' },
+          { label: 'Bot defense', slug: 'api-catalog/bot-defense' },
+          { label: 'Client-side defense', slug: 'api-catalog/client-side-defense' },
+          { label: 'Device intelligence', slug: 'api-catalog/device-data-intelligence' },
+          { label: 'DDoS protection', slug: 'api-catalog/ddos-protection' },
+          { label: 'DNS', slug: 'api-catalog/dns' },
+          { label: 'CDN', slug: 'api-catalog/cdn' },
+          { label: 'Networking', slug: 'api-catalog/networking' },
+          { label: 'Kubernetes & storage', slug: 'api-catalog/kubernetes-storage' },
+          { label: 'Logs & events', slug: 'api-catalog/logs-events-alerts' },
+          { label: 'Synthetic monitoring', slug: 'api-catalog/synthetic-monitoring' },
+          { label: 'Billing & usage', slug: 'api-catalog/billing-usage' },
+        ],
+      },
       { slug: 'setup' },
       { slug: 'shell-scripts' },
       {

package/src/utils/search-sites.ts

@@ -1,32 +1,3 @@
-export const federatedSearchSites = [
-  { repo: 'docs-builder', label: 'Documentation builder' },
-  { repo: 'docs-theme', label: 'Shared documentation theme' },
-  { repo: 'f5-sales-demo.github.io', label: 'Sales demo portal' },
-  { repo: 'administration', label: 'Administration' },
-  { repo: 'nginx', label: 'NGINX One' },
-  { repo: 'observability', label: 'Observability' },
-  { repo: 'statistics', label: 'Statistics' },
-  { repo: 'was', label: 'Web App Scanning' },
-  { repo: 'multi-cloud-networking', label: 'Multi-Cloud Networking' },
-  { repo: 'canada', label: 'Canada topology' },
-  { repo: 'dns', label: 'DNS Management' },
-  { repo: 'cdn', label: 'Content Delivery Network' },
-  { repo: 'bot-standard', label: 'Bot Defense Standard' },
-  { repo: 'bot-advanced', label: 'Bot Defense Advanced' },
-  { repo: 'ddos', label: 'DDoS Mitigation' },
-  { repo: 'webapp-api-protection', label: 'Web App & API Protection' },
-  { repo: 'api-protection', label: 'API Protection' },
-  { repo: 'xcsh', label: 'xcsh' },
-  { repo: 'xcsh-action', label: 'xcsh GitHub Action' },
-  { repo: 'csd', label: 'Client-Side Defense' },
-  { repo: 'docs-icons', label: 'Icon packages' },
-  { repo: 'marketplace', label: 'xcsh marketplace' },
-  { repo: 'api-specs', label: 'API specifications' },
-  { repo: 'api-specs-enriched', label: 'Enriched API specifications' },
-  { repo: 'cdn-simulator', label: 'CDN simulator' },
-  { repo: 'origin-server', label: 'Origin server' },
-  { repo: 'traffic-generator', label: 'Traffic generator' },
-  { repo: 'demo-resources', label: 'Demo resource catalog' },
-  { repo: 'xcsh-chrome-extension', label: 'xcsh Chrome extension' },
-  { repo: 'console', label: 'Console catalog' },
-];
+// Explicit local builds may supply their own federation in createF5xcDocsConfig.
+export const localSearchSites: Array<{ repo: string; label: string }> = [];
+export const federatedSearchSites = localSearchSites;

package/src/utils/showcase-navigation.test.ts

@@ -1,34 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { expect, it } from 'vitest';
 import { defaultMegaMenuItems } from '../../config';
-import { localizeEcosystemHref } from './localize-ecosystem-href';
 
-describe('showcase navigation', () => {
-  it('uses the audience taxonomy without duplicate project destinations', () => {
-    expect(defaultMegaMenuItems.map((item) => item.label)).toEqual([
-      'Demos',
-      'Demo environment',
-      'Operations',
-      'Developer tools',
-      'Ecosystem',
-      'F5 services',
-    ]);
-    const links = defaultMegaMenuItems.flatMap((item) => item.content?.categories?.flatMap((c) => c.items) ?? []);
-    const urls = links.map((item) => item.href);
-    expect(new Set(urls).size).toBe(urls.length);
-    expect(urls).not.toContain('https://f5-sales-demo.github.io/');
-    expect(links.find((l) => l.href.includes('/api-protection/'))?.label).toBe('API Protection');
-    expect(links.find((l) => l.href.includes('/ddos/'))?.label).toBe('DDoS Mitigation');
-    expect(defaultMegaMenuItems[1].content?.footer?.label).toBe('Demo resource catalog');
-  });
-
-  it('keeps explicit English catalog destinations valid across locale selection', () => {
-    for (const locale of ['en', 'fr', 'ar']) {
-      expect(localizeEcosystemHref('https://f5-sales-demo.github.io/en/demos/', locale)).toBe(
-        'https://f5-sales-demo.github.io/en/demos/',
-      );
-      expect(localizeEcosystemHref('https://f5-sales-demo.github.io/en/ecosystem/', locale)).toBe(
-        'https://f5-sales-demo.github.io/en/ecosystem/',
-      );
-    }
-  });
-});
+it('leaves production menu content to the root publisher', () => expect(defaultMegaMenuItems).toEqual([]));

package/src/utils/statistics-navigation.test.ts

@@ -1,33 +1,9 @@
-import { describe, expect, it } from 'vitest';
-import { defaultMegaMenuItems, federatedSearchBundlePaths, federatedSearchSites } from '../../config';
+import { expect, it } from 'vitest';
 import { localizeEcosystemHref } from './localize-ecosystem-href';
 
-describe('Statistics discovery', () => {
-  it('lists Statistics beside monitoring tools exactly once', () => {
-    const networking = defaultMegaMenuItems.find((item) => item.label === 'Operations');
-    const category = networking?.content?.categories?.find((item) => item.title === 'Queries and administration');
-    const statistics = category?.items?.filter((item) => item.label === 'Statistics');
-    expect(statistics).toHaveLength(1);
-    expect(statistics?.[0]).toMatchObject({
-      href: 'https://f5-sales-demo.github.io/statistics/en/',
-      description: 'Query access logs, application metrics, and security telemetry through the API.',
-    });
-    expect(category?.items?.map((item) => item.label)).toEqual(['Statistics', 'Observability', 'Administration']);
-  });
-  it('adds Statistics to federated search and avoids self-index duplication', () => {
-    expect(federatedSearchSites.filter((item) => item.repo === 'statistics')).toHaveLength(1);
-    expect(federatedSearchBundlePaths('https://f5-sales-demo.github.io', '/')).toContain(
-      'https://f5-sales-demo.github.io/statistics/pagefind/',
+it('retains explicit English Statistics destinations', () => {
+  for (const locale of ['en', 'fr', 'ar'])
+    expect(localizeEcosystemHref('https://f5-sales-demo.github.io/statistics/en/', locale)).toBe(
+      'https://f5-sales-demo.github.io/statistics/en/',
     );
-    expect(federatedSearchBundlePaths('https://f5-sales-demo.github.io', '/statistics')).not.toContain(
-      'https://f5-sales-demo.github.io/statistics/pagefind/',
-    );
-  });
-  it('keeps the published English destination for every reader locale', () => {
-    for (const locale of ['en', 'fr', 'ja']) {
-      expect(localizeEcosystemHref('https://f5-sales-demo.github.io/statistics/en/', locale)).toBe(
-        'https://f5-sales-demo.github.io/statistics/en/',
-      );
-    }
-  });
 });