@gsa-tts/graymatter-ui 0.3.1 → 0.3.3

package/README.md

@@ -1,16 +1,18 @@
 # @gsa-tts/graymatter-ui
 
+A comprehensive UI component library built with Svelte 5, providing reusable components, layouts, and utilities for modern web applications.
+
 ## Package Responsibilities
 
-The GrayMatter UI package (`@gsa-tts/graymatter-ui`) is a UI component library. It provides reusable UI components, layouts, styles, and utilities.
+The GrayMatter UI package (`@gsa-tts/graymatter-ui`) is a UI component library that provides:
 
 ### Primary Responsibilities:
 
-- Provide a comprehensive set of reusable UI components
-- Implement the design system using the tokens from `@gsa-tts/graymatter-style-tokens`
-- Provide layouts for consistent page structures
-- Offer utility functions for UI-related operations
-- Export components as both Svelte components and web components
+- **Reusable UI Components** - A comprehensive set of accessible, customizable components
+- **Design System Implementation** - Built using tokens from `@gsa-tts/graymatter-style-tokens`
+- **Layout Components** - Consistent page structures and navigation patterns
+- **Utility Functions** - Helper functions for UI-related operations
+- **Cross-Framework Support** - Components available as both Svelte components and web components
 
 ### Package Boundaries:
 
@@ -21,91 +23,188 @@ The GrayMatter UI package (`@gsa-tts/graymatter-ui`) is a UI component library.
 - **SHOULD NOT** contain data fetching or API integration code
 - **SHOULD NOT** depend on application-specific packages
 
+## Installation
+
+```bash
+npm install @gsa-tts/graymatter-ui @gsa-tts/graymatter-style-tokens
+```
+
+**Note:** The `@gsa-tts/graymatter-style-tokens` package is required for proper styling and design tokens.
+
 ## Usage
 
 The UI package can be used in two ways:
 
-1. As Svelte components (for Svelte/Astro applications)
-2. As web components (for any framework or vanilla JS)
+### 1. Svelte Components (for Svelte/Astro applications)
 
-## Component Documentation
+```svelte
+<script>
+  import { DesktopSideNav, ProfileMenu } from '@gsa-tts/graymatter-ui';
+</script>
+
+<DesktopSideNav showAppIcons={true} ssrSelectedItem="api">
+  <!-- Sub navigation content -->
+</DesktopSideNav>
+```
+
+### 2. Web Components (for any framework or vanilla JS)
+
+```html
+<graymatter-desktop-side-nav show-app-icons="true" ssr-selected-item="api">
+  <!-- Sub navigation content -->
+</graymatter-desktop-side-nav>
+```
+
+## Navigation URL Configuration
+
+Navigation components (`DesktopSideNav`, `MobileBottomNav`) support flexible URL configuration:
+
+### Option 1: Environment Variables (Recommended)
+```bash
+# .env
+PUBLIC_CHAT_URL=https://your-chat-app.com
+PUBLIC_CONSOLE_URL=https://your-console-app.com
+PUBLIC_API_URL=https://your-api-app.com
+PUBLIC_DISCOVER_URL=https://your-discover-page.com
+```
 
-### ProfileMenu Component - Event-Driven Architecture
-
-The ProfileMenu component uses a custom event system to handle menu item actions, avoiding issues with function serialization in Astro apps.
-
-### Usage
-
-#### 1. Define Menu Items with Action Strings
-
-```typescript
-const profileMenuData = {
-  userMeta: {
-    initials: 'ZW',
-  },
-  menuItems: [
-    {
-      label: 'Settings',
-      icon: '/path/to/icon.svg',
-      action: 'settings', // String identifier
-    },
-    {
-      label: 'Log out',
-      icon: '/path/to/icon.svg',
-      action: 'logout', // String identifier
-    },
-  ],
-};
+### Option 2: Component Props (Override Environment)
+```svelte
+<DesktopSideNav 
+  showAppIcons={true}
+  apiUrl="https://custom-api.com"
+  chatUrl="https://custom-chat.com"
+  consoleUrl="https://custom-console.com"
+  discoverUrl="https://custom-discover.com"
+>
+  <!-- Sub navigation content -->
+</DesktopSideNav>
 ```
 
-#### 2. Listen for Profile Menu Actions
+### Option 3: Mixed Approach
+```svelte
+<DesktopSideNav 
+  showAppIcons={true}
+  apiUrl="https://custom-api.com"
+  <!-- chatUrl, consoleUrl, discoverUrl will use environment variables -->
+>
+  <!-- Sub navigation content -->
+</DesktopSideNav>
+```
+
+**Priority Order:** Component props → Environment variables → Fallback (`#`)
+
+## Available Components
+
+### Web Components (Universal - Any Framework)
+
+All components with `.webcomponent.svelte` extension are available as web components:
 
-```typescript
-// In your app's main layout or component
-window.addEventListener('profileMenuAction', (event) => {
-  const { action, userMeta, timestamp } = event.detail;
+- `graymatter-desktop-side-nav` - Desktop sidebar navigation
+- `graymatter-mobile-top-nav` - Mobile header navigation  
+- `graymatter-mobile-bottom-nav` - Mobile bottom navigation bar
+- `graymatter-mobile-side-menu` - Mobile slide-out navigation menu
+- `graymatter-desktop-header` - Desktop header component
+- `graymatter-button` - Accessible button component
+- `graymatter-logo` - Brand logo component
+
+### Svelte 5 Components
+
+Available for Svelte, SvelteKit, and Astro applications:
+
+```javascript
+import { 
+  // Navigation Components
+  DesktopSideNav,
+  MobileTopNav,
+  MobileBottomNav,
+  MobileSideMenu,
+  DesktopHeader,
+  
+  // UI Components
+  Button,
+  Logo,
+  ProfileMenu,
+  
+  // Utility Components
+  UsaBanner,
+  UsaSkipNav,
+  NavigationInitializer,
   
-  switch (action) {
-    case 'settings':
-      // Handle settings action
-      console.log('Settings clicked for user:', userMeta);
-      break;
-    case 'logout':
-      // Handle logout action
-      console.log('Logout clicked for user:', userMeta);
-      break;
-    default:
-      console.warn('Unknown profile menu action:', action);
-  }
-});
+  // Icon Components
+  // (all icons from ./icons/index.js)
+} from '@gsa-tts/graymatter-ui/components';
 ```
 
-### Event Details
+### Astro Components
+
+Available for Astro applications:
+
+```javascript
+import { 
+  Head,
+  BaseLayout,
+  GlobalAppLayout
+} from '@gsa-tts/graymatter-ui/layouts';
+```
+
+## Component Categories
+
+### Navigation Components
+- **DesktopSideNav** - Desktop sidebar navigation with external control support
+- **MobileTopNav** - Mobile header navigation
+- **MobileBottomNav** - Mobile bottom navigation bar
+- **MobileSideMenu** - Mobile slide-out navigation menu
 
-The `profileMenuAction` event includes:
+### Layout Components
+- **GlobalAppLayout** - Main application layout wrapper
+- **BaseLayout** - Base page layout structure
 
-- **action**: String identifier for the menu item action
-- **userMeta**: User metadata object
-- **timestamp**: When the action was triggered
+### UI Components
+- **ProfileMenu** - User profile dropdown menu with event-driven actions
+- **Button** - Accessible button component with multiple variants
+- **Logo** - Brand logo component
+
+### Utility Components
+- **UsaBanner** - Government banner component
+- **UsaSkipNav** - Skip navigation link for accessibility
+
+## Key Features
+
+### Event-Driven Architecture
+Many components use custom events for external control and communication:
+
+- **DesktopSideNav** - External control via `graymatter-desktop-nav-control` events
+- **ProfileMenu** - Action handling via `profileMenuAction` events
+
+### Cross-App Communication
+Components support communication between different applications:
+
+- **Navigation Control** - Control desktop navigation from external apps
+- **Event Bubbling** - Events work across Shadow DOM boundaries
+
+### Accessibility
+- **WCAG 2.1 AA Compliant** - Built with accessibility in mind
+- **Keyboard Navigation** - Full keyboard support
+- **Screen Reader Support** - Proper ARIA labels and roles
+
+## Component Documentation
 
-### Benefits
+### Navigation Control
+- **[DesktopSideNav External Control](./docs/NAVIGATION_CONTROL.md)** - Event-based control system for desktop navigation
 
-- ✅ **No serialization issues** - Works with both Astro and Svelte apps
-- ✅ **Type safe** - No runtime function evaluation
-- ✅ **Secure** - No `new Function()` usage
-- ✅ **Debuggable** - Clear event flow
-- ✅ **Flexible** - Each app can handle actions differently
-- ✅ **Shadow DOM compatible** - Events bubble through web component boundaries
+### Component-Specific Documentation
+- **[ProfileMenu Component](./docs/PROFILE_MENU.md)** - Event-driven profile menu with action handling
 
-### Shadow DOM & Web Component Support
+## Framework Support
 
-The ProfileMenu component is designed to work in both regular DOM and Shadow DOM contexts:
+- **Svelte 5** - Native Svelte components
+- **Astro** - Full support with client-side hydration
+- **React/Vue/Angular** - Via web components
+- **Vanilla JavaScript** - Via web components
 
-- **Regular DOM**: Events bubble up to `window` as expected
-- **Shadow DOM**: Events are configured with `bubbles: true` and `composed: true` to cross Shadow DOM boundaries
-- **Web Components**: Events are dispatched from the component element to ensure proper bubbling
+## Browser Support
 
-This makes the component compatible with:
-- Astro apps using the component directly
-- Svelte apps using the web component version
-- Any other framework using the web component 
+- **Modern Browsers** - Chrome, Firefox, Safari, Edge (latest 2 versions)
+- **Web Components** - Native support or polyfill required
+- **Custom Events** - Native support in all modern browsers