@gsa-tts/graymatter-ui 0.4.17 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsa-tts/graymatter-ui",
-  "version": "0.4.17",
+  "version": "0.5.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -53,13 +53,13 @@
     "@types/unist": "^3.0.3",
     "@uswds/compile": "1.2.2",
     "@vitest/coverage-istanbul": "^3.2.4",
-    "astro": "^5.13.7",
+    "astro": "^5.15.9",
     "astro-purgecss": "^5.2.2",
     "eslint": "^9.21.0",
     "gulp": "^5.0.0",
-    "svelte": "^5.35.4",
+    "svelte": "^5.53.5",
     "typescript": "5.7.3",
-    "vite": "^6.3.5",
+    "vite": "^6.4.1",
     "vitest": "^3.0.7",
     "@gsa-tts/graymatter-eslint": "0.0.2",
     "@gsa-tts/graymatter-typescript-config": "0.0.2",

package/src/components/ApiDocSubNavMenu.svelte

@@ -1,10 +1,10 @@
 <script lang="ts">
-  import { createEventDispatcher, onMount } from 'svelte';
+  import { createEventDispatcher } from 'svelte';
   import { subNavReady } from '../stores/subNavReadyStore';
   import type { SubNavData, SubNavItem } from '../types/subnav.ts';
   import ApiDocSubNavList from './ApiDocSubNavList.svelte';
 
-  const { data = null } = $props();
+  let { data = null } = $props();
   // TODO: remove legacy /api/documentation path once all consuming apps migrate
   const API_DOC_PATHS = ['/api-documentation', '/api/documentation'];
 
@@ -187,6 +187,18 @@
   let currentSelectedId = $state<string | null>(null);
   let hydrated = $state(false);
   let pageLoadComplete = $state(false);
+  let hasMounted = $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;
@@ -257,7 +269,10 @@
     }
   });
 
-  onMount(() => {
+  $effect(() => {
+    if (hasMounted) return;
+    hasMounted = true;
+
     hydrated = true;
 
     if (!data) return;
@@ -296,13 +311,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) {
@@ -332,9 +354,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(
@@ -382,6 +402,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/Button.svelte

@@ -28,6 +28,7 @@
     type?: 'button' | 'submit' | 'reset';
     onclick?: (event: MouseEvent) => void;
     class?: string;
+    children?: import('svelte').Snippet;
     [key: `data-${string}`]: string;
     [key: `aria-${string}`]: string;
   }
@@ -42,6 +43,7 @@
     size = 'medium',
     type = 'button',
     class: className = '',
+    children,
     // eslint-disable-next-line svelte/valid-compile
     ...props
   }: Props = $props();
@@ -71,11 +73,11 @@
 
 {#if href}
   <a class={mergedClasses()} {href} class:disabled {onclick} {...props}>
-    <slot />
+    {@render children?.()}
   </a>
 {:else}
   <button class={mergedClasses()} {type} {disabled} {onclick} {...props}>
-    <slot />
+    {@render children?.()}
   </button>
 {/if}
 

package/src/components/Button.webcomponent.svelte

@@ -16,17 +16,32 @@
   import Button from './Button.svelte';
 
   // Props for the web component
+  interface Props {
+    variant?: 'primary' | 'secondary' | 'unstyled';
+    theme?: 'default' | 'inverted';
+    href?: string;
+    disabled?: boolean;
+    size?: 'small' | 'medium' | 'large';
+    type?: 'button' | 'submit' | 'reset';
+    onclick?: (event: MouseEvent) => void;
+    class?: string;
+    children?: import('svelte').Snippet;
+    [key: `data-${string}`]: string;
+    [key: `aria-${string}`]: string;
+  }
+
   let {
     variant = 'primary',
     theme = 'default',
-    href = null,
+    href = undefined,
     disabled = false,
     size = 'medium',
     type = 'button',
     onclick,
     class: className = '',
+    children,
     ...props
-  } = $props();
+  }: Props = $props();
 </script>
 
 <Button
@@ -37,8 +52,7 @@
   {size}
   {type}
   {onclick}
+  {children}
   class={className}
   {...props}
->
-  <slot />
-</Button>
+></Button>

package/src/components/DesktopHeader.svelte

@@ -4,11 +4,10 @@
     isExpanded,
     selectedSubNavItemTitle,
   } from '../stores/navigationStore.js';
-  import { onMount } from 'svelte';
 
-  const { customHeaderText = '' } = $props();
+  let { customHeaderText = '' } = $props();
 
-  let isLayoutTransitioning = false;
+  let isLayoutTransitioning = $state(false);
 
   const showHeader = $derived(
     () =>
@@ -21,20 +20,19 @@
     () => customHeaderText || $selectedSubNavItemTitle
   );
 
-  onMount(() => {
+  $effect(() => {
+    if (typeof window === 'undefined') return;
     const handleSectionVisible = (event: Event) => {
-      if (typeof window !== 'undefined' && window.innerWidth <= 640) {
+      if (window.innerWidth <= 640) {
         return;
       }
       let topLevelTitle = null;
-      if (typeof window !== 'undefined') {
-        topLevelTitle = sessionStorage.getItem('subNav-topLevelTitle');
-        if (topLevelTitle) {
-          try {
-            topLevelTitle = JSON.parse(topLevelTitle);
-          } catch {
-            /* ignore parse error */
-          }
+      topLevelTitle = sessionStorage.getItem('subNav-topLevelTitle');
+      if (topLevelTitle) {
+        try {
+          topLevelTitle = JSON.parse(topLevelTitle);
+        } catch {
+          /* ignore parse error */
         }
       }
       if (typeof topLevelTitle === 'string' && topLevelTitle.trim() !== '') {

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 {
@@ -21,8 +26,9 @@
   import ProfileMenu from './ProfileMenu.svelte';
   import HelpIcon from './icons/HelpIcon.svelte';
 
-  const {
+  let {
     ssrSelectedItem = undefined,
+    controlledSelectedItem = undefined,
     onNavToggle = undefined,
     onNavItemClick = undefined,
     showAppIcons = true,
@@ -33,9 +39,10 @@
     consoleUrl,
     discoverUrl,
     supplementalMenuData,
+    children,
   } = $props();
 
-  const helpUrl = supplementalMenuData?.help?.url?.trim();
+  const helpUrl = $derived(() => supplementalMenuData?.help?.url?.trim());
 
   // Check if we're on the help page by comparing URLs (help is not a nav/subnav item)
   function getPathname(url: string, baseOrigin: string) {
@@ -47,23 +54,24 @@
   }
 
   function checkIsHelpPage(): boolean {
-    if (!helpUrl || helpUrl === '#' || helpUrl.startsWith('#')) {
+    const url = helpUrl();
+    if (!url || url === '#' || url.startsWith('#')) {
       return false;
     }
     const location = (
       globalThis as { location?: { pathname?: string; origin?: string } }
     ).location;
     if (location?.origin && location?.pathname) {
-      const helpPath = getPathname(helpUrl, location.origin);
+      const helpPath = getPathname(url, location.origin);
       return helpPath !== null && location.pathname === helpPath;
     }
     return false;
   }
 
-  const isHelpSelected = $derived(checkIsHelpPage());
+  const isHelpSelected = $derived(() => checkIsHelpPage());
 
-  let hydrated = false;
-  let navContainer: HTMLDivElement;
+  let hydrated = $state(false);
+  let navContainer = $state<HTMLDivElement | null>(null);
   let hoveredItem = $state<string | null>(null);
   let menuButtonHovered = $state(false);
   let canHover = $state(false);
@@ -79,8 +87,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,31 +104,36 @@
   }
 
   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()
   );
 
   onMount(() => {
+    if (typeof window === 'undefined') return;
+
     hydrated = true;
+
+    if (
+      controlledSelectedItem === undefined &&
+      ssrSelectedItem &&
+      $selectedItem === null
+    ) {
+      navigationStore.setSelectedItem(ssrSelectedItem);
+    }
     // Remove the CSS class since reactive state takes over
     document.documentElement.classList.remove('nav-initially-expanded');
+
     // Remove the custom property since reactive CSS takes over
     document.documentElement.style.removeProperty('--initial-main-top-padding');
     // Add hydrated class to re-enable transitions
@@ -121,106 +142,120 @@
     }
 
     // Detect if device supports hover (desktop only)
-    if (typeof window !== 'undefined') {
-      const mq = window.matchMedia('(hover: hover)');
+    const mq =
+      typeof window.matchMedia === 'function'
+        ? window.matchMedia('(hover: hover)')
+        : null;
+    const handleHoverChange = (e: MediaQueryListEvent) => {
+      canHover = e.matches;
+    };
+    if (mq) {
       canHover = mq.matches;
-      mq.addEventListener('change', e => {
-        canHover = e.matches;
-      });
+      mq.addEventListener('change', handleHoverChange);
+    } else {
+      canHover = false;
+    }
 
-      // Listen for layout transitions
-      const handleLayoutTransition = (event: Event) => {
-        const customEvent = event as CustomEvent;
-        const { isMobile } = customEvent.detail;
+    // Listen for layout transitions
+    const handleLayoutTransition = (event: Event) => {
+      const customEvent = event as CustomEvent;
+      const { isMobile } = customEvent.detail;
 
-        if (isMobile) {
-          // Switching to mobile: close navigation
-          navigationStore.setExpanded(false);
+      if (isMobile) {
+        // Switching to mobile: close navigation
+        navigationStore.setExpanded(false);
+      } else {
+        // Switching to desktop: open navigation if on non-discover page
+        const currentItem = selectedForUi();
+
+        if (currentItem && currentItem !== 'discover') {
+          navigationStore.setExpanded(true);
         } else {
-          // Switching to desktop: open navigation if on non-discover page
-          const currentItem = $selectedItem;
-
-          if (currentItem && currentItem !== 'discover') {
-            navigationStore.setExpanded(true);
-          } else {
-            navigationStore.setExpanded(false);
-          }
-        }
-      };
-
-      window.addEventListener('layoutTransition', handleLayoutTransition);
-
-      // Add Escape key handler for nav collapse, but ignore if focus is in profile context menu
-      const handleEscape = (e: KeyboardEvent) => {
-        const active = document.activeElement;
-        if (
-          e.key === 'Escape' &&
-          $isExpanded &&
-          !(active && active.closest('.profile-context-menu'))
-        ) {
           navigationStore.setExpanded(false);
         }
-      };
-      window.addEventListener('keydown', handleEscape);
+      }
+    };
 
-      // Custom event system for external control
-      const handleDesktopNavControlEvent = (event: Event) => {
-        const customEvent = event as CustomEvent;
-        const { action, isOpen: eventIsOpen } = customEvent.detail;
+    window.addEventListener('layoutTransition', handleLayoutTransition);
 
-        if (action === 'toggle') {
-          navigationStore.toggleExpanded();
-        } else if (action === 'open') {
-          navigationStore.setExpanded(true);
-        } else if (action === 'close') {
-          navigationStore.setExpanded(false);
-        } else if (action === 'set' && typeof eventIsOpen === 'boolean') {
-          navigationStore.setExpanded(eventIsOpen);
-        }
-      };
+    // Add Escape key handler for nav collapse, but ignore if focus is in profile context menu
+    const handleEscape = (e: KeyboardEvent) => {
+      const active = document.activeElement;
+      const profileMenuOpen = Boolean(
+        document.querySelector('.profile-context-menu')
+      );
+      if (
+        e.key === 'Escape' &&
+        $isExpanded &&
+        !profileMenuOpen &&
+        !(active && active.closest('.profile-context-menu'))
+      ) {
+        navigationStore.setExpanded(false);
+      }
+    };
+    window.addEventListener('keydown', handleEscape);
+
+    // Custom event system for external control
+    const handleDesktopNavControlEvent = (event: Event) => {
+      const customEvent = event as CustomEvent;
+      const { action, isOpen: eventIsOpen } = customEvent.detail;
+
+      if (action === 'toggle') {
+        navigationStore.toggleExpanded();
+      } else if (action === 'open') {
+        navigationStore.setExpanded(true);
+      } else if (action === 'close') {
+        navigationStore.setExpanded(false);
+      } else if (action === 'set' && typeof eventIsOpen === 'boolean') {
+        navigationStore.setExpanded(eventIsOpen);
+      }
+    };
+
+    // Listen for custom desktop navigation control events
+    window.addEventListener(
+      'graymatter-desktop-nav-control',
+      handleDesktopNavControlEvent
+    );
 
-      // Listen for custom desktop navigation control events
-      window.addEventListener(
+    eventListenerCleanup = () => {
+      window.removeEventListener(
         'graymatter-desktop-nav-control',
         handleDesktopNavControlEvent
       );
-
-      eventListenerCleanup = () => {
-        window.removeEventListener(
-          'graymatter-desktop-nav-control',
-          handleDesktopNavControlEvent
-        );
-      };
-
-      // Listen for navigation changes to update help button state
-      const handleNavigationChange = () => {
-        // Force reactivity update by accessing the derived value
-        // Accessing isHelpSelected triggers reactivity
-        void isHelpSelected;
-      };
-
-      window.addEventListener('popstate', handleNavigationChange);
-
-      return () => {
-        window.removeEventListener('layoutTransition', handleLayoutTransition);
-        window.removeEventListener('keydown', handleEscape);
-        window.removeEventListener('popstate', handleNavigationChange);
-        if (eventListenerCleanup) {
-          eventListenerCleanup();
-        }
-      };
-    }
+    };
+
+    // Listen for navigation changes to update help button state
+    const handleNavigationChange = () => {
+      // Force reactivity update by accessing the derived value
+      // Accessing isHelpSelected triggers reactivity
+      void isHelpSelected();
+    };
+
+    window.addEventListener('popstate', handleNavigationChange);
+
+    return () => {
+      window.removeEventListener('layoutTransition', handleLayoutTransition);
+      window.removeEventListener('keydown', handleEscape);
+      window.removeEventListener('popstate', handleNavigationChange);
+      if (mq) {
+        mq.removeEventListener('change', handleHoverChange);
+      }
+      if (eventListenerCleanup) {
+        eventListenerCleanup();
+      }
+    };
   });
 
   function handleHelpClick(event: MouseEvent) {
     // If it's a hash link, prevent default to stay on same page
-    if (helpUrl === '#' || helpUrl?.startsWith('#')) {
+    const url = helpUrl();
+    if (url === '#' || url?.startsWith('#')) {
       event.preventDefault();
     }
   }
 
   function toggleNav() {
-    if ($isMenuButtonDisabled) return;
+    if (menuBtnDisabled()) return;
     navigationStore.toggleExpanded();
     onNavToggle?.({ expanded: $isExpanded });
   }
@@ -231,7 +266,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') {
@@ -470,16 +507,16 @@
 
     {#if profileMenuData}
       <div class="nav-footer" part="nav-footer">
-        {#if helpUrl}
+        {#if helpUrl()}
           <div
             class="nav-footer-icon-container"
             part="nav-footer-icon-container"
           >
             <a
               class="help-link"
-              class:selected={isHelpSelected}
-              aria-current={isHelpSelected ? 'page' : undefined}
-              href={helpUrl}
+              class:selected={isHelpSelected()}
+              aria-current={isHelpSelected() ? 'page' : undefined}
+              href={helpUrl()}
               part="help-link"
               title="Help"
               aria-label="Help"
@@ -487,7 +524,7 @@
             >
               <div class="icon-container" part="help-icon-container">
                 <div class="icon-wrapper">
-                  <HelpIcon isSelected={isHelpSelected} />
+                  <HelpIcon isSelected={isHelpSelected()} />
                 </div>
               </div>
             </a>
@@ -513,7 +550,7 @@
     {#if sideNavExpanded()}
       <div class="drawer-content" part="drawer-content">
         <nav aria-label="Sub navigation" part="sub-navigation">
-          <slot />
+          {@render children?.()}
         </nav>
       </div>
     {/if}

package/src/components/DesktopSideNav.webcomponent.svelte

@@ -10,6 +10,7 @@
   // Props for the web component
   let {
     ssrSelectedItem,
+    controlledSelectedItem,
     onNavToggle,
     onNavItemClick,
     showAppIcons = true,
@@ -20,11 +21,13 @@
     consoleUrl,
     discoverUrl,
     supplementalMenuData,
+    children,
   } = $props();
 </script>
 
 <DesktopSideNav
   {ssrSelectedItem}
+  {controlledSelectedItem}
   {onNavToggle}
   {onNavItemClick}
   {showAppIcons}
@@ -35,6 +38,5 @@
   {consoleUrl}
   {discoverUrl}
   {supplementalMenuData}
->
-  <slot />
-</DesktopSideNav>
+  {children}
+/>

package/src/components/Logo.svelte

@@ -8,9 +8,9 @@
     ...restProps
   } = $props();
 
-  const logoColor = isInverted
-    ? 'var(--ai-color-white)'
-    : 'var(--ai-color-black)';
+  const logoColor = $derived(() =>
+    isInverted ? 'var(--ai-color-white)' : 'var(--ai-color-black)'
+  );
 </script>
 
 {#if !showServiceMark}
@@ -20,7 +20,7 @@
     viewBox="0 0 102 30"
     fill="none"
     xmlns="http://www.w3.org/2000/svg"
-    style="fill: {logoColor};"
+    style="fill: {logoColor()};"
     {...restProps}
   >
     <g>
@@ -44,7 +44,7 @@
     viewBox="0 0 75 20"
     fill="none"
     xmlns="http://www.w3.org/2000/svg"
-    style="fill: {logoColor};"
+    style="fill: {logoColor()};"
     {...restProps}
   >
     <path