@f5-sales-demo/docs-theme 4.8.0 → 4.9.0

package/components/CanadaSidebar.astro

@@ -0,0 +1,77 @@
+---
+import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
+import SidebarRestorePoint from '@astrojs/starlight/components/SidebarRestorePoint.astro';
+
+const { sidebar } = Astro.locals.starlightRoute;
+---
+
+<SidebarPersister>
+  <ul class="canada-sidebar">
+    {sidebar.map((entry) => {
+      if (entry.type === 'link') {
+        return <li><a class="home-link" href={entry.href} aria-current={entry.isCurrent ? 'page' : undefined}>{entry.label}</a></li>;
+      }
+
+      const [overview, ...children] = entry.entries;
+      if (!overview || overview.type !== 'link') {
+        return <li><SidebarSublist sublist={[entry]} /></li>;
+      }
+      const active = overview.isCurrent || children.some((child) => child.type === 'link' && child.isCurrent);
+
+      return <li class="stage">
+        <a class="stage-link" href={overview.href} aria-current={overview.isCurrent ? 'page' : undefined}>{entry.label}</a>
+        <details open={active || !entry.collapsed}>
+          <summary aria-label={`Toggle ${entry.label} pages`} title={`Toggle ${entry.label} pages`}><span class="caret" aria-hidden="true"></span></summary>
+          <SidebarRestorePoint />
+          <SidebarSublist sublist={children} nested />
+        </details>
+      </li>;
+    })}
+  </ul>
+</SidebarPersister>
+
+<div class="md:sl-hidden"><MobileMenuFooter /></div>
+
+<style>
+  @layer starlight.core {
+    .canada-sidebar { list-style: none; margin: 0; padding: 0; }
+    .canada-sidebar > li + li { margin-top: 0.5rem; }
+    .stage { position: relative; }
+    .home-link, .stage-link {
+      display: block;
+      border-radius: 0.25rem;
+      color: var(--sl-color-gray-2);
+      line-height: 1.4;
+      padding: 0.3em 2.5rem 0.3em 0.5rem;
+      text-decoration: none;
+      font-size: var(--sl-text-sm);
+    }
+    .stage-link { color: var(--sl-color-white); font-weight: 600; }
+    .home-link:hover, .home-link:focus, .stage-link:hover, .stage-link:focus { color: var(--sl-color-white); }
+    a[aria-current='page'], a[aria-current='page']:hover, a[aria-current='page']:focus {
+      color: var(--sl-color-text-invert);
+      background-color: var(--sl-color-text-accent);
+      font-weight: 600;
+    }
+    summary {
+      position: absolute;
+      inset-block-start: 0;
+      inset-inline-end: 0;
+      display: grid;
+      place-items: center;
+      width: 2rem;
+      height: 2rem;
+      cursor: pointer;
+      border-radius: 0.25rem;
+      list-style: none;
+    }
+    summary::-webkit-details-marker { display: none; }
+    summary:hover, summary:focus-visible { color: var(--sl-color-white); background: var(--sl-color-gray-5); }
+    .caret { width: 0.55rem; height: 0.55rem; border-block-start: 2px solid currentColor; border-inline-end: 2px solid currentColor; transform: rotate(45deg); transition: transform 0.2s ease; }
+    details[open] .caret { transform: rotate(135deg); }
+    :global([dir='rtl']) .caret { transform: rotate(225deg); }
+    :global([dir='rtl']) details[open] .caret { transform: rotate(135deg); }
+  }
+</style>

package/config.ts

@@ -782,7 +782,7 @@ export function createF5xcDocsConfig(options: F5xcDocsConfigOptions = {}) {
     starlightMegaMenu({ items: megaMenuItems, mobileLabels }),
     starlightVideosPlugin(),
     starlightImageZoom(),
-    f5xcDocsTheme(),
+    f5xcDocsTheme(githubRepository),
     starlightScrollToTop({
       showTooltip: true,
       tooltipText: {

package/index.ts

@@ -1,7 +1,7 @@
 import type { StarlightPlugin } from '@astrojs/starlight/types';
 import { translations } from './src/i18n/translations.ts';
 
-export default function f5xcDocsTheme(): StarlightPlugin {
+export default function f5xcDocsTheme(repository = process.env.GITHUB_REPOSITORY || ''): StarlightPlugin {
   return {
     name: '@f5-sales-demo/docs-theme',
     hooks: {
@@ -29,7 +29,11 @@ export default function f5xcDocsTheme(): StarlightPlugin {
               ? {
                   Sidebar: '@f5-sales-demo/docs-theme/components/ProviderSidebar.astro',
                 }
-              : {}),
+              : repository === 'f5-sales-demo/canada'
+                ? {
+                    Sidebar: '@f5-sales-demo/docs-theme/components/CanadaSidebar.astro',
+                  }
+                : {}),
             Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
             EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
             Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f5-sales-demo/docs-theme",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "F5 Distributed Cloud branded Starlight documentation theme",
   "type": "module",
   "engines": {
@@ -43,6 +43,7 @@
     "./src/utils/localize-ecosystem-href.ts": "./src/utils/localize-ecosystem-href.ts",
     "./canonical-route-middleware": "./canonical-route-middleware.ts",
     "./components/ProviderSidebar.astro": "./components/ProviderSidebar.astro",
+    "./components/CanadaSidebar.astro": "./components/CanadaSidebar.astro",
     "./components/ProviderHeader.astro": "./components/ProviderHeader.astro",
     "./components/SharedHeader.astro": "./components/SharedHeader.astro",
     "./assets/canada-flag.svg": "./assets/canada-flag.svg",

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

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+import f5xcDocsTheme from '../../index';
+
+function configuredComponents(repository: string) {
+  const updateConfig = vi.fn();
+  const setup = f5xcDocsTheme(repository).hooks?.['config:setup'];
+  if (!setup) throw new Error('theme setup hook is missing');
+  setup({
+    config: { components: {} },
+    updateConfig,
+    addRouteMiddleware: vi.fn(),
+    logger: { info: vi.fn() },
+  } as never);
+  return updateConfig.mock.calls[0][0].components;
+}
+
+describe('Canada-only sidebar override', () => {
+  it('selects the linked stage sidebar for Canada', () => {
+    expect(configuredComponents('f5-sales-demo/canada').Sidebar).toBe(
+      '@f5-sales-demo/docs-theme/components/CanadaSidebar.astro',
+    );
+  });
+
+  it('leaves other repositories on their existing sidebar', () => {
+    expect(configuredComponents('f5-sales-demo/multi-cloud-networking')).not.toHaveProperty('Sidebar');
+  });
+});

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

@@ -19,21 +19,36 @@ describe('Canadian publication', () => {
 });
 
 describe('publication profile sidebar', () => {
-  it('makes the Canada article primary and keeps every existing reference URL', () => {
+  it('orders four linked stages and covers all 14 pages once', () => {
     const sidebar = publicationSidebar('f5-sales-demo/canada', []);
-    expect(sidebar?.slice(0, 2)).toEqual([{ slug: 'index' }, { slug: 'use-case' }]);
-    const reference = sidebar?.[2];
-    expect(reference).toMatchObject({ label: 'Reference', collapsed: true });
-    expect(JSON.stringify(reference)).toContain('architecture');
-    expect(JSON.stringify(reference)).toContain('verification');
-    expect(JSON.stringify(reference)).toContain('terraform');
-    expect(JSON.stringify(reference)).toContain('presentation');
-    expect(reference).toMatchObject({
-      items: expect.arrayContaining([expect.objectContaining({ label: 'Maintenance', collapsed: true })]),
+    expect(sidebar?.[0]).toEqual({ slug: 'index' });
+    const stages = sidebar?.slice(1) ?? [];
+    expect(stages.map((stage) => ('label' in stage ? stage.label : ''))).toEqual([
+      'Design',
+      'Deploy',
+      'Verify',
+      'Operate',
+    ]);
+    const expected = [
+      ['design', 'use-case', 'architecture'],
+      ['deploy', 'deployment', 'terraform'],
+      ['verify', 'presentation', 'verification'],
+      ['operate', 'troubleshooting', 'failover', 'teardown'],
+    ];
+    const routes = ['index'];
+    stages.forEach((stage, index) => {
+      expect(stage).toMatchObject({ collapsed: true });
+      if (!('items' in stage)) throw new Error('Canada stage must have items');
+      const stageRoutes = stage.items.map((item) => {
+        if (!('slug' in item)) throw new Error('Canada stage item must be a page');
+        return item.slug;
+      });
+      expect(stageRoutes).toEqual(expected[index]);
+      routes.push(...stageRoutes);
     });
-    for (const slug of ['deployment', 'failover', 'troubleshooting', 'teardown']) {
-      expect(JSON.stringify(reference)).toContain(`"${slug}"`);
-    }
+    expect(new Set(routes).size).toBe(14);
+    expect(routes).toHaveLength(14);
+    expect(stages.every((stage) => 'label' in stage && stage.label.split(/\s+/).length <= 3)).toBe(true);
   });
   it('preserves fallback navigation for every repository without a sidebar profile', () => {
     const fallback = [{ label: 'Existing', slug: 'en/existing' }];

package/src/utils/publication-profiles.ts

@@ -17,21 +17,25 @@ export const publicationProfiles: Record<string, PublicationProfile> = {
     favicon: '/assets/canada-favicon.svg',
     sidebar: [
       { slug: 'index' },
-      { slug: 'use-case' },
       {
-        label: 'Reference',
+        label: 'Design',
         collapsed: true,
-        items: [
-          { slug: 'architecture' },
-          { slug: 'verification' },
-          { slug: 'presentation' },
-          { slug: 'terraform' },
-          {
-            label: 'Maintenance',
-            collapsed: true,
-            items: [{ slug: 'deployment' }, { slug: 'failover' }, { slug: 'troubleshooting' }, { slug: 'teardown' }],
-          },
-        ],
+        items: [{ slug: 'design' }, { slug: 'use-case' }, { slug: 'architecture' }],
+      },
+      {
+        label: 'Deploy',
+        collapsed: true,
+        items: [{ slug: 'deploy' }, { slug: 'deployment' }, { slug: 'terraform' }],
+      },
+      {
+        label: 'Verify',
+        collapsed: true,
+        items: [{ slug: 'verify' }, { slug: 'presentation' }, { slug: 'verification' }],
+      },
+      {
+        label: 'Operate',
+        collapsed: true,
+        items: [{ slug: 'operate' }, { slug: 'troubleshooting' }, { slug: 'failover' }, { slug: 'teardown' }],
       },
     ],
   },