feat(#3713): add related component cards to component pages

Surface relatedComponents MDX data as mini cards below tabs on each
component page. Cards show thumbnail, name, description, and category
badge. Extract shared thumbnail utility from ComponentsGrid. Fix
relatedComponents data: typo in input, add missing bidirectional
relationships for pagination, drawer, form-item, side-menu, button.

Author: twjeffery

docs/src/components/ComponentsGrid.tsx

@@ -11,6 +11,7 @@
  */
 
 import React, { useState, useMemo, useCallback, useEffect, useRef } from "react";
+import { getThumbnailPath } from "../lib/component-thumbnails";
 import { createPortal } from "react-dom";
 import {
   GoabButton,
@@ -114,27 +115,6 @@ function formatStatus(status: string): string {
   return status.charAt(0).toUpperCase() + status.slice(1);
 }
 
-// Thumbnail filename mapping for slugs that don't match the filename
-const THUMBNAIL_MAP: Record<string, string> = {
-  "app-header": "header",
-  icon: "icons",
-  input: "text-input",
-  "checkbox-list": "checkbox-group",
-  "circular-progress": "circular-progress-indicator",
-  "linear-progress": "linear-progress-indicator",
-  notification: "notification-banner",
-  skeleton: "skeleton-loader",
-  "radio-group": "radio",
-  "file-upload-input": "file-uploader",
-  "link-button": "link",
-  "page-block": "block",
-};
-
-function getThumbnailPath(slug: string): string {
-  const filename = THUMBNAIL_MAP[slug] || slug;
-  return `/images/component-thumbnails/${filename}.svg`;
-}
-
 export function ComponentsGrid({ components }: ComponentsGridProps) {
   // State
   const [searchValue, setSearchValue] = useState("");

docs/src/content/components/button.mdx

@@ -10,6 +10,7 @@ tags:
 relatedComponents:
   - button-group
   - icon-button
+  - link-button
 figmaUrl: https://www.figma.com/design/3pb2IK8s2QUqWieH79KdN7/%E2%9D%96-Component-library-%7C-DDD?node-id=420-6810
 githubUrl: https://github.com/GovAlta/ui-components/issues?q=is%3Aissue+is%3Aopen+label%3AButton
 webComponentTag: goa-button

docs/src/content/components/drawer.mdx

@@ -11,6 +11,7 @@ tags:
   - sidepanel
 relatedComponents:
   - modal
+  - push-drawer
 githubUrl: https://github.com/GovAlta/ui-components/labels/Drawer
 webComponentTag: goa-drawer
 reactClassName: GoabDrawer

docs/src/content/components/form-item.mdx

@@ -11,6 +11,11 @@ relatedComponents:
   - input
   - dropdown
   - checkbox
+  - checkbox-list
+  - date-picker
+  - file-upload-input
+  - radio-group
+  - text-area
 figmaUrl: https://www.figma.com/design/3pb2IK8s2QUqWieH79KdN7/%E2%9D%96-Component-library-%7C-DDD?node-id=27284-300347
 githubUrl: https://github.com/GovAlta/ui-components/labels/Form%20item
 webComponentTag: goa-form-item

docs/src/content/components/input.mdx

@@ -11,7 +11,7 @@ tags:
   - text input
 relatedComponents:
   - form-item
-  - textarea
+  - text-area
   - dropdown
 figmaUrl: https://www.figma.com/design/3pb2IK8s2QUqWieH79KdN7/%E2%9D%96-Component-library-%7C-DDD?node-id=27301-303447
 githubUrl: https://github.com/GovAlta/ui-components/labels/Input
@@ -25,6 +25,7 @@ Capture text input from users in forms.
 ## When to use
 
 Use Input when you need users to enter:
+
 - Short text answers (names, email addresses)
 - Numbers (phone numbers, quantities)
 - Dates and times
@@ -33,6 +34,7 @@ Use Input when you need users to enter:
 ## When not to use
 
 Don't use Input when:
+
 - Users need to enter multiple lines of text (use Textarea)
 - Users need to select from predefined options (use Dropdown or Radio)
 - The input requires complex formatting (consider specialized components)

docs/src/content/components/pagination.mdx

@@ -7,6 +7,9 @@ tags:
   - pager
   - pagination controls
   - structure and navigation
+relatedComponents:
+  - data-grid
+  - table
 figmaUrl: https://www.figma.com/design/3pb2IK8s2QUqWieH79KdN7/%E2%9D%96-Component-library-%7C-DDD?node-id=622-13964
 githubUrl: https://github.com/GovAlta/ui-components/labels/Pagination
 webComponentTag: goa-pagination

docs/src/content/components/side-menu.mdx

@@ -11,6 +11,7 @@ tags:
 relatedComponents:
   - side-menu-group
   - side-menu-heading
+  - work-side-menu
 figmaUrl: https://www.figma.com/design/3pb2IK8s2QUqWieH79KdN7/%E2%9D%96-Component-library-%7C-DDD?node-id=24089-474089
 githubUrl: https://github.com/GovAlta/ui-components/labels/Side%20menu
 webComponentTag: goa-side-menu

docs/src/lib/component-thumbnails.ts

@@ -0,0 +1,20 @@
+// Slug-to-filename mapping for component thumbnails that don't match their slug
+const THUMBNAIL_MAP: Record<string, string> = {
+  "app-header": "header",
+  icon: "icons",
+  input: "text-input",
+  "checkbox-list": "checkbox-group",
+  "circular-progress": "circular-progress-indicator",
+  "linear-progress": "linear-progress-indicator",
+  notification: "notification-banner",
+  skeleton: "skeleton-loader",
+  "radio-group": "radio",
+  "file-upload-input": "file-uploader",
+  "link-button": "link",
+  "page-block": "block",
+};
+
+export function getThumbnailPath(slug: string): string {
+  const filename = THUMBNAIL_MAP[slug] || slug;
+  return `/images/component-thumbnails/${filename}.svg`;
+}

docs/src/pages/components/[slug].astro

@@ -10,10 +10,12 @@ import {
   getComponentApi,
   getGuidanceForComponent,
   getExamplesForComponent,
+  getRelatedComponents,
   getSubcomponents,
   categorizeGuidance,
 } from '../../lib/content-queries';
 import { getComponentConfigurations } from '../../data/configurations';
+import { getThumbnailPath } from '../../lib/component-thumbnails';
 
 // Generate static paths for all components
 export async function getStaticPaths() {
@@ -47,6 +49,9 @@ const componentExamples = await getExamplesForComponent(slug);
 // 5. Get component configurations (if available)
 const configurations = getComponentConfigurations(slug);
 
+// 6. Get visible related components (peers, not subcomponents)
+const relatedComponents = await getRelatedComponents(component.data.relatedComponents ?? []);
+
 // GitHub issues URL for this component
 const githubIssuesUrl = `https://github.com/GovAlta/ui-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22${encodeURIComponent(component.data.name)}%22`;
 
@@ -174,6 +179,39 @@ const v1DocsUrl = `https://v1.design.alberta.ca/components/${slug}`;
       </TabContentWrapper>
     </goa-tab>
   </goa-tabs>
+
+  {relatedComponents.length > 0 && (
+    <section class="related-components">
+      <h2 class="related-heading">Related components</h2>
+      <div class="related-cards">
+        {relatedComponents.map((comp) => {
+          const compSlug = comp.data.slug || comp.slug;
+          return (
+            <a href={`/components/${compSlug}`} class="related-card">
+              <div class="related-card-thumbnail" aria-hidden="true">
+                <img src={getThumbnailPath(compSlug)} alt="" loading="lazy"
+                  onerror="this.style.display='none';this.nextElementSibling.style.display='flex'" />
+                <span class="related-card-thumbnail-fallback">{comp.data.name}</span>
+              </div>
+              <div class="related-card-info">
+                <span class="related-card-name">{comp.data.name}</span>
+                {comp.data.description && (
+                  <p class="related-card-description">{comp.data.description}</p>
+                )}
+                <div class="related-card-badge">
+                  <goa-badge version="2" type="default" emphasis="subtle" icon="false" content={comp.data.category.replace(/-/g, ' ')} />
+                </div>
+              </div>
+            </a>
+          );
+        })}
+      </div>
+    </section>
+  )}
+
+  <goa-spacer version="2" vspacing="xl"></goa-spacer>
+  <goa-divider version="2"></goa-divider>
+  <goa-spacer version="2" vspacing="m"></goa-spacer>
   </div>
   <goa-link size="small" trailingicon="open">
     <a href={v1DocsUrl} target="_blank" rel="noopener noreferrer"
@@ -296,5 +334,95 @@ const v1DocsUrl = `https://v1.design.alberta.ca/components/${slug}`;
     padding-left: var(--goa-space-l);
     max-width: 65ch;
   }
+
+  /* Related Components */
+  .related-components {
+    margin-top: var(--goa-space-2xl);
+    padding-top: var(--goa-space-xl);
+    border-top: 1px solid var(--goa-color-greyscale-200);
+  }
+
+  .related-heading {
+    font: var(--goa-typography-heading-s);
+    color: var(--goa-color-text-default);
+    margin: 0 0 var(--goa-space-m);
+  }
+
+  .related-cards {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(12rem, 15rem));
+    gap: var(--goa-space-m);
+  }
+
+  .related-card {
+    display: flex;
+    flex-direction: column;
+    text-decoration: none;
+    color: inherit;
+  }
+
+  .related-card:focus-visible {
+    outline: 2px solid var(--goa-color-interactive-focus);
+    outline-offset: 2px;
+    border-radius: var(--goa-border-radius-m);
+  }
+
+  .related-card-thumbnail {
+    aspect-ratio: 386 / 256;
+    background: var(--goa-color-greyscale-200);
+    border-radius: var(--goa-border-radius-m);
+    overflow: hidden;
+  }
+
+  .related-card-thumbnail img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+  }
+
+  .related-card-thumbnail-fallback {
+    display: none;
+    width: 100%;
+    height: 100%;
+    align-items: center;
+    justify-content: center;
+    font: var(--goa-typography-heading-xs);
+    color: var(--goa-color-text-secondary);
+    text-align: center;
+    padding: var(--goa-space-s);
+  }
+
+  .related-card-info {
+    display: flex;
+    flex-direction: column;
+    gap: var(--goa-space-2xs);
+    padding-top: var(--goa-space-xs);
+  }
+
+  .related-card-name {
+    font: var(--goa-typography-heading-xs);
+    color: var(--goa-color-interactive-default);
+    text-decoration: none;
+  }
+
+  .related-card:hover .related-card-name {
+    text-decoration: underline;
+  }
+
+  .related-card-description {
+    margin: 0;
+    font: var(--goa-typography-body-s);
+    color: var(--goa-color-text-secondary);
+    line-height: 1.5;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  .related-card-badge {
+    margin-top: var(--goa-space-3xs);
+  }
 </style>