@gsa-tts/graymatter-ui 0.3.23 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsa-tts/graymatter-ui",
-  "version": "0.3.23",
+  "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/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);
+        }
+      }
+    );
+  };
+}