@gsa-tts/graymatter-ui 0.3.14 → 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.14",
+  "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",
@@ -55,9 +58,9 @@
     "typescript": "5.7.3",
     "vite": "^6.3.5",
     "vitest": "^3.0.7",
-    "@gsa-tts/graymatter-eslint": "0.0.2",
+    "@gsa-tts/graymatter-typescript-config": "0.0.2",
     "@gsa-tts/graymatter-vitest-config": "0.0.1",
-    "@gsa-tts/graymatter-typescript-config": "0.0.2"
+    "@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';

package/src/content/api/endpoints.mdx

@@ -0,0 +1,174 @@
+---
+title: 'Endpoints'
+description: ''
+sortOrder: 20
+---
+
+API endpoints will be available when you login.
+
+### 1. Models
+
+GET /api/v1/models
+
+To reach models the documented endpoint is `<base url>/api/v1/models`, which will allow you to retrieve available model information.  
+
+**Example Request**
+
+```bash
+curl -X 'GET' \
+'<base url>/api/v1/models' \
+-H 'accept: application/json' \
+-H 'Authorization: Bearer <Your API Key>'
+```
+**Example Response**
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "claude_3_5_sonnet",
+      "created": 1718841600,
+      "object": "model",
+      "owned_by": "Anthropic"
+    },
+    {
+      "id": "llama3211b",
+      "created": 1727222400,
+      "object": "model",
+      "owned_by": "Meta"
+    },
+    {
+      "id": "cohere_english_v3",
+      "created": 1698883200,
+      "object": "model",
+      "owned_by": "Cohere"
+    }
+  ]
+}
+```
+### 2. Chat Completions
+
+POST /api/v1/chat/completions
+
+To reach chat completions the documented endpoint is `<base url>/api/v1/chat/completions`, which will allow you to retrieve chat completion information. 
+
+**Request Body**
+
+* **model**: The model ID (e.g: gemini-2.0-flash, claude_3_haiku)
+* **messages**: An array of of message items consisting of User message, Image Content, Document Content, Assistant Message
+* **max_tokens**: Maximum response length (optional)
+* **temperature**: Response creativity (0.0-2.0, optional)
+
+| **Models** | **Range** | **Default value** |
+| :------- | :------: | -------: |
+| Google models | 0.0 - 2.0 | 1.0 |
+| Anthropic models | 0.0 - 1.0 | 0.5 |
+| Meta models | 0.0 - 1.0 | 0.5 |
+
+* **top_p**: An alternative to sampling with temperature, called nucleus sampling (optional)
+* **stream**: a boolean indicating whether to send partials responses as available (optional)
+
+**Example Request**
+
+```bash
+curl -X 'POST' \
+'<base url>/api/v1/chat/completions' \
+-H 'accept: application/json' \
+-H 'Authorization: Bearer <Your API Key>' \
+-H 'Content-Type: application/json' \
+-d '{
+  "messages": [
+    {
+      "content": "You speak only pirate",
+      "role": "system"
+    },
+    {
+      "content": "Hello!",
+      "role": "user"
+    }
+  ],
+  "model": "gemini-2.0-flash"
+}'
+```
+
+**Example Response**
+
+```json
+{
+   "object": "chat.completion",
+   "created": 1748517745,
+   "model": "gemini-2.0-flash",
+   "choices": [
+      {
+        "index": 0,
+        "message": {
+           "role": "assistant",
+           "content": "Ahoy there, matey! What brings ye to me waters?\n"
+        },
+       "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+       "prompt_tokens": 14,
+       "completion_tokens": 15,
+      "total_tokens": 29
+  }
+}
+
+```
+
+### 3. Embeddings
+
+POST /api/v1/embeddings
+
+To reach embeddings the documented endpoint is `<base url>/api/v1/embeddings`, which will allow you to retrieve embeddings information.  
+
+**Request Body**
+
+* **model:** The model ID (e.g: cohere_english_v3)
+* **input:** Input text to embed, encoded as a string or array of strings. Each input must not exceed the max input tokens for the model.
+dimensions: The number of dimensions the resulting output embeddings should have. Only supported in some models (Optional)
+* **input_type:** (Note: this is not part of the OpenAI specification but is useful on some models). Specify the kind of input to allow the model to optimize for specific uses. Options are: "search_document", "search_query",   "classification", "clustering", "semantic_similarity" (Optional)
+
+**Example Request**
+
+```bash
+curl -X 'POST' \
+'<base url>/api/v1/embeddings' \
+-H 'accept: application/json' \
+-H 'Authorization: Bearer <Your API Key>\
+-H 'Content-Type: application/json' \
+-d '{
+    "encodingFormat": "float",
+    "input": "A mighty woman with a torch, whose flame / Is the imprisoned lightning",
+    "input_type": "search_document",
+    "model": "cohere_english_v3"
+}
+```
+**Example Response**
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "embedding",
+      "embedding": [
+        0.06933594,
+        -0.030883789,
+        0.054351807,
+        -0.0018196106,
+       …
+        0.013938904
+      ],
+      "index": 0
+    }
+  ],
+  "model": "cohere.embed-english-v3",
+  "usage": {
+    "promptTokens": 12,
+    "totalTokens": 12
+  }
+}
+```

package/src/content/api/getting-started.mdx

@@ -0,0 +1,84 @@
+---
+title: 'Getting Started'
+description: ''
+sortOrder: 10
+---
+
+### Introduction
+
+USAi API provides programmatic access to AI services for government users and approved partners. It currently supports Chat Completions (model inference) and Embeddings (used for RAG and other applications). 
+
+Our API has resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses HTTP response codes to indicate API errors, authentication messaging, and verbs. 
+
+### Models and endpoints 
+
+USAi API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) and provides access to the large language models (LLMs):
+
+**Google AI models**
+- [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash)
+- [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models#gemini-2.5-pro)
+
+**Anthropic models**
+- [Claude Haiku 3.5](https://docs.claude.com/en/docs/overview)
+- [Claude Sonnet 3.7](https://docs.claude.com/en/docs/overview)
+- [Claude Sonnet 4](https://docs.claude.com/en/docs/overview)
+- [Claude Opus 4](https://docs.claude.com/en/docs/overview)
+
+**Meta models**
+- [Llama 3.2 11B](https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_2/)
+- [Llama 4 Maverick](https://www.llama.com/docs/model-cards-and-prompt-formats/llama4/)
+
+The interface is modeled after the [OpenAI Chat Completion API](https://platform.openai.com/docs/guides/text?api-mode=responses). We will continue to add more models over time; we may also remove models if they are found to not meet our standards. You will be notified if a model is removed. 
+
+Each model we draw on has unique capabilities. Models may also respond differently to the same API request. Below is a summary of each endpoint’s functionality:
+
+- **Chat Completions:** The ability to send prompts and receive a response from the LLM models.
+- **Embedding:** Converts input into numeric vectors representing semantic meaning. The vectors are used for tasks like retrieving information from documents, document analysis, and building Retrieval Augmented Generation (RAG) systems.
+- **Models:** A list of models and IDs used to specify LLM models in requests.
+
+#### Content types
+
+The models USAi API draws on support multiple types of inputs; text, image, and file content types. However, each model has different input capabilities: for example, Claude Sonnet supports Optical Character Recognition (OCR) and recognizes image-only PDFs, while Claude Haiku and Llama currently do not. For additional detail about how we handle these content types, reference [OpenAI’s API documentation](https://platform.openai.com/docs/api-reference/chat/create). 
+
+### Authentication
+
+All API requests require an API key. Upon authentication, your agency-specific instructions for requesting an API key, and the API endpoint, will be available.
+
+### Limitations
+
+#### Rate limitations
+
+We currently have a rate limit of 3 calls / second / API key. If you hit a rate limit, you should expect a 429 error code. If you need additional capacity, please contact us at [support@usai.gov](mailto:support@usai.gov). We can work with our infrastructure providers to secure higher model limits.
+
+#### Feature limitations
+
+Because the underlying platforms have different capabilities and interfaces, not all features of the Chat Completions API are available at this time. Current known limitations include:
+
+- Audio
+- Structured output
+
+#### Guardrail limitations
+
+We do not have guardrails beyond those provided by our model providers; this means that an API user has full control over what inputs and outputs are allowed when using the API. We expect API users to interact with the API ethically and deliberately, and add their own guardrails and system prompts as needed. We recommend implementing system prompts when using the API in situations where you do not know what inputs the model will receive. 
+
+System prompts should address your needs and concerns. Some of the system prompts in USAi Chat include:
+- You are a helpful assistant that works for a government agency. 
+- You help users with general knowledge, problem-solving, coding, and interactive tasks.
+- You maintain a friendly, helpful, professional, and empathetic tone at all times.  
+- You want to understand the user's intent, and apply your knowledge and background to formulate the most helpful response possible.  
+- Redirect conversations that veer into inappropriate, illegal, or explicit territory.  
+- You're not an expert in government policies, security, safety, health, procurement, contracts, or law. Provide general guidance only and advise users to reference appropriate material.
+- Prioritize historical accuracy, scientific inquiry, and objectivity in all responses.
+- Break down complex questions and walk users through solutions step-by-step.
+- Use real-world analogies to simplify complex concepts.  
+- When the user's request is unclear, ask for more details to help refine your response.  
+- Ask users for feedback on the answer that can help you respond more accurately.
+- Never knowingly make false statements or deceive users.  
+- Avoid generating explicit, hateful, dangerous, or illegal content. 
+- Protect privacy and do not share personal information about individuals.  
+- Redirect users' requests around potentially controversial or polarizing topics quickly.  
+- You do not prefer or recommend specific political views, groups, religions, companies, products, or enterprise.
+
+### Code demo
+
+To see an example of how to implement features using Python, visit our [HTML example notebook](https://www.usai.gov/assets/files/jupyter_example.html). If you would like to run this file in a Jupyter environment, you can download the <a href="https://www.usai.gov/assets/files/jupyter_example.ipynb" download>notebook ipynb file</a>.

package/src/content/api/support.mdx

@@ -0,0 +1,10 @@
+---
+title: 'Support'
+description: ''
+sortOrder: 30
+---
+
+You may encounter issues while working with the USAi API, as it is under active development. We may not be able to fix all issues immediately, but will add them to our backlog for future releases. If you have any questions, hit rate limits, or otherwise need assistance, please contact us at [support@usai.gov](mailto:support@usai.gov).
+
+
+

package/src/layouts/DocsLayout.astro

@@ -0,0 +1,178 @@
+---
+import GlobalAppLayout from './GlobalAppLayout.astro';
+import ApiDocSubNavMenu from '../components/ApiDocSubNavMenu.svelte';
+import NavigationInitializer from '../components/NavigationInitializer.svelte';
+import { getBaseUrl } from '../helpers';
+
+const gtmID = import.meta.env.PUBLIC_GTM_ID;
+const {
+  navigationItem = 'api',
+  title,
+  description,
+  openGraphImage,
+  showAppIcons = false,
+  subNavData = null,
+  disableCodeCopyButtons = false,
+  postItems = null,
+  profileMenuData = null,
+} = Astro.props;
+---
+
+<GlobalAppLayout
+  ssrSelectedItem={navigationItem}
+  gtmID={gtmID}
+  {showAppIcons}
+  {profileMenuData}
+  logoLinkUrl={getBaseUrl()}
+  logoLinkLabel="Homepage"
+  title={title}
+  {description}
+  {openGraphImage}
+>
+  <!-- Initialize navigation state and auto-expand submenu for section pages -->
+  <NavigationInitializer
+    item={navigationItem}
+    autoExpand={true}
+    client:only="svelte"
+  />
+
+  <!-- Documentation Sub Navigation -->
+  {
+    subNavData && (
+      <ApiDocSubNavMenu
+        data={subNavData}
+        selectedId={null}
+        slot="sub-nav"
+        client:load
+      />
+    )
+  }
+
+  <!-- Main content area -->
+  <div class="docs-content">
+    <article class="article-body">
+      <h1 class="page-title">API Documentation</h1>
+
+      <!-- Render postItems if provided -->
+      {
+        postItems &&
+          postItems.map((post: any) => (
+            <div>
+              <h2 class="title" id={post.id}>
+                {post.data.title}
+              </h2>
+              <post.ContentComponent />
+            </div>
+          ))
+      }
+    </article>
+  </div>
+</GlobalAppLayout>
+
+<!-- Add copy button to all code blocks -->
+{
+  !disableCodeCopyButtons && (
+    <script>
+      import {setupCopyButtons} from '../utils/copyButtonScript.js';
+      setupCopyButtons();
+    </script>
+  )
+}
+
+<style>
+  body {
+    color: var(--ai-color-steel-900);
+    line-height: var(--ai-font-lineheight-prose);
+  }
+
+  :is(h1, h2, h3, h4, h5, h6) {
+    color: var(--ai-color-black);
+  }
+
+  .docs-content {
+    padding: 0;
+  }
+
+  .article-body {
+    max-width: 84ch;
+  }
+
+  :global(.ai-copy-btn) {
+    width: var(--ai-size-32);
+    height: var(--ai-size-32);
+    position: absolute;
+    top: var(--ai-size-8);
+    right: var(--ai-size-8);
+    background: none;
+    border-radius: var(--ai-size-4);
+    border: none;
+    padding: 0;
+    cursor: pointer;
+    box-shadow: 0 var(--ai-size-2) var(--ai-size-8) rgba(0, 0, 0, 0.08);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition:
+      background var(--ai-duration-fast),
+      border var(--ai-duration-fast);
+    z-index: var(--ai-layer-2);
+    overflow: hidden;
+  }
+  :global(.ai-copy-btn:hover),
+  :global(.ai-copy-btn:focus) {
+    background: var(--ai-color-steel-800);
+  }
+  :global(.ai-copy-btn svg) {
+    display: block;
+    position: relative;
+  }
+  :global(.ai-code-block-wrapper) {
+    position: relative;
+    display: block;
+  }
+  :global(pre) {
+    font-family: var(--ai-font-family-monospace);
+    font-size: var(--ai-size-13);
+    font-weight: var(--ai-font-weight-normal);
+  }
+
+  /* Table styling - only for documentation pages */
+  :global(.docs-content table) {
+    width: 100%;
+    border-collapse: collapse;
+    margin: var(--ai-size-24) 0;
+  }
+
+  :global(.docs-content table th),
+  :global(.docs-content table td) {
+    padding: var(--ai-size-12) var(--ai-size-16);
+    text-align: left;
+    border-bottom: 1px solid var(--ai-color-neutral-200);
+  }
+
+  :global(.docs-content table th) {
+    background-color: var(--ai-color-neutral-50);
+    font-weight: var(--ai-font-weight-semibold);
+    color: var(--ai-color-black);
+  }
+
+  :global(.docs-content table tbody tr:hover) {
+    background-color: var(--ai-color-neutral-25);
+  }
+
+  :global(.docs-content table tbody tr:last-child td) {
+    border-bottom: none;
+  }
+
+  @media (--ai-size-breakpoint-tablet) {
+    .docs-content {
+      padding: 2rem 0;
+    }
+  }
+
+  @media (--ai-size-breakpoint-desktop) {
+    .docs-content {
+      padding: 2rem;
+    }
+  }
+</style>

package/src/types/subnav.ts

@@ -0,0 +1,15 @@
+export interface SubNavItem {
+  id: string;
+  title: string;
+  href?: string;
+  children?: SubNavItem[];
+}
+
+export interface SubNavSection {
+  header: string;
+  items: SubNavItem[];
+}
+
+export interface SubNavData {
+  sections: SubNavSection[];
+}

package/src/utils/copyButtonScript.ts

@@ -0,0 +1,107 @@
+interface CopyButtonConfig {
+  buttonClass?: string;
+  copyIconClass?: string;
+  checkIconClass?: string;
+  timeout?: number;
+}
+
+export function initializeCopyButtons(config: CopyButtonConfig = {}) {
+  const {
+    buttonClass = 'ai-copy-btn',
+    copyIconClass = 'ai-copy-icon',
+    checkIconClass = 'ai-check-icon',
+    timeout = 1200,
+  } = config;
+
+  // Function to add a button to a visible code block
+  function addCopyButton(pre: HTMLPreElement) {
+    const codeBlock = pre.querySelector('code');
+    if (!codeBlock || pre.querySelector(`.${buttonClass}`)) return;
+
+    const wrapper = codeBlock.closest('.ai-code-block-wrapper');
+    if (!wrapper) return;
+
+    const button = document.createElement('button');
+    button.className = buttonClass;
+    button.type = 'button';
+    button.setAttribute('aria-label', 'Copy code to clipboard');
+
+    button.innerHTML = `
+      <!-- Inline Copy Icon -->
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
+        stroke-width="1.5" stroke="#f2f4f7"
+        class="usai-icon ${copyIconClass} size-6"
+        aria-hidden="true" focusable="false" role="img"
+        style="width:1.25em;height:1.25em;">
+        <path stroke-linecap="round" stroke-linejoin="round"
+          d="M15.75 17.25v3.375c0 .621-.504 1.125-1.125 1.125h-9.75a1.125 1.125 0 0 1-1.125-1.125V7.875c0-.621.504-1.125 1.125-1.125H6.75a9.06 9.06 0 0 1 1.5.124m7.5 10.376h3.375c.621 0 1.125-.504 1.125-1.125V11.25c0-4.46-3.243-8.161-7.5-8.876a9.06 9.06 0 0 0-1.5-.124H9.375c-.621 0-1.125.504-1.125 1.125v3.5m7.5 10.375H9.375a1.125 1.125 0 0 1-1.125-1.125v-9.25m12 6.625v-1.875a3.375 3.375 0 0 0-3.375-3.375h-1.5a1.125 1.125 0 0 1-1.125-1.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H9.75" />
+      </svg>
+
+      <!-- Inline Check Icon -->
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
+        stroke-width="1.5" stroke="#f2f4f7"
+        class="usai-icon ${checkIconClass} size-6"
+        aria-hidden="true" focusable="false" role="img"
+        style="display:none; position:absolute; top:50%; left:50%; transform:translate(-50%,-50%); width:1.25em; height:1.25em;">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m4.5 12.75 6 6 9-13.5" />
+      </svg>
+    `;
+
+    button.onclick = () => {
+      const lines = codeBlock.querySelectorAll('.line');
+      const textToCopy =
+        lines.length > 0
+          ? Array.from(lines)
+              .map(line => line.textContent ?? '')
+              .join('\n')
+          : (codeBlock.textContent ?? '');
+
+      navigator.clipboard.writeText(textToCopy);
+
+      const copyIcon = button.querySelector(
+        `.${copyIconClass}`
+      ) as SVGElement | null;
+      const checkIcon = button.querySelector(
+        `.${checkIconClass}`
+      ) as SVGElement | null;
+
+      if (copyIcon && checkIcon) {
+        copyIcon.style.display = 'none';
+        checkIcon.style.display = '';
+        button.setAttribute('aria-label', 'Copied!');
+        setTimeout(() => {
+          copyIcon.style.display = '';
+          checkIcon.style.display = 'none';
+          button.setAttribute('aria-label', 'Copy code to clipboard');
+        }, timeout);
+      }
+    };
+
+    wrapper.appendChild(button);
+  }
+
+  const observer = new IntersectionObserver(
+    (entries, obs) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          const pre = entry.target as HTMLPreElement;
+          addCopyButton(pre);
+          obs.unobserve(pre);
+        }
+      }
+    },
+    { rootMargin: '200px' }
+  );
+
+  document.querySelectorAll('pre').forEach(pre => {
+    observer.observe(pre);
+  });
+}
+
+export function setupCopyButtons() {
+  if (typeof window !== 'undefined') {
+    window.addEventListener('DOMContentLoaded', () => {
+      initializeCopyButtons();
+    });
+  }
+}

package/src/utils/generateApiNavData.ts

@@ -0,0 +1,113 @@
+import type { SubNavData } from '../types/subnav.js';
+
+// Interface for API documentation metadata
+export interface ApiDocMetadata {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  sortOrder: number;
+  content?: string; // Raw MDX content for heading extraction
+}
+
+// Interface for navigation items with recursive children
+interface NavItem {
+  id: string;
+  title: string;
+  href: string;
+  children: NavItem[];
+}
+
+// Extract headings from MDX content
+function extractHeadings(content: string) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/gm;
+  const headings: Array<{ level: number; text: string; id: string }> = [];
+  let match;
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    const level = match[1]?.length || 0;
+    const text = match[2]?.trim() || '';
+    // Create a simple ID from the heading text
+    const id = text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .replace(/\s+/g, '-');
+    headings.push({ level, text, id });
+  }
+
+  return headings;
+}
+
+// Convert headings to nested navigation structure
+function headingsToNavItems(
+  headings: Array<{ level: number; text: string; id: string }>
+): NavItem[] {
+  const items: NavItem[] = [];
+  const stack: Array<NavItem & { level: number }> = [];
+
+  headings.forEach(heading => {
+    const item = {
+      id: heading.id,
+      title: heading.text,
+      href: `#${heading.id}`,
+      children: [],
+    };
+
+    // Find the correct parent level
+    while (stack.length > 0) {
+      const lastItem = stack[stack.length - 1];
+      if (lastItem && lastItem.level >= heading.level) {
+        stack.pop();
+      } else {
+        break;
+      }
+    }
+
+    if (stack.length === 0) {
+      // Top level item
+      items.push(item);
+    } else {
+      // Nested item
+      const parent = stack[stack.length - 1];
+      if (parent) {
+        parent.children.push(item);
+      }
+    }
+
+    stack.push({ ...item, level: heading.level });
+  });
+
+  return items;
+}
+
+// Generate navigation data dynamically from API documentation metadata
+export function generateApiDocumentationNavData(
+  apiDocs: ApiDocMetadata[]
+): SubNavData {
+  // Sort by sortOrder
+  const sortedDocs = [...apiDocs].sort((a, b) => a.sortOrder - b.sortOrder);
+
+  // Convert to navigation items with dynamic heading extraction
+  const items = sortedDocs.map(doc => {
+    // Extract headings from content if provided
+    const children = doc.content
+      ? headingsToNavItems(extractHeadings(doc.content))
+      : [];
+
+    return {
+      id: doc.slug,
+      title: doc.title,
+      href: `/api/documentation#${doc.slug}`,
+      children,
+    };
+  });
+
+  return {
+    sections: [
+      {
+        header: 'API Documentation',
+        items,
+      },
+    ],
+  };
+}

package/src/utils/index.ts

@@ -1,2 +1,4 @@
 export * from './getAppUrls.js';
 export * from './navigationControl.js';
+export * from './copyButtonScript.js';
+export * from './generateApiNavData.js';