@gsa-tts/graymatter-ui 0.3.13 → 0.3.15

package/README.md

@@ -190,6 +190,7 @@ import {
 ### Layout Components
 - **GlobalAppLayout** - Main application layout wrapper
 - **BaseLayout** - Base page layout structure
+- **DocsLayout** - Documentation layout with dynamic navigation (Astro only)
 
 ### UI Components
 - **ProfileMenu** - User profile dropdown menu with event-driven actions
@@ -235,15 +236,18 @@ Detailed documentation for specific components is available in the package:
 
 - **[NAVIGATION_CONTROL.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/NAVIGATION_CONTROL.md)** - DesktopSideNav external control system with event-based API
 - **[PROFILE_MENU.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/PROFILE_MENU.md)** - ProfileMenu component usage and event handling
+- **[README_DocsLayout.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/README_DocsLayout.md)** - DocsLayout component with dynamic navigation generation (Astro only)
 
 These files are also included with the package in your `node_modules/@gsa-tts/graymatter-ui/` directory. If you don't have access to the private repository, you can find the documentation files locally after installation.
 
 ## Framework Support
 
-- **Svelte 5** - Native Svelte components
-- **Astro** - Full support with client-side hydration
-- **React/Vue/Angular** - Via web components
-- **Vanilla JavaScript** - Via web components
+- **Svelte 5** - Native Svelte components (individual components only)
+- **Astro** - Full support with client-side hydration (including DocsLayout)
+- **React/Vue/Angular** - Via web components (individual components only)
+- **Vanilla JavaScript** - Via web components (individual components only)
+
+**Note:** The `DocsLayout` component is Astro-specific and cannot be used in other frameworks. For non-Astro applications, use the individual Svelte components and shared utilities instead.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsa-tts/graymatter-ui",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,6 +18,9 @@
     "./components": "./src/components/index.ts",
     "./components/*": "./src/components/*",
     "./constants": "./src/constants/index.ts",
+    "./data": "./src/data/index.ts",
+    "./data/*": "./src/data/*",
+    "./content/api/*": "./src/content/api/*",
     "./helpers": "./src/helpers/index.ts",
     "./helpers/*": "./src/helpers/*",
     "./utils": "./src/utils/index.ts",
@@ -56,8 +59,8 @@
     "vite": "^6.3.5",
     "vitest": "^3.0.7",
     "@gsa-tts/graymatter-typescript-config": "0.0.2",
-    "@gsa-tts/graymatter-eslint": "0.0.2",
-    "@gsa-tts/graymatter-vitest-config": "0.0.1"
+    "@gsa-tts/graymatter-vitest-config": "0.0.1",
+    "@gsa-tts/graymatter-eslint": "0.0.2"
   },
   "dependencies": {
     "@fontsource-variable/archivo": "^5.2.6",

package/src/components/ApiDocSubNavList.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  import ApiDocSubNavMenuItem from './ApiDocSubNavMenuItem.svelte';
+  import Self from './ApiDocSubNavList.svelte';
+
+  const { items, level = 0, selectedId, onClick, onKeyDown } = $props();
+</script>
+
+{#each items as item}
+  <ApiDocSubNavMenuItem
+    {item}
+    {level}
+    isSelected={selectedId === item.id}
+    {onClick}
+    {onKeyDown}
+  />
+  {#if item.children}
+    <Self
+      items={item.children}
+      level={level + 1}
+      {selectedId}
+      {onClick}
+      {onKeyDown}
+    />
+  {/if}
+{/each}

package/src/components/ApiDocSubNavMenu.svelte

@@ -0,0 +1,464 @@
+<script lang="ts">
+  import { createEventDispatcher, onMount } from 'svelte';
+  import { subNavReady } from '@gsa-tts/graymatter-ui/stores/subNavReadyStore';
+  import type { SubNavData, SubNavItem } from '../types/subnav.ts';
+  import ApiDocSubNavList from './ApiDocSubNavList.svelte';
+
+  const { data = null } = $props();
+
+  const sections = $derived(() =>
+    !Array.isArray(data) &&
+    data &&
+    typeof data === 'object' &&
+    'sections' in data &&
+    Array.isArray(
+      (data as { sections: { header: string; items: SubNavItem[] }[] }).sections
+    )
+      ? (data as { sections: { header: string; items: SubNavItem[] }[] })
+          .sections
+      : null
+  );
+
+  const dispatch = createEventDispatcher<{
+    navigate: { item: SubNavItem };
+    itemSelect: { item: SubNavItem };
+    mobileAnchorNavigate: { hash: string };
+  }>();
+
+  function findFirstItem(data: SubNavData | null): SubNavItem | null {
+    if (!data) return null;
+
+    if (Array.isArray(data)) {
+      return data[0] || null;
+    } else if (
+      data &&
+      typeof data === 'object' &&
+      'sections' in data &&
+      Array.isArray(
+        (data as { sections: { header: string; items: SubNavItem[] }[] })
+          .sections
+      )
+    ) {
+      const sections = (
+        data as { sections: { header: string; items: SubNavItem[] }[] }
+      ).sections;
+      if (
+        sections.length > 0 &&
+        sections[0] &&
+        sections[0].items &&
+        sections[0].items.length > 0
+      ) {
+        return sections[0].items[0] || null;
+      }
+    }
+    return null;
+  }
+
+  function findItemByHash(
+    data: SubNavData | null,
+    hash: string
+  ): SubNavItem | null {
+    if (!data) return null;
+
+    function searchInItems(items: SubNavItem[]): SubNavItem | null {
+      for (const item of items) {
+        if (item.href && item.href.includes('#')) {
+          const itemHash = item.href.split('#')[1];
+          if (itemHash === hash) {
+            return item;
+          }
+        }
+        if (item.children) {
+          const found = searchInItems(item.children);
+          if (found) return found;
+        }
+      }
+      return null;
+    }
+
+    if (Array.isArray(data)) {
+      return searchInItems(data);
+    } else if (
+      data &&
+      typeof data === 'object' &&
+      'sections' in data &&
+      Array.isArray(
+        (data as { sections: { header: string; items: SubNavItem[] }[] })
+          .sections
+      )
+    ) {
+      for (const section of (
+        data as { sections: { header: string; items: SubNavItem[] }[] }
+      ).sections) {
+        const found = searchInItems(section.items);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  function findItemById(
+    data: SubNavData | null,
+    id: string
+  ): SubNavItem | null {
+    if (!data) return null;
+
+    function searchInItems(items: SubNavItem[]): SubNavItem | null {
+      for (const item of items) {
+        if (item.id === id) {
+          return item;
+        }
+        if (item.children) {
+          const found = searchInItems(item.children);
+          if (found) return found;
+        }
+      }
+      return null;
+    }
+
+    if (Array.isArray(data)) {
+      return searchInItems(data);
+    } else if (
+      data &&
+      typeof data === 'object' &&
+      'sections' in data &&
+      Array.isArray(
+        (data as { sections: { header: string; items: SubNavItem[] }[] })
+          .sections
+      )
+    ) {
+      for (const section of (
+        data as { sections: { header: string; items: SubNavItem[] }[] }
+      ).sections) {
+        const found = searchInItems(section.items);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  // Utility: Find top-level parent of a submenu item
+  function findTopLevelParent(
+    item: SubNavItem,
+    data: SubNavData | null
+  ): SubNavItem | null {
+    if (!data || !item) return null;
+    function search(
+      items: SubNavItem[],
+      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 (found) return found;
+        }
+      }
+      return null;
+    }
+    if (Array.isArray(data)) {
+      return search(data, null);
+    } else if (
+      data &&
+      typeof data === 'object' &&
+      'sections' in data &&
+      Array.isArray(
+        (data as { sections: { header: string; items: SubNavItem[] }[] })
+          .sections
+      )
+    ) {
+      for (const section of (
+        data as { sections: { header: string; items: SubNavItem[] }[] }
+      ).sections) {
+        const found = search(section.items, null);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  let currentSelectedId = $state<string | null>(null);
+  let hydrated = $state(false);
+
+  const effectiveSelectedId = $derived(() => {
+    if (!hydrated || !data) return null;
+
+    // If we already have a selectedId, use it
+    if (currentSelectedId) return currentSelectedId;
+
+    // First priority: URL hash
+    if (typeof window !== 'undefined' && window.location.hash) {
+      const hash = window.location.hash.substring(1);
+      const targetItem = findItemByHash(data, hash);
+      if (targetItem) {
+        return targetItem.id;
+      }
+    }
+
+    // Second priority: 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;
+            }
+          }
+        } catch (e) {
+          console.log('[SubNavMenu] Error parsing stored ID:', e);
+        }
+      }
+    }
+
+    // Third priority: first item
+    const firstItem = findFirstItem(data);
+    if (firstItem && firstItem.title) {
+      return firstItem.id;
+    }
+
+    return null;
+  });
+
+  // Update currentSelectedId when effectiveSelectedId changes
+  $effect(() => {
+    if (effectiveSelectedId() && effectiveSelectedId() !== currentSelectedId) {
+      currentSelectedId = effectiveSelectedId();
+    }
+  });
+
+  onMount(() => {
+    hydrated = true;
+
+    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);
+        }
+      }
+
+      // 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,
+            },
+          })
+        );
+      }
+    }
+    subNavReady.set(true);
+  });
+
+  function handleItemClick(event: Event, item: SubNavItem) {
+    // Always prevent default for anchor links
+    if (item.href && item.href.includes('#')) {
+      event.preventDefault();
+    } else if (!item.href || item.href === '#') {
+      event.preventDefault();
+    }
+    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();
+    if (typeof window !== 'undefined') {
+      if (item.href && item.href.includes('#')) {
+        const hash = item.href.split('#')[1];
+        if (hash) {
+          window.location.hash = hash;
+          if (window.innerWidth > 640) {
+            // Desktop: use delay for consistent timing
+            setTimeout(() => {
+              scrollToAnchorWithOffset(hash);
+            }, 350);
+          } else {
+            // Mobile: immediate scroll without delay
+            window.dispatchEvent(
+              new CustomEvent('mobileAnchorNavigate', { detail: { hash } })
+            );
+          }
+        }
+      }
+      // Always use top-level parent for header
+      if (topLevel.title) {
+        window.dispatchEvent(
+          new CustomEvent('sectionVisible', {
+            detail: {
+              title: topLevel.title,
+              id: topLevel.id,
+            },
+          })
+        );
+      }
+      // Mobile menu logic unchanged
+      if (window.innerWidth <= 640 && item.href && item.href !== '#') {
+        import('@gsa-tts/graymatter-ui/stores/navigationStore').then(
+          ({ navigationStore }) => {
+            navigationStore.setExpanded(false);
+          }
+        );
+      }
+      if (window.innerWidth <= 640) {
+        window.dispatchEvent(new CustomEvent('closeMobileMenu'));
+      }
+    }
+    if (item.href && item.href !== '#') {
+      dispatch('navigate', { item });
+    } else {
+      dispatch('itemSelect', { item });
+    }
+  }
+
+  function handleKeyDown(event: KeyboardEvent, item: SubNavItem) {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      handleItemClick(event, item);
+    }
+  }
+
+  // Utility: Scroll to anchor with header offset
+  function scrollToAnchorWithOffset(anchorId: string) {
+    const mainContent = document.getElementById('main-content');
+    if (mainContent) {
+      const anchor = mainContent.querySelector(
+        `[id="${anchorId}"]`
+      ) as HTMLElement;
+      if (anchor) {
+        // Use instant scrolling without animation
+        try {
+          // Add temporary scroll margin to account for header
+          const originalScrollMargin = anchor.style.scrollMarginTop;
+          anchor.style.scrollMarginTop = '56px';
+
+          anchor.scrollIntoView({
+            behavior: 'auto',
+            block: 'start',
+            inline: 'nearest',
+          });
+
+          // Restore original scroll margin after a delay
+          setTimeout(() => {
+            anchor.style.scrollMarginTop = originalScrollMargin;
+          }, 1000);
+        } catch {
+          // Fallback to manual calculation
+          const headerHeight = 56;
+          const rect = anchor.getBoundingClientRect();
+          const scrollTop = window.scrollY + rect.top - headerHeight;
+          const finalScrollTop = Math.max(0, scrollTop);
+          window.scrollTo({ top: finalScrollTop, behavior: 'auto' });
+        }
+      }
+    }
+  }
+</script>
+
+<div class="sub-menu-container">
+  <div class="sub-menu-content">
+    {#if data}
+      {#if Array.isArray(data)}
+        <ApiDocSubNavList
+          items={data}
+          level={0}
+          selectedId={effectiveSelectedId()}
+          onClick={handleItemClick}
+          onKeyDown={handleKeyDown}
+        />
+      {/if}
+      {#each sections() ?? [] as section: { header: string; items: SubNavItem[] }}
+        <div class="sub-menu-header">
+          {section.header}
+        </div>
+        <ApiDocSubNavList
+          items={section.items}
+          level={0}
+          selectedId={effectiveSelectedId()}
+          onClick={handleItemClick}
+          onKeyDown={handleKeyDown}
+        />
+      {/each}
+    {/if}
+  </div>
+</div>
+
+<style>
+  .sub-menu-container {
+    display: flex;
+    padding: 0 var(--ai-size-8) var(--ai-size-16) var(--ai-size-8);
+    flex-direction: column;
+    align-items: flex-start;
+    gap: var(--ai-size-32);
+    align-self: stretch;
+    min-height: 6.25rem;
+  }
+  .sub-menu-content {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: var(--ai-size-2);
+    align-self: stretch;
+  }
+  .sub-menu-header {
+    display: flex;
+    padding: var(--ai-size-8);
+    justify-content: flex-start;
+    align-items: center;
+    gap: var(--ai-size-10);
+    align-self: stretch;
+    color: var(--ai-color-steel-900);
+    font-size: var(--ai-size-12);
+    font-style: normal;
+    font-weight: 600;
+    line-height: 1.2;
+    letter-spacing: 0.0075rem;
+    text-transform: uppercase;
+  }
+</style>

package/src/components/ApiDocSubNavMenuItem.svelte

@@ -0,0 +1,116 @@
+<script lang="ts">
+  const { item, level = 0, isSelected = false, onClick, onKeyDown } = $props();
+  const levelClass = $derived(() => `level-${level}`);
+  const hasHref = $derived(() => item.href && item.href !== '#');
+</script>
+
+{#if hasHref()}
+  <a
+    href={item.href}
+    class={`menu-item ${levelClass()}`}
+    class:selected={isSelected}
+    onclick={e => onClick(e, item)}
+  >
+    <div class="menu-item-content">
+      <span class="menu-item-text" class:selected={isSelected}>
+        {item.title}
+      </span>
+    </div>
+  </a>
+{:else}
+  <div
+    class={`menu-item ${levelClass()}${!hasHref() ? ' non-clickable' : ''}`}
+    class:selected={isSelected}
+    tabindex="0"
+    role="button"
+    aria-label={`Select ${item.title}`}
+    onclick={e => onClick(e, item)}
+    onkeydown={e => onKeyDown(e, item)}
+  >
+    <div class="menu-item-content">
+      <span class="menu-item-text" class:selected={isSelected}>
+        {item.title}
+      </span>
+    </div>
+  </div>
+{/if}
+
+<style>
+  .menu-item {
+    display: flex;
+    height: 2.1625rem; /* 34.6px */
+    padding: var(--ai-size-8);
+    align-items: center;
+    gap: var(--ai-size-4);
+    align-self: stretch;
+    width: 100%;
+    background: none;
+    border: none;
+    cursor: pointer;
+    text-decoration: none;
+    color: inherit;
+    border-radius: var(--ai-size-4);
+    transition: background-color var(--ai-transition-ease-fast);
+  }
+
+  .menu-item:hover {
+    background-color: var(--ai-color-steel-200);
+  }
+
+  .menu-item:focus {
+    outline: var(--ai-size-2) solid var(--ai-color-blue-600);
+    outline-offset: var(--ai-size-2);
+  }
+
+  /* Hide focus outline on click */
+  .menu-item:focus:not(:focus-visible) {
+    outline: none;
+  }
+
+  .menu-item.selected {
+    background-color: var(--ai-color-steel-200);
+  }
+
+  .menu-item.non-clickable {
+    cursor: default;
+  }
+
+  .menu-item.non-clickable:hover {
+    background-color: transparent;
+  }
+
+  /* Nesting levels with indentation */
+  .menu-item.level-0 {
+    padding-left: var(--ai-size-8);
+  }
+
+  .menu-item.level-1 {
+    padding-left: var(--ai-size-20);
+  }
+
+  .menu-item.level-2 {
+    padding-left: var(--ai-size-32);
+  }
+
+  .menu-item-content {
+    display: flex;
+    align-items: center;
+    gap: var(--ai-size-10);
+    flex: 1 0 0;
+  }
+
+  .menu-item-text {
+    color: var(--ai-color-steel-800);
+    font-size: var(--ai-size-14);
+    font-style: normal;
+    font-weight: 400;
+    line-height: 1.3;
+    transition: all var(--ai-transition-ease-fast);
+  }
+
+  .menu-item-text.selected,
+  .menu-item.selected .menu-item-text {
+    color: var(--ai-color-black);
+    font-weight: 600;
+  }
+</style>

package/src/components/index.ts

@@ -12,6 +12,9 @@ export { default as MobileBottomNav } from './MobileBottomNav.svelte';
 export { default as MobileSideMenu } from './MobileSideMenu.svelte';
 export { default as NavigationInitializer } from './NavigationInitializer.svelte';
 export { default as UsaSkipNav } from './UsaSkipNav.svelte';
+export { default as ApiDocSubNavMenu } from './ApiDocSubNavMenu.svelte';
+export { default as ApiDocSubNavList } from './ApiDocSubNavList.svelte';
+export { default as ApiDocSubNavMenuItem } from './ApiDocSubNavMenuItem.svelte';
 
 // Icon Components
 export * from './icons/index.js';