@gsa-tts/graymatter-ui 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsa-tts/graymatter-ui",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -67,8 +67,8 @@
     "typescript": "5.7.3",
     "vite": "^7.3.2",
     "vitest": "^3.2.4",
-    "@gsa-tts/graymatter-eslint": "0.0.2",
     "@gsa-tts/graymatter-typescript-config": "0.0.3",
+    "@gsa-tts/graymatter-eslint": "0.0.2",
     "@gsa-tts/graymatter-vitest-config": "0.0.2"
   },
   "dependencies": {

package/src/component-options/componentOptions.ts

@@ -45,8 +45,8 @@ export const componentOptions: ComponentOptions = {
     header: { theme: 'inverse' },
   },
   partnershipsSubpage: {
-    usaBanner: { theme: 'default' },
-    header: { theme: 'default' },
+    usaBanner: { theme: 'inverse' },
+    header: { theme: 'inverse' },
   },
   website: {
     usaBanner: { theme: 'inverse' },

package/src/components/DesktopSideNav.svelte

@@ -25,6 +25,7 @@
   import MenuIcon from './icons/MenuIcon.svelte';
   import ProfileMenu from './ProfileMenu.svelte';
   import HelpIcon from './icons/HelpIcon.svelte';
+  import Tooltip from './Tooltip.svelte';
 
   let {
     ssrSelectedItem = undefined,
@@ -530,22 +531,23 @@
             class="nav-footer-icon-container"
             part="nav-footer-icon-container"
           >
-            <a
-              class="help-link"
-              class:selected={isHelpSelected()}
-              aria-current={isHelpSelected() ? 'page' : undefined}
-              href={helpUrl()}
-              part="help-link"
-              title="Help"
-              aria-label="Help"
-              onclick={handleHelpClick}
-            >
-              <div class="icon-container" part="help-icon-container">
-                <div class="icon-wrapper">
-                  <HelpIcon isSelected={isHelpSelected()} />
+            <Tooltip text="User Guide" position="right">
+              <a
+                class="help-link"
+                class:selected={isHelpSelected()}
+                aria-current={isHelpSelected() ? 'page' : undefined}
+                href={helpUrl()}
+                part="help-link"
+                aria-label="User Guide"
+                onclick={handleHelpClick}
+              >
+                <div class="icon-container" part="help-icon-container">
+                  <div class="icon-wrapper">
+                    <HelpIcon isSelected={isHelpSelected()} />
+                  </div>
                 </div>
-              </div>
-            </a>
+              </a>
+            </Tooltip>
           </div>
         {/if}
         <div class="nav-footer-profile-container">

package/src/components/MobileTopNav.svelte

@@ -7,6 +7,7 @@
   import Logo from './Logo.svelte';
   import MenuIcon from './icons/MenuIcon.svelte';
   import HelpIcon from './icons/HelpIcon.svelte';
+  import Tooltip from './Tooltip.svelte';
 
   let { profileMenuData, logoLinkUrl, logoLinkLabel, supplementalMenuData } =
     $props();
@@ -141,19 +142,20 @@
   </div>
 
   {#if helpUrl()}
-    <a
-      class="help-button"
-      class:selected={isHelpSelected()}
-      aria-current={isHelpSelected() ? 'page' : undefined}
-      href={helpUrl()}
-      title="Help"
-      aria-label="Help"
-      onclick={handleHelpClick}
-    >
-      <span class="icon-container">
-        <HelpIcon isSelected={isHelpSelected()} />
-      </span>
-    </a>
+    <Tooltip text="User Guide" position="bottom">
+      <a
+        class="help-button"
+        class:selected={isHelpSelected()}
+        aria-current={isHelpSelected() ? 'page' : undefined}
+        href={helpUrl()}
+        aria-label="User Guide"
+        onclick={handleHelpClick}
+      >
+        <span class="icon-container">
+          <HelpIcon isSelected={isHelpSelected()} />
+        </span>
+      </a>
+    </Tooltip>
   {/if}
 
   {#if profileMenuData}

package/src/components/ProfileMenu.svelte

@@ -65,6 +65,8 @@
    * - composed: true (allows event to cross Shadow DOM boundaries)
    */
 
+  import Tooltip from './Tooltip.svelte';
+
   /**
    * Array of menu items to render in the profile menu.
    * Each item: { label: string, icon: string, action: string }
@@ -167,23 +169,28 @@
 </script>
 
 <div style="position: relative; display: inline-block;" data-profile-menu>
-  <button
-    class="user-profile-button"
-    tabindex="0"
-    aria-label={ariaLabel}
-    aria-haspopup="menu"
-    aria-expanded={menuOpen}
-    aria-controls={menuId}
-    onclick={toggleMenu}
-    onblur={handleBlur}
-    bind:this={profileButton}
+  <Tooltip
+    text="Account"
+    position={menuAlign === 'desktop' ? 'right' : 'bottom'}
   >
-    <div class="user-profile-container">
-      <div class="user-profile-icon" part="user-profile-icon">
-        <span class="user-initials">{userMeta?.initials}</span>
+    <button
+      class="user-profile-button"
+      tabindex="0"
+      aria-label={ariaLabel}
+      aria-haspopup="menu"
+      aria-expanded={menuOpen}
+      aria-controls={menuId}
+      onclick={toggleMenu}
+      onblur={handleBlur}
+      bind:this={profileButton}
+    >
+      <div class="user-profile-container">
+        <div class="user-profile-icon" part="user-profile-icon">
+          <span class="user-initials">{userMeta?.initials}</span>
+        </div>
       </div>
-    </div>
-  </button>
+    </button>
+  </Tooltip>
 
   {#if menuOpen}
     <div

package/src/components/Tooltip.svelte

@@ -0,0 +1,288 @@
+<script lang="ts">
+  /**
+   * Tooltip Component
+   *
+   * Ported from usai-frontend's Tooltip:
+   * https://github.com/GSA-TTS/usai-frontend/blob/4050b68aeccf21572c3897a0b2e01c4719b9456a/src/lib/components/shared/Tooltip.svelte
+   * (kept behaviorally identical; renamed `.tooltip*` classes to `.ai-tooltip*`
+   * and `--tooltip-*` vars to `--ai-tooltip-*` to match this package's naming).
+   *
+   * The bubble is portaled to <body> and positioned with `position: fixed` +
+   * JS coordinates so it never gets clipped by an `overflow: hidden` ancestor.
+   *
+   * Appearance is driven entirely by `--ai-tooltip-*` CSS custom properties. To
+   * restyle per app, override those variables at `:root` (or any scope that
+   * reaches <body>) — no component changes needed.
+   *
+   * `children` is a snippet that receives accessibility props. Callers that
+   * don't need them can pass plain content; the extra args are simply ignored.
+   *
+   * Props:
+   * - text: string - Text shown inside the tooltip bubble
+   * - position?: 'top' | 'bottom' | 'left' | 'right' (default: 'top')
+   * - align?: 'center' | 'left' | 'right' (default: 'center')
+   * - showOn?: 'hover' | 'disabled' (default: 'hover')
+   * - disabled?: boolean (default: false)
+   * - showArrow?: boolean (default: false)
+   * - minWidth?: string
+   * - maxWidth?: string
+   * - tooltipId?: string - Auto-generated if omitted
+   * - wrapperClass?: string
+   * - children?: Snippet<[TooltipChildrenProps]>
+   *
+   * Example:
+   * ```svelte
+   * <Tooltip text="Help" position="right">
+   *   <a href="/help" aria-label="Help"><HelpIcon /></a>
+   * </Tooltip>
+   * ```
+   */
+  import { onMount, onDestroy } from 'svelte';
+
+  interface TooltipChildrenProps {
+    disabled: boolean;
+    tooltipId: string;
+    ariaDisabled: 'true' | 'false';
+    ariaDescribedby: string;
+  }
+
+  interface Props {
+    text: string;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    align?: 'center' | 'left' | 'right';
+    showOn?: 'hover' | 'disabled';
+    disabled?: boolean;
+    showArrow?: boolean;
+    minWidth?: string;
+    maxWidth?: string;
+    tooltipId?: string;
+    wrapperClass?: string;
+    children?: import('svelte').Snippet<[TooltipChildrenProps]>;
+  }
+
+  let {
+    text,
+    position = 'top',
+    align = 'center',
+    showOn = 'hover',
+    disabled = false,
+    showArrow = false,
+    minWidth,
+    maxWidth,
+    tooltipId = `tooltip-${Math.random().toString(36).substring(2, 9)}`,
+    wrapperClass = '',
+    children,
+  }: Props = $props();
+
+  let isVisible = $state(false);
+  let tooltipElement: HTMLDivElement;
+  let wrapperElement: HTMLDivElement;
+
+  // Gap in px between the trigger and the bubble.
+  const GAP = 6;
+
+  // 'hover' → always available; 'disabled' → only when the trigger is disabled.
+  let shouldShow = $derived(
+    showOn === 'hover' || (showOn === 'disabled' && disabled)
+  );
+
+  let customStyle = $derived(
+    [minWidth && `min-width: ${minWidth}`, maxWidth && `max-width: ${maxWidth}`]
+      .filter(Boolean)
+      .join('; ') || undefined
+  );
+
+  function updatePosition() {
+    if (!tooltipElement || !wrapperElement || typeof window === 'undefined') {
+      return;
+    }
+
+    const wrap = wrapperElement.getBoundingClientRect();
+    const tip = tooltipElement.getBoundingClientRect();
+    const centerX = wrap.left + wrap.width / 2;
+    const centerY = wrap.top + wrap.height / 2;
+
+    // Clear any previously-set coordinates so only the ones we set below apply.
+    tooltipElement.style.top = '';
+    tooltipElement.style.left = '';
+    tooltipElement.style.transform = 'none';
+
+    let top = 0;
+    let left = 0;
+
+    if (position === 'top' || position === 'bottom') {
+      top =
+        position === 'top' ? wrap.top - tip.height - GAP : wrap.bottom + GAP;
+      if (align === 'left') left = wrap.left;
+      else if (align === 'right') left = wrap.right - tip.width;
+      else left = centerX - tip.width / 2;
+    } else {
+      left =
+        position === 'left' ? wrap.left - tip.width - GAP : wrap.right + GAP;
+      top = centerY - tip.height / 2;
+    }
+
+    tooltipElement.style.top = `${top}px`;
+    tooltipElement.style.left = `${left}px`;
+
+    // Point the arrow at the trigger's center regardless of alignment.
+    if (showArrow && arrowElement) {
+      if (position === 'top' || position === 'bottom') {
+        arrowElement.style.left = `${centerX - left}px`;
+        arrowElement.style.top = '';
+      } else {
+        arrowElement.style.top = `${centerY - top}px`;
+        arrowElement.style.left = '';
+      }
+    }
+  }
+
+  let arrowElement = $state<HTMLDivElement>();
+
+  $effect(() => {
+    if (isVisible && tooltipElement) {
+      requestAnimationFrame(updatePosition);
+    }
+  });
+
+  onMount(() => {
+    if (typeof window !== 'undefined' && tooltipElement) {
+      document.body.appendChild(tooltipElement);
+    }
+  });
+
+  onDestroy(() => {
+    if (typeof window !== 'undefined' && tooltipElement?.parentNode) {
+      tooltipElement.parentNode.removeChild(tooltipElement);
+    }
+  });
+
+  function open() {
+    if (shouldShow) isVisible = true;
+  }
+  function close() {
+    isVisible = false;
+  }
+</script>
+
+<div
+  bind:this={wrapperElement}
+  class={`ai-tooltip-trigger ${wrapperClass}`}
+  role="none"
+  onmouseenter={open}
+  onmouseleave={close}
+  onfocusin={open}
+  onfocusout={close}
+>
+  {@render children?.({
+    disabled,
+    tooltipId,
+    ariaDisabled: disabled ? 'true' : 'false',
+    ariaDescribedby: shouldShow ? tooltipId : '',
+  })}
+</div>
+
+<div
+  bind:this={tooltipElement}
+  id={tooltipId}
+  class={`ai-tooltip pos-${position}`}
+  class:visible={isVisible && shouldShow}
+  style={customStyle}
+  role="tooltip"
+  aria-live="polite"
+>
+  {text}{#if showArrow}<div
+      bind:this={arrowElement}
+      class="ai-tooltip-arrow"
+      aria-hidden="true"
+    ></div>{/if}
+</div>
+
+<style>
+  /*! purgecss start ignore */
+  :root,
+  :host {
+    --ai-tooltip-bg: var(--ai-color-black);
+    --ai-tooltip-fg: var(--ai-color-white);
+    --ai-tooltip-radius: var(--ai-size-8, 0.625rem);
+    --ai-tooltip-padding: var(--ai-size-8, 0.5rem);
+    --ai-tooltip-font-size: 0.8125rem;
+    --ai-tooltip-font-weight: 500;
+    --ai-tooltip-line-height: 1.4;
+    --ai-tooltip-shadow: 0 0.25rem 0.375rem rgba(0, 0, 0, 0.3);
+    --ai-tooltip-max-width: 21.875rem;
+    --ai-tooltip-max-width-mobile: 18rem;
+    --ai-tooltip-arrow-size: 0.3125rem;
+  }
+
+  .ai-tooltip-trigger {
+    position: relative;
+    display: inline-block;
+  }
+
+  .ai-tooltip {
+    position: fixed;
+    top: 0;
+    left: 0;
+    z-index: var(--ai-layer-100);
+    display: none;
+    max-width: var(--ai-tooltip-max-width);
+    padding: var(--ai-tooltip-padding);
+    border-radius: var(--ai-tooltip-radius);
+    background-color: var(--ai-tooltip-bg);
+    box-shadow: var(--ai-tooltip-shadow);
+    color: var(--ai-tooltip-fg);
+    font-size: var(--ai-tooltip-font-size);
+    font-weight: var(--ai-tooltip-font-weight);
+    line-height: var(--ai-tooltip-line-height);
+    pointer-events: none;
+    white-space: normal;
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+  }
+
+  .ai-tooltip.visible {
+    display: block;
+  }
+
+  /* Arrow — JS positions it along the trigger-facing edge; here we only place
+   * it on the correct side and point it in the right direction. */
+  .ai-tooltip-arrow {
+    position: absolute;
+    width: 0;
+    height: 0;
+    border: var(--ai-tooltip-arrow-size) solid transparent;
+  }
+
+  .ai-tooltip.pos-top .ai-tooltip-arrow {
+    top: 100%;
+    transform: translateX(-50%);
+    border-top-color: var(--ai-tooltip-bg);
+  }
+
+  .ai-tooltip.pos-bottom .ai-tooltip-arrow {
+    bottom: 100%;
+    transform: translateX(-50%);
+    border-bottom-color: var(--ai-tooltip-bg);
+  }
+
+  .ai-tooltip.pos-left .ai-tooltip-arrow {
+    left: 100%;
+    transform: translateY(-50%);
+    border-left-color: var(--ai-tooltip-bg);
+  }
+
+  .ai-tooltip.pos-right .ai-tooltip-arrow {
+    right: 100%;
+    transform: translateY(-50%);
+    border-right-color: var(--ai-tooltip-bg);
+  }
+
+  /* Mobile: cap width so long messages stay readable. */
+  @media (max-width: 48rem) {
+    .ai-tooltip {
+      max-width: var(--ai-tooltip-max-width-mobile);
+    }
+  }
+  /*! purgecss end ignore */
+</style>

package/src/components/index.ts

@@ -15,6 +15,7 @@ export { default as ApiDocSubNavMenuItem } from './ApiDocSubNavMenuItem.svelte';
 export { default as PlatformFooter } from './PlatformFooter.svelte';
 export { default as PlatformFooterMenu } from './PlatformFooterMenu.svelte';
 export { default as Modal } from './Modal.svelte';
+export { default as Tooltip } from './Tooltip.svelte';
 
 // Icon Components
 export * from './icons/index.js';