@gsa-tts/graymatter-ui 0.4.16 → 0.4.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsa-tts/graymatter-ui",
-  "version": "0.4.16",
+  "version": "0.4.19",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/components/ApiDocSubNavMenu.svelte

@@ -5,6 +5,13 @@
   import ApiDocSubNavList from './ApiDocSubNavList.svelte';
 
   const { data = null } = $props();
+  // TODO: remove legacy /api/documentation path once all consuming apps migrate
+  const API_DOC_PATHS = ['/api-documentation', '/api/documentation'];
+
+  function isApiDocumentationPath(path: string | null | undefined) {
+    if (!path) return false;
+    return API_DOC_PATHS.some(apiPath => path.includes(apiPath));
+  }
 
   const sections = $derived(() =>
     !Array.isArray(data) &&
@@ -180,6 +187,17 @@
   let currentSelectedId = $state<string | null>(null);
   let hydrated = $state(false);
   let pageLoadComplete = $state(false);
+  let scrollTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  function queueScrollToAnchor(hash: string, delay: number) {
+    if (scrollTimeoutId) {
+      clearTimeout(scrollTimeoutId);
+    }
+    scrollTimeoutId = setTimeout(() => {
+      scrollTimeoutId = null;
+      scrollToAnchorWithOffset(hash);
+    }, delay);
+  }
 
   const effectiveSelectedId = $derived(() => {
     if (!hydrated || !data) return null;
@@ -232,8 +250,7 @@
       // Only do this if we're on the API documentation page (where this component exists)
       if (data && effectiveSelectedId() && typeof window !== 'undefined') {
         const currentPath = window.location.pathname;
-        const isApiDocumentationPage =
-          currentPath.includes('/api/documentation');
+        const isApiDocumentationPage = isApiDocumentationPath(currentPath);
 
         if (isApiDocumentationPage) {
           const restoredItem = findItemById(data, effectiveSelectedId()!);
@@ -259,13 +276,13 @@
     // Check if we're navigating TO the documentation page (vs refreshing while on it)
     if (typeof window !== 'undefined') {
       const currentPath = window.location.pathname;
-      const isDocumentationPage = currentPath.includes('/api/documentation');
+      const isDocumentationPage = isApiDocumentationPath(currentPath);
 
       // If we're on the documentation page, check if we came from a different page
       if (isDocumentationPage) {
         const referrer = document.referrer;
         const isFromDifferentPage =
-          referrer && !referrer.includes('/api/documentation');
+          referrer && !isApiDocumentationPath(referrer);
 
         // If we came from a different page, clear sessionStorage to reset to initial values
         if (isFromDifferentPage) {
@@ -290,13 +307,20 @@
     if (targetItem && targetItem.href && targetItem.href.includes('#')) {
       const hash = targetItem.href.split('#')[1];
       if (hash) {
-        setTimeout(() => scrollToAnchorWithOffset(hash), 100);
+        queueScrollToAnchor(hash, 100);
       }
     }
 
     // Mark page load as complete
     pageLoadComplete = true;
     subNavReady.set(true);
+
+    return () => {
+      if (scrollTimeoutId) {
+        clearTimeout(scrollTimeoutId);
+        scrollTimeoutId = null;
+      }
+    };
   });
 
   function handleItemClick(event: Event, item: SubNavItem) {
@@ -326,9 +350,7 @@
           window.location.hash = hash;
           if (window.innerWidth > 640) {
             // Desktop: use delay for consistent timing
-            setTimeout(() => {
-              scrollToAnchorWithOffset(hash);
-            }, 350);
+            queueScrollToAnchor(hash, 350);
           } else {
             // Mobile: immediate scroll without delay
             window.dispatchEvent(
@@ -376,6 +398,7 @@
 
   // Utility: Scroll to anchor with header offset
   function scrollToAnchorWithOffset(anchorId: string) {
+    if (typeof document === 'undefined') return;
     const mainContent = document.getElementById('main-content');
     if (mainContent) {
       const anchor = mainContent.querySelector(

package/src/components/DesktopSideNav.svelte

@@ -1,9 +1,14 @@
 <script lang="ts">
   /**
-   * Controls which nav item is selected on initial server-side render (SSR) or first paint.
-   * - For the Discover page, set ssrSelectedItem="discover".
-   * - For other pages, set ssrSelectedItem to the corresponding nav key (e.g., "api", "chat", "console").
-   * - If not provided, the navigation will default to expanded/open on SSR.
+   * Initial selection for SSR/first paint.
+   * - Discover page: set ssrSelectedItem="discover".
+   * - Other pages: set ssrSelectedItem to the nav key (e.g., "api", "chat", "console").
+   * - Omit to default to expanded/open on SSR.
+   *
+   * controlledSelectedItem overrides the nav store after hydration.
+   * - Use for web component integrations where bundle/app stores can diverge.
+   * - In Svelte/SvelteKit apps, prefer NavigationInitializer and omit
+   *   controlledSelectedItem to keep store-driven behavior.
    */
   import { onMount } from 'svelte';
   import {
@@ -23,6 +28,7 @@
 
   const {
     ssrSelectedItem = undefined,
+    controlledSelectedItem = undefined,
     onNavToggle = undefined,
     onNavItemClick = undefined,
     showAppIcons = true,
@@ -79,8 +85,16 @@
     return hydrated ? hydratedValue : ssrValue;
   }
 
+  const selectedForUi = $derived(() => controlledSelectedItem ?? $selectedItem);
+  const ssrSelectedForUi = $derived(
+    () => controlledSelectedItem ?? ssrSelectedItem
+  );
+  const ssrSelected = $derived(() => ssrSelectedForUi());
+  const ssrIsDiscover = $derived(() => ssrSelected() === 'discover');
+  const isMenuDisabledForUi = $derived(() => selectedForUi() === 'discover');
+
   function isNavSelected(key: NavigationItem) {
-    return ssrOrHydrated($selectedItem === key, ssrSelectedItem === key);
+    return ssrOrHydrated(selectedForUi() === key, ssrSelectedForUi() === key);
   }
 
   function isNavHovered(key: string) {
@@ -88,22 +102,16 @@
   }
 
   const sideNavExpanded = $derived(() =>
-    ssrOrHydrated(
-      $isExpanded,
-      ssrSelectedItem ? ssrSelectedItem !== 'discover' : true
-    )
+    ssrOrHydrated($isExpanded, ssrSelected() ? !ssrIsDiscover() : true)
   );
   const menuBtnDisabled = $derived(() =>
     ssrOrHydrated(
-      $isMenuButtonDisabled,
-      ssrSelectedItem ? ssrSelectedItem === 'discover' : false
+      isMenuDisabledForUi(),
+      ssrSelected() ? ssrIsDiscover() : false
     )
   );
   const menuBtnOpen = $derived(() =>
-    ssrOrHydrated(
-      $isExpanded,
-      ssrSelectedItem ? ssrSelectedItem !== 'discover' : true
-    )
+    ssrOrHydrated($isExpanded, ssrSelected() ? !ssrIsDiscover() : true)
   );
   const menuBtnHovered = $derived(
     () => canHover && menuButtonHovered && !menuBtnDisabled()
@@ -138,7 +146,7 @@
           navigationStore.setExpanded(false);
         } else {
           // Switching to desktop: open navigation if on non-discover page
-          const currentItem = $selectedItem;
+          const currentItem = selectedForUi();
 
           if (currentItem && currentItem !== 'discover') {
             navigationStore.setExpanded(true);
@@ -220,7 +228,7 @@
   }
 
   function toggleNav() {
-    if ($isMenuButtonDisabled) return;
+    if (menuBtnDisabled()) return;
     navigationStore.toggleExpanded();
     onNavToggle?.({ expanded: $isExpanded });
   }
@@ -231,7 +239,9 @@
       sessionStorage.setItem('navigatingToMainNav', 'true');
     }
 
-    navigationStore.setSelectedItem(item);
+    if (controlledSelectedItem === undefined) {
+      navigationStore.setSelectedItem(item);
+    }
 
     // Clear header state for main navigation items (including discover)
     if (item !== 'discover') {

package/src/components/DesktopSideNav.webcomponent.svelte

@@ -10,6 +10,7 @@
   // Props for the web component
   let {
     ssrSelectedItem,
+    controlledSelectedItem,
     onNavToggle,
     onNavItemClick,
     showAppIcons = true,
@@ -25,6 +26,7 @@
 
 <DesktopSideNav
   {ssrSelectedItem}
+  {controlledSelectedItem}
   {onNavToggle}
   {onNavItemClick}
   {showAppIcons}

package/src/components/MobileBottomNav.svelte

@@ -14,6 +14,7 @@
     chatUrl,
     consoleUrl,
     discoverUrl,
+    controlledSelectedItem = undefined,
   }: {
     onNavItemClick?: (data: {
       item: NavigationItem;
@@ -25,8 +26,11 @@
     chatUrl?: string;
     consoleUrl?: string;
     discoverUrl?: string;
+    controlledSelectedItem?: NavigationItem;
   } = $props();
 
+  const selectedForUi = $derived(() => controlledSelectedItem ?? $selectedItem);
+
   const allNavItems = [
     {
       id: 'discover',
@@ -55,7 +59,9 @@
       sessionStorage.setItem('navigatingToMainNav', 'true');
     }
 
-    navigationStore.setSelectedItem(item);
+    if (controlledSelectedItem === undefined) {
+      navigationStore.setSelectedItem(item);
+    }
 
     // Clear header state for main navigation items (including discover)
     if (item !== 'discover') {
@@ -130,12 +136,12 @@
       <a
         href={navItem.href}
         class={`nav-item ${navItem.id}-item`}
-        class:active={$selectedItem === navItem.id}
+        class:active={selectedForUi() === navItem.id}
         onclick={() => handleNavItemClick(navItem.id)}
         part={`${navItem.id}-item`}
       >
         <div class="icon">
-          <navItem.icon isSelected={$selectedItem === navItem.id} />
+          <navItem.icon isSelected={selectedForUi() === navItem.id} />
         </div>
         <span class="label">{navItem.label}</span>
       </a>

package/src/components/MobileBottomNav.webcomponent.svelte

@@ -16,6 +16,7 @@
     chatUrl,
     consoleUrl,
     discoverUrl,
+    controlledSelectedItem,
   } = $props();
 </script>
 
@@ -27,4 +28,5 @@
   {chatUrl}
   {consoleUrl}
   {discoverUrl}
+  {controlledSelectedItem}
 />

package/src/utils/generateApiNavData.ts

@@ -82,7 +82,8 @@ function headingsToNavItems(
 
 // Generate navigation data dynamically from API documentation metadata
 export function generateApiDocumentationNavData(
-  apiDocs: ApiDocMetadata[]
+  apiDocs: ApiDocMetadata[],
+  basePath = '/api-documentation'
 ): SubNavData {
   // Sort by sortOrder
   const sortedDocs = [...apiDocs].sort((a, b) => a.sortOrder - b.sortOrder);
@@ -97,7 +98,7 @@ export function generateApiDocumentationNavData(
     return {
       id: doc.slug,
       title: doc.title,
-      href: `/api/documentation#${doc.slug}`,
+      href: `${basePath}#${doc.slug}`,
       children,
     };
   });