@gsa-tts/graymatter-ui 0.3.17 → 0.3.19

package/package.json

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

package/src/components/ApiDocSubNavMenu.svelte

@@ -148,9 +148,9 @@
       parent: SubNavItem | null
     ): SubNavItem | null {
       for (const it of items) {
-        if (it.id === item.id) return parent ?? it;
-        if (it.children) {
-          const found = search(it.children, parent ?? it);
+        if (it.id === item.id) return parent || it;
+        if (it.children && it.children.length > 0) {
+          const found = search(it.children, it);
           if (found) return found;
         }
       }
@@ -179,6 +179,7 @@
 
   let currentSelectedId = $state<string | null>(null);
   let hydrated = $state(false);
+  let pageLoadComplete = $state(false);
 
   const effectiveSelectedId = $derived(() => {
     if (!hydrated || !data) return null;
@@ -195,28 +196,28 @@
       }
     }
 
-    // Second priority: sessionStorage
+    // Second priority: Check if we have a persisted selectedId from sessionStorage
     if (typeof window !== 'undefined') {
       const storedId = sessionStorage.getItem('subNav-selectedId');
       if (storedId) {
         try {
           const parsedId = JSON.parse(storedId);
-          if (parsedId && parsedId !== 'null' && parsedId !== '') {
-            const targetItem = findItemById(data, parsedId);
-            if (targetItem) {
-              return targetItem.id;
-            }
+          const targetItem = findItemById(data, parsedId);
+          if (targetItem) {
+            return parsedId;
           }
-        } catch (e) {
-          console.log('[SubNavMenu] Error parsing stored ID:', e);
+        } catch {
+          // Invalid JSON, ignore
         }
       }
     }
 
-    // Third priority: first item
-    const firstItem = findFirstItem(data);
-    if (firstItem && firstItem.title) {
-      return firstItem.id;
+    // Fallback: use first item when no other selection method works
+    if (pageLoadComplete) {
+      const firstItem = findFirstItem(data);
+      if (firstItem && firstItem.title) {
+        return firstItem.id;
+      }
     }
 
     return null;
@@ -226,6 +227,27 @@
   $effect(() => {
     if (effectiveSelectedId() && effectiveSelectedId() !== currentSelectedId) {
       currentSelectedId = effectiveSelectedId();
+
+      // When restoring from sessionStorage, also restore the correct header
+      // 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');
+
+        if (isApiDocumentationPage) {
+          const restoredItem = findItemById(data, effectiveSelectedId()!);
+          if (restoredItem) {
+            const topLevel =
+              findTopLevelParent(restoredItem, data) || restoredItem;
+            import('@gsa-tts/graymatter-ui/stores/navigationStore')
+              .then(({ selectedSubNavItemTitle }) => {
+                selectedSubNavItemTitle.set(topLevel.title || '');
+              })
+              .catch();
+          }
+        }
+      }
     }
   });
 
@@ -234,53 +256,46 @@
 
     if (!data) return;
 
-    // Handle header updates and scrolling
-    const targetItem = currentSelectedId
-      ? findItemById(data, currentSelectedId)
-      : null;
-    if (targetItem) {
-      // Always resolve top-level parent from data
-      const topLevel = findTopLevelParent(targetItem, data) || targetItem;
-      import('@gsa-tts/graymatter-ui/stores/navigationStore')
-        .then(({ selectedSubNavItemTitle }) => {
-          selectedSubNavItemTitle.set(topLevel.title || '');
-          if (typeof window !== 'undefined') {
-            sessionStorage.setItem(
-              'subNav-selectedId',
-              JSON.stringify(targetItem.id)
-            );
-            sessionStorage.setItem(
-              'subNav-topLevelId',
-              JSON.stringify(topLevel.id)
-            );
-            sessionStorage.setItem(
-              'subNav-topLevelTitle',
-              JSON.stringify(topLevel.title || '')
-            );
-          }
-        })
-        .catch();
-
-      // Handle scrolling if we have a URL hash
-      if (targetItem.href && targetItem.href.includes('#')) {
-        const hash = targetItem.href.split('#')[1];
-        if (hash) {
-          setTimeout(() => scrollToAnchorWithOffset(hash), 100);
+    // 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');
+
+      // 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');
+
+        // If we came from a different page, clear sessionStorage to reset to initial values
+        if (isFromDifferentPage) {
+          sessionStorage.removeItem('subNav-selectedId');
+          sessionStorage.removeItem('subNav-selectedTitle');
+          sessionStorage.removeItem('subNav-topLevelId');
+          sessionStorage.removeItem('subNav-topLevelTitle');
         }
       }
 
-      // Always dispatch sectionVisible with top-level parent
-      if (topLevel.title && typeof window !== 'undefined') {
-        window.dispatchEvent(
-          new CustomEvent('sectionVisible', {
-            detail: {
-              title: topLevel.title,
-              id: topLevel.id,
-            },
-          })
-        );
+      // Clean up any leftover sessionStorage items
+      sessionStorage.removeItem('__subNavPageLoaded');
+    }
+
+    // Reset currentSelectedId to ensure clean state
+    currentSelectedId = null;
+
+    // Handle scrolling if we have a URL hash
+    const targetItem = currentSelectedId
+      ? findItemById(data, currentSelectedId)
+      : null;
+    if (targetItem && targetItem.href && targetItem.href.includes('#')) {
+      const hash = targetItem.href.split('#')[1];
+      if (hash) {
+        setTimeout(() => scrollToAnchorWithOffset(hash), 100);
       }
     }
+
+    // Mark page load as complete
+    pageLoadComplete = true;
     subNavReady.set(true);
   });
 
@@ -293,22 +308,17 @@
     }
     currentSelectedId = item.id;
     const topLevel = findTopLevelParent(item, data) || item;
+
     import('@gsa-tts/graymatter-ui/stores/navigationStore')
       .then(({ selectedSubNavItemTitle }) => {
         selectedSubNavItemTitle.set(topLevel.title || '');
-        if (typeof window !== 'undefined') {
-          sessionStorage.setItem('subNav-selectedId', JSON.stringify(item.id));
-          sessionStorage.setItem(
-            'subNav-topLevelId',
-            JSON.stringify(topLevel.id)
-          );
-          sessionStorage.setItem(
-            'subNav-topLevelTitle',
-            JSON.stringify(topLevel.title || '')
-          );
-        }
       })
       .catch();
+
+    // Save selectedId to sessionStorage for persistence
+    if (typeof window !== 'undefined') {
+      sessionStorage.setItem('subNav-selectedId', JSON.stringify(item.id));
+    }
     if (typeof window !== 'undefined') {
       if (item.href && item.href.includes('#')) {
         const hash = item.href.split('#')[1];

package/src/components/DesktopSideNav.svelte

@@ -19,7 +19,6 @@
   import ApiIcon from './icons/ApiIcon.svelte';
   import MenuIcon from './icons/MenuIcon.svelte';
   import ProfileMenu from './ProfileMenu.svelte';
-  import { getAppUrls } from '../utils/getAppUrls';
   // import HelpIcon from './icons/HelpIcon.svelte';
 
   const {
@@ -35,12 +34,6 @@
     discoverUrl,
   } = $props();
 
-  // Only call getAppUrls if not all URLs are provided via props
-  const urls =
-    apiUrl && chatUrl && consoleUrl && discoverUrl
-      ? { api: '#', chat: '#', console: '#', discover: '#' }
-      : getAppUrls();
-
   let hydrated = false;
   let navContainer: HTMLDivElement;
   let hoveredItem = $state<string | null>(null);
@@ -332,7 +325,7 @@
         <div class="nav-items" part="nav-items">
           {#if !hideDiscover}
             <a
-              href={discoverUrl || urls.discover}
+              href={discoverUrl || '#'}
               class="nav-item discover-item"
               class:selected={isNavSelected('discover')}
               class:hovered={isNavHovered('discover')}
@@ -356,7 +349,7 @@
             </a>
           {/if}
           <a
-            href={chatUrl || urls.chat}
+            href={chatUrl || '#'}
             class="nav-item chat-item"
             class:selected={isNavSelected('chat')}
             class:hovered={isNavHovered('chat')}
@@ -380,7 +373,7 @@
           </a>
 
           <a
-            href={consoleUrl || urls.console}
+            href={consoleUrl || '#'}
             class="nav-item console-item"
             class:selected={isNavSelected('console')}
             class:hovered={isNavHovered('console')}
@@ -404,7 +397,7 @@
           </a>
 
           <a
-            href={apiUrl || urls.api}
+            href={apiUrl || '#'}
             class="nav-item api-item"
             class:selected={isNavSelected('api')}
             class:hovered={isNavHovered('api')}

package/src/components/MobileBottomNav.svelte

@@ -5,7 +5,6 @@
   import ChatIcon from './icons/ChatIcon.svelte';
   import ConsoleIcon from './icons/ConsoleIcon.svelte';
   import ApiIcon from './icons/ApiIcon.svelte';
-  import { getAppUrls } from '../utils/getAppUrls';
   import slugify from 'slugify';
 
   let {
@@ -29,27 +28,21 @@
     discoverUrl?: string;
   } = $props();
 
-  // Only call getAppUrls if not all URLs are provided via props
-  const urls =
-    apiUrl && chatUrl && consoleUrl && discoverUrl
-      ? { api: '#', chat: '#', console: '#', discover: '#' }
-      : getAppUrls();
-
   const allNavItems = [
     {
       id: 'discover',
       label: 'Discover',
       icon: DiscoverIcon,
-      href: discoverUrl || urls.discover,
+      href: discoverUrl || '#',
     },
-    { id: 'chat', label: 'Chat', icon: ChatIcon, href: chatUrl || urls.chat },
+    { id: 'chat', label: 'Chat', icon: ChatIcon, href: chatUrl || '#' },
     {
       id: 'console',
       label: 'Console',
       icon: ConsoleIcon,
-      href: consoleUrl || urls.console,
+      href: consoleUrl || '#',
     },
-    { id: 'api', label: 'API', icon: ApiIcon, href: apiUrl || urls.api },
+    { id: 'api', label: 'API', icon: ApiIcon, href: apiUrl || '#' },
   ] as const;
 
   // Filter out discover item if hideDiscover is true

package/src/layouts/GlobalAppLayout.astro

@@ -8,6 +8,7 @@ import MobileBottomNav from '../components/MobileBottomNav.svelte';
 import MobileSideMenu from '../components/MobileSideMenu.svelte';
 import Logo from '../components/Logo.svelte';
 import { siteName } from '../constants';
+import { getAppUrls } from '../utils/getAppUrls';
 
 const {
   componentOptions = {},
@@ -21,6 +22,8 @@ const {
   description,
   openGraphImage,
 } = Astro.props;
+
+const { api, chat, console, discover } = getAppUrls();
 ---
 
 <BaseLayout title={pageTitle} {gtmID} {description} {openGraphImage}>
@@ -33,6 +36,10 @@ const {
           ssrSelectedItem={ssrSelectedItem}
           {showAppIcons}
           {profileMenuData}
+          apiUrl={api}
+          chatUrl={chat}
+          consoleUrl={console}
+          discoverUrl={discover}
         >
           <slot name="sub-nav" />
         </DesktopSideNav>
@@ -54,11 +61,22 @@ const {
         {profileMenuData}
         {logoLinkUrl}
         {logoLinkLabel}
+        apiUrl={api}
+        chatUrl={chat}
+        consoleUrl={console}
+        discoverUrl={discover}
       />
       <MobileSideMenu client:load {logoLinkUrl} {logoLinkLabel}>
         <slot name="sub-nav" />
       </MobileSideMenu>
-      <MobileBottomNav client:load {showAppIcons} />
+      <MobileBottomNav
+        client:load
+        {showAppIcons}
+        apiUrl={api}
+        chatUrl={chat}
+        consoleUrl={console}
+        discoverUrl={discover}
+      />
     </nav>
 
     <!-- Fixed Logo (Desktop only) -->

package/src/utils/getAppUrls.ts

@@ -1,11 +1,23 @@
 import { getUrlFromBase } from '@gsa-tts/graymatter-ui/helpers/url.js';
 
+/**
+ * Logs a warning message when an environment variable is missing.
+ *
+ * @param name - The name of the missing environment variable
+ * @param value - The value of the environment variable (should be undefined)
+ */
 function warnIfMissing(name: string, value: string | undefined) {
   if (!value) {
     console.warn(`[getAppUrls] Environment variable for ${name} is missing!`);
   }
 }
 
+/**
+ * Checks if a URL is absolute (starts with protocol like http:// or https://).
+ *
+ * @param url - The URL string to check
+ * @returns True if the URL is absolute, false otherwise
+ */
 function isAbsoluteUrl(url: string): boolean {
   try {
     new URL(url);
@@ -15,6 +27,24 @@ function isAbsoluteUrl(url: string): boolean {
   }
 }
 
+/**
+ * Processes a URL string, handling both absolute and relative URLs.
+ *
+ * If the URL is undefined, returns the fallback. If it's absolute (starts with protocol),
+ * returns it as-is. If it's relative, processes it through `getUrlFromBase()` to create
+ * a full URL.
+ *
+ * @param url - The URL string to process (can be undefined)
+ * @param fallback - The fallback URL to use if the input URL is undefined
+ * @returns The processed URL string (can be absolute URL or relative path)
+ *
+ * @example
+ * ```typescript
+ * processUrl('https://example.com', '/fallback'); // "https://example.com"
+ * processUrl('/api/docs', '/fallback'); // "/api/docs" (processed by getUrlFromBase)
+ * processUrl(undefined, '/fallback'); // "/fallback"
+ * ```
+ */
 function processUrl(url: string | undefined, fallback: string): string {
   if (!url) {
     return fallback;
@@ -27,6 +57,60 @@ function processUrl(url: string | undefined, fallback: string): string {
   return getUrlFromBase(url);
 }
 
+/**
+ * Retrieves application URLs/paths from environment variables with fallback support.
+ *
+ * This utility function processes environment variables to provide URLs or paths for different
+ * application sections (chat, console, API, discover). It supports both absolute URLs
+ * and relative paths, with intelligent fallback handling.
+ *
+ * @param envArg - Optional environment object to use instead of `import.meta.env`.
+ *                 Useful for testing or when you want to override environment variables.
+ *                 If not provided, uses Vite's `import.meta.env`.
+ *
+ * @returns An object containing processed URLs/paths for each application section:
+ *   - `chat`: Chat application URL or path
+ *   - `console`: Console application URL or path
+ *   - `api`: API documentation URL or path
+ *   - `discover`: Discover page URL or path
+ *
+ * @example
+ * ```typescript
+ * // Using default environment variables
+ * const urls = getAppUrls();
+ * console.log(urls.chat); // "#" (fallback) or "https://chat.example.com" (URL)
+ *
+ * // Using custom environment object (useful for testing)
+ * const urls = getAppUrls({
+ *   PUBLIC_CHAT_URL: 'https://chat.dev/',
+ *   PUBLIC_CONSOLE_URL: 'https://console.dev/',
+ *   PUBLIC_API_URL: 'https://api.dev/docs',
+ *   PUBLIC_DISCOVER_URL: 'https://discover.dev/'
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Environment variables (.env file)
+ * PUBLIC_CHAT_URL=https://chat.example.com
+ * PUBLIC_CONSOLE_URL=https://console.example.com
+ * PUBLIC_API_URL=/api/documentation
+ * PUBLIC_DISCOVER_URL=https://discover.example.com
+ *
+ * // Usage in code
+ * const { chat, console, api, discover } = getAppUrls();
+ * ```
+ *
+ * @remarks
+ * - URLs are processed through `processUrl()` which handles both absolute and relative URLs
+ * - Relative URLs are processed through `getUrlFromBase()` to create full URLs
+ * - Missing environment variables result in fallback values (`#` for most, `/api/documentation` for API)
+ * - Warnings are logged in development when environment variables are missing
+ * - The function is designed to work with Vite's `import.meta.env` system
+ *
+ * @see {@link processUrl} - URL processing logic
+ * @see {@link getUrlFromBase} - Base URL resolution
+ */
 export function getAppUrls(envArg?: Record<string, string | undefined>) {
   const env = envArg || import.meta.env;
   const fallback = '#';