@gsa-tts/graymatter-ui 0.3.22 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsa-tts/graymatter-ui",
-  "version": "0.3.22",
+  "version": "0.4.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -47,7 +47,10 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/svelte": "^5.2.8",
     "@testing-library/user-event": "^14.6.1",
+    "@types/mdast": "^4.0.4",
+    "@types/mdx": "^2.0.13",
     "@types/node": "^22.13.0",
+    "@types/unist": "^3.0.3",
     "@uswds/compile": "1.2.2",
     "@vitest/coverage-istanbul": "^3.2.4",
     "astro": "^5.13.7",
@@ -58,15 +61,16 @@
     "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-vitest-config": "0.0.1",
+    "@gsa-tts/graymatter-eslint": "0.0.2"
   },
   "dependencies": {
     "@fontsource-variable/archivo": "^5.2.6",
     "@fontsource/space-mono": "^5.2.8",
     "@uswds/uswds": "3.12.0",
     "slugify": "^1.6.6",
+    "unist-util-visit": "^5.0.0",
     "@gsa-tts/graymatter-style-tokens": "0.3.17"
   },
   "scripts": {

package/src/astro-config/index.ts

@@ -6,6 +6,7 @@ import purgecss from 'astro-purgecss';
 import { join as pathJoin, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { normalizeTrailingSlash } from '../helpers/string-formatters';
+import { remarkWrapPre } from '../utils/remarkPlugins.js';
 
 interface AstroConfigOptions {
   appDir: string;
@@ -95,11 +96,32 @@ export function createAstroConfig({
       }
     : baseViteConfig;
 
+  // Base markdown config with remarkWrapPre plugin for code block wrapping
+  const baseMarkdownConfig = {
+    remarkPlugins: [remarkWrapPre],
+  };
+
+  // Merge markdown config if provided in overrides
+  const mergedMarkdownConfig = overrides.markdown
+    ? {
+        ...baseMarkdownConfig,
+        ...(overrides.markdown as Record<string, unknown>),
+        remarkPlugins: [
+          ...baseMarkdownConfig.remarkPlugins,
+          ...((overrides.markdown as { remarkPlugins?: unknown[] })
+            .remarkPlugins || []),
+        ],
+      }
+    : baseMarkdownConfig;
+
   return defineConfig({
     base: normalizeTrailingSlash(process.env.BASEURL || ''),
     integrations: process.env.VITEST
       ? []
       : overrides.integrations || baseIntegrations,
+    // Markdown config with remark plugins (applies to all markdown/MDX processing)
+    markdown: mergedMarkdownConfig as typeof baseMarkdownConfig &
+      typeof overrides.markdown,
     experimental: {
       // Astro Experimental Fonts API for managing custom fonts
       fonts: [
@@ -134,7 +156,7 @@ export function createAstroConfig({
     // Spread other overrides (excluding the ones we handle specifically)
     ...Object.fromEntries(
       Object.entries(overrides).filter(
-        ([key]) => !['integrations', 'vite'].includes(key)
+        ([key]) => !['integrations', 'vite', 'markdown'].includes(key)
       )
     ),
   });

package/src/components/PlatformFooter.svelte

@@ -0,0 +1,149 @@
+<script lang="ts">
+  import { siteName } from '@gsa-tts/graymatter-ui/constants';
+  import { getUrlFromBase } from '@gsa-tts/graymatter-ui/helpers';
+  import Logo from '@gsa-tts/graymatter-ui/components/Logo.svelte';
+  import PlatformFooterMenu from './PlatformFooterMenu.svelte';
+  import Button from '@gsa-tts/graymatter-ui/components/Button.svelte';
+
+  /**
+   * PlatformFooter Component
+   *
+   * The main footer component for the platform, featuring:
+   * - Agency branding and logo
+   * - Call-to-action section
+   * - Footer navigation menus
+   *
+   * Props:
+   * - menus?: FooterMenu[] (optional array of footer menus)
+   * - ctaHeading?: string (optional CTA heading text)
+   * - ctaButtonText?: string (optional CTA button text)
+   * - ctaButtonHref?: string (optional CTA button URL)
+   * - showCta?: boolean (whether to show the CTA section)
+   * - class?: string (optional additional CSS classes)
+   *
+   * Example:
+   * ```svelte
+   * <PlatformFooter {menus} />
+   * ```
+   */
+  interface FooterLink {
+    title: string;
+    url: string;
+  }
+
+  interface FooterMenu {
+    title: string;
+    items: Array<FooterLink>;
+  }
+
+  interface Props {
+    menus?: FooterMenu[];
+    ctaHeading?: string;
+    ctaButtonText?: string;
+    ctaButtonHref?: string;
+    showCta?: boolean;
+    class?: string;
+  }
+
+  let {
+    menus = [],
+    ctaHeading = 'Get your team started today.',
+    ctaButtonText = 'Partnerships',
+    ctaButtonHref = getUrlFromBase('/partnerships'),
+    showCta = true,
+    class: className = '',
+  }: Props = $props();
+</script>
+
+<footer class="ai-footer {className}">
+  <div class="ai-maxw-widescreen grid-container">
+    {#if showCta}
+      <section
+        class="usa-section ai-section ai-footer-top"
+        aria-labelledby="ai-footer-cta"
+      >
+        <div
+          class="usa-identifier__identity ai-identifier__identity"
+          aria-label="Agency description"
+        >
+          <p
+            class="usa-identifier__identity-domain ai-identifier__identity-domain"
+          >
+            <a href={getUrlFromBase('/')} aria-label="Home">
+              <Logo
+                aria-label={siteName}
+                isInverted={true}
+                showServiceMark={true}
+                width={68}
+              />
+            </a>
+          </p>
+          <p class="usa-identifier__identity-disclaimer text-normal">
+            An official website of the U.S.
+            <a class="ai-footer-link" href="https://www.gsa.gov/"
+              >General Services Administration</a
+            >
+          </p>
+        </div>
+        <p class="ai-footer-cta__heading" id="ai-footer-cta">
+          {ctaHeading}
+        </p>
+        <div class="ai-footer-cta__buttons">
+          <Button href={ctaButtonHref} theme="inverted" variant="secondary">
+            {ctaButtonText}
+          </Button>
+        </div>
+      </section>
+    {/if}
+
+    {#if menus.length > 0}
+      <section class="usa-section ai-section">
+        <div class="grid-row grid-gap">
+          <div class="tablet:grid-col-12">
+            <nav aria-label="Footer navigation">
+              <div class="grid-row grid-gap">
+                {#each menus as menu}
+                  <div class="tablet:grid-col-4">
+                    <PlatformFooterMenu content={menu} />
+                  </div>
+                {/each}
+              </div>
+            </nav>
+          </div>
+        </div>
+      </section>
+    {/if}
+  </div>
+</footer>
+
+<style>
+  .ai-footer-link {
+    color: var(--ai-footer-color-link-rest);
+  }
+
+  .ai-footer-link:hover {
+    color: var(--ai-footer-color-link-hover);
+  }
+
+  .ai-footer {
+    background: var(--ai-footer-color-background);
+    color: var(--ai-footer-color-text);
+  }
+
+  .ai-footer-cta__heading {
+    margin-block: 0 var(--ai-size-24);
+  }
+
+  .ai-footer-top {
+    border-bottom: 1px solid var(--ai-footer-color-separator);
+  }
+
+  .ai-identifier__identity {
+    padding-bottom: var(--ai-layout-section-spacing-y);
+  }
+
+  .ai-identifier__identity-domain {
+    color: var(--ai-footer-color-text);
+    font-weight: 600;
+  }
+</style>

package/src/components/PlatformFooterMenu.svelte

@@ -0,0 +1,80 @@
+<script lang="ts">
+  import { v4 as uuidv4 } from 'uuid';
+
+  /**
+   * PlatformFooterMenu Component
+   *
+   * A footer menu component that displays a title and list of links.
+   * Used within the PlatformFooter component to create organized footer navigation.
+   *
+   * Props:
+   * - content: FooterMenu object containing title and items
+   * - class?: string (optional additional CSS classes)
+   *
+   * Example:
+   * ```svelte
+   * <PlatformFooterMenu content={menuData} />
+   * ```
+   */
+  interface FooterLink {
+    title: string;
+    url: string;
+  }
+
+  interface FooterMenu {
+    title: string;
+    items: Array<FooterLink>;
+  }
+
+  interface Props {
+    content: FooterMenu;
+    class?: string;
+  }
+
+  let { content, class: className = '' }: Props = $props();
+
+  // Generate unique ID for accessibility
+  const menuLabel = `platform-footer-${uuidv4()}`;
+</script>
+
+<div class={className}>
+  <p id={menuLabel}>{content.title}</p>
+  <ul class="add-list-reset" aria-labelledby={menuLabel}>
+    {#each content.items as item}
+      <li>
+        <a href={item.url}>{item.title}</a>
+      </li>
+    {/each}
+  </ul>
+</div>
+
+<style>
+  p {
+    color: var(--ai-footer-color-text-muted);
+    margin-top: 0;
+    margin-bottom: var(--ai-size-16);
+  }
+
+  ul {
+    margin-bottom: var(--ai-size-32);
+  }
+
+  li {
+    display: block;
+    margin-bottom: var(--ai-size-16);
+  }
+
+  a {
+    color: var(--ai-footer-color-link-rest);
+    display: block;
+    text-decoration: none;
+  }
+
+  a:hover {
+    color: var(--ai-footer-color-link-hover);
+  }
+
+  a:is(:focus, :hover, :active) {
+    text-decoration: underline;
+  }
+</style>

package/src/components/index.ts

@@ -12,6 +12,8 @@ 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';
+export { default as PlatformFooter } from './PlatformFooter.svelte';
+export { default as PlatformFooterMenu } from './PlatformFooterMenu.svelte';
 
 // Icon Components
 export * from './icons/index.js';

package/src/layouts/DocsLayout.astro

@@ -3,6 +3,9 @@ import GlobalAppLayout from './GlobalAppLayout.astro';
 import ApiDocSubNavMenu from '../components/ApiDocSubNavMenu.svelte';
 import NavigationInitializer from '../components/NavigationInitializer.svelte';
 import { getBaseUrl } from '../helpers';
+import { getCollection } from 'astro:content';
+import { render } from 'astro:content';
+import { generateApiDocumentationNavData } from '../utils/generateApiNavData.js';
 
 const gtmID = import.meta.env.PUBLIC_GTM_ID;
 const {
@@ -11,12 +14,43 @@ const {
   description,
   openGraphImage,
   showAppIcons = false,
-  subNavData = null,
   disableCodeCopyButtons = false,
-  postItems = null,
   profileMenuData = null,
   hideDiscover = true,
+  contentCustomization = undefined,
 } = Astro.props;
+
+// Handle ALL logic internally
+// Get collection
+const rawPosts = await getCollection('apiDocumentation');
+
+// Sort by sortOrder
+const sortedPosts = [...rawPosts].sort(
+  (a, b) => a.data.sortOrder - b.data.sortOrder
+);
+
+// Render posts
+const postItems = await Promise.all(
+  sortedPosts.map(async post => {
+    const { Content } = await render(post);
+    return {
+      ...post,
+      ContentComponent: Content,
+    };
+  })
+);
+
+// Generate navigation data
+const apiDocsMetadata = sortedPosts.map(doc => ({
+  id: doc.id,
+  slug: doc.id,
+  title: doc.data.title,
+  description: doc.data.description,
+  sortOrder: doc.data.sortOrder,
+  content: doc.body || '',
+}));
+
+const subNavData = generateApiDocumentationNavData(apiDocsMetadata);
 ---
 
 <GlobalAppLayout
@@ -55,7 +89,7 @@ const {
     <article class="article-body">
       <h1 class="page-title">API Documentation</h1>
 
-      <!-- Render postItems if provided -->
+      <!-- Render postItems -->
       {
         postItems &&
           postItems.map((post: any) => (
@@ -80,6 +114,116 @@ const {
     </script>
   )
 }
+<!-- Client-side content replacement -->
+<script is:inline define:vars={{ contentCustomization }}>
+  if (!contentCustomization) {
+    // no customization provided
+  } else {
+    const customization = contentCustomization;
+    function escapeHtml(input) {
+      return String(input)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    }
+    function linkify(input) {
+      // Preserve markdown links [label](url) using placeholders
+      const placeholders = [];
+      const withPlaceholders = String(input).replace(
+        /\[([^\]]+)\]\(((https?:\/\/|www\.)[^\s)]+)\)/gi,
+        (m, label, href) => {
+          const safeLabel = escapeHtml(label);
+          const normalizedHref = href.startsWith('http')
+            ? href
+            : `https://${href}`;
+          const safeHref = escapeHtml(normalizedHref);
+          const html = `<a href="${safeHref}" target="_blank" rel="noopener noreferrer">${safeLabel}</a>`;
+          const token = `__LINK_PLACEHOLDER_${placeholders.length}__`;
+          placeholders.push(html);
+          return token;
+        }
+      );
+
+      // Escape remaining content
+      const escaped = escapeHtml(withPlaceholders);
+
+      // Linkify emails
+      const withEmails = escaped.replace(
+        /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi,
+        email => {
+          return `<a href="mailto:${email}">${email}</a>`;
+        }
+      );
+      // Linkify bare URLs (http/https and www.)
+      const urlRegex = /\b((https?:\/\/)[^\s)]+|www\.[^\s)]+)\b/gi;
+      const withUrls = withEmails.replace(urlRegex, raw => {
+        const href = raw.startsWith('http') ? raw : `https://${raw}`;
+        return `<a href="${href}" target="_blank" rel="noopener noreferrer">${raw}</a>`;
+      });
+
+      // Restore placeholders
+      return withUrls.replace(
+        /__LINK_PLACEHOLDER_(\d+)__/g,
+        (m, idx) => placeholders[Number(idx)]
+      );
+    }
+
+    function replaceContent() {
+      // For endpoints
+      if (customization.endpointsMessage) {
+        const heading = document.getElementById('endpoints');
+        if (heading) {
+          const section = heading.closest('div');
+          if (section) {
+            const paragraphs = section.querySelectorAll('p');
+            paragraphs.forEach(p => {
+              if (
+                p.textContent?.includes(
+                  'API endpoints will be available when you login'
+                )
+              ) {
+                p.innerHTML = linkify(customization.endpointsMessage);
+              }
+            });
+          }
+        }
+      }
+
+      // For getting-started
+      if (customization.authMessage) {
+        const heading = document.getElementById('getting-started');
+        if (heading) {
+          const section = heading.closest('div');
+          if (section) {
+            const paragraphs = section.querySelectorAll('p');
+            paragraphs.forEach(p => {
+              const text = p.textContent || '';
+              if (text.includes('All API requests require an API key')) {
+                const authPattern =
+                  /All API requests require an API key\. Upon authentication,.*?available\./s;
+                if (authPattern.test(text)) {
+                  p.innerHTML = linkify(customization.authMessage);
+                }
+              }
+            });
+          }
+        }
+      }
+    }
+
+    // Run synchronously before paint
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', replaceContent, {
+        once: true,
+      });
+    } else {
+      replaceContent();
+    }
+    setTimeout(replaceContent, 0);
+  }
+</script>
 
 <style>
   body {

package/src/utils/apiDocumentationConfig.ts

@@ -0,0 +1,35 @@
+import { glob } from 'astro/loaders';
+
+/**
+ * Creates the API documentation collection for Astro apps.
+ *
+ * @example
+ * ```typescript
+ * import { defineCollection, z } from 'astro:content';
+ * import { createApiDocumentationCollection } from '@gsa-tts/graymatter-ui/utils/apiDocumentationConfig.js';
+ *
+ * export const collections = {
+ *   apiDocumentation: createApiDocumentationCollection({ defineCollection, z }),
+ * };
+ * ```
+ */
+export function createApiDocumentationCollection({
+  defineCollection,
+  z,
+}: {
+  defineCollection: typeof import('astro:content').defineCollection;
+  z: typeof import('astro:content').z;
+}) {
+  return defineCollection({
+    loader: glob({
+      base: './node_modules/@gsa-tts/graymatter-ui/src/content/api',
+      pattern: '**/*.{md,mdx}',
+    }),
+    schema: () =>
+      z.object({
+        title: z.string(),
+        description: z.string(),
+        sortOrder: z.number(),
+      }),
+  });
+}

package/src/utils/index.ts

@@ -1,3 +1,7 @@
+// Note: Do not export remarkPlugins.js or apiDocumentationConfig.js from here.
+// These are Astro-specific utilities that should only be imported directly by their specific paths.
+// Exporting them would cause bundling issues for Svelte/SvelteKit apps that import from this barrel export.
+
 export * from './getAppUrls.js';
 export * from './navigationControl.js';
 export * from './copyButtonScript.js';

package/src/utils/remarkPlugins.ts

@@ -0,0 +1,55 @@
+import { visit } from 'unist-util-visit';
+import type { Root } from 'mdast';
+import type { Code } from 'mdast';
+import type { Parent } from 'unist';
+
+/**
+ * MDX-specific node type for JSX flow elements
+ */
+interface MdxJsxFlowElement extends Parent {
+  type: 'mdxJsxFlowElement';
+  name: string;
+  attributes?: Array<{
+    type: 'mdxJsxAttribute';
+    name: string;
+    value: string;
+  }>;
+}
+
+/**
+ * Remark plugin to wrap code blocks in a div with className 'ai-code-block-wrapper'
+ *
+ * This enables the copy button functionality for code blocks in documentation.
+ *
+ * @returns A remark plugin function
+ */
+export function remarkWrapPre() {
+  return (tree: Root) => {
+    visit(
+      tree,
+      'code',
+      (node: Code, index: number | undefined, parent: Parent | undefined) => {
+        if (
+          node.type === 'code' &&
+          typeof index === 'number' &&
+          parent &&
+          'children' in parent
+        ) {
+          const wrapper: MdxJsxFlowElement = {
+            type: 'mdxJsxFlowElement',
+            name: 'div',
+            attributes: [
+              {
+                type: 'mdxJsxAttribute',
+                name: 'className',
+                value: 'ai-code-block-wrapper',
+              },
+            ],
+            children: [node],
+          };
+          parent.children.splice(index, 1, wrapper);
+        }
+      }
+    );
+  };
+}