@gsa-tts/graymatter-ui 1.3.0 → 2.0.0

package/README.md

@@ -1,26 +1,28 @@
 # @gsa-tts/graymatter-ui
 
-A comprehensive UI component library built with Svelte 5, providing reusable components, layouts, and utilities for modern web applications.
+A UI component library built with Svelte 5, providing reusable components,
+styles, and utilities for the USAi applications.
 
 ## Package Responsibilities
 
-The GrayMatter UI package (`@gsa-tts/graymatter-ui`) is a UI component library that provides:
+The GrayMatter UI package (`@gsa-tts/graymatter-ui`) provides:
 
 ### Primary Responsibilities:
 
-- **Reusable UI Components** - A comprehensive set of accessible, customizable components
+- **Reusable UI Components** - A set of accessible, customizable Svelte 5 components
 - **Design System Implementation** - Built using tokens from `@gsa-tts/graymatter-style-tokens`
-- **Layout Components** - Consistent page structures and navigation patterns
+- **Shared Styles** - Global and component CSS, plus compiled USWDS assets
 - **Utility Functions** - Helper functions for UI-related operations
-- **Cross-Framework Support** - Components available as both Svelte components and web components
 
 ### Package Boundaries:
 
-- **SHOULD** contain UI components, layouts, and styles
+- **SHOULD** contain Svelte UI components, styles, and utilities
 - **SHOULD** consume design tokens from the style-tokens package
-- **SHOULD** be framework-agnostic where possible (via web components)
 - **SHOULD NOT** contain application-specific business logic
 - **SHOULD NOT** contain data fetching or API integration code
+- **SHOULD NOT** contain application layouts or framework configuration
+  (e.g. Astro layouts / config live in the consuming app — see the `apps/site`
+  `src/layouts/`)
 - **SHOULD NOT** depend on application-specific packages
 
 ## Installation
@@ -29,13 +31,12 @@ The GrayMatter UI package (`@gsa-tts/graymatter-ui`) is a UI component library t
 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.
+**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. Svelte Components (for Svelte/Astro applications)
+### Svelte Components
 
 ```svelte
 <script>
@@ -47,31 +48,30 @@ The UI package can be used in two ways:
 </DesktopSideNav>
 ```
 
-### 2. Utility Functions
-
-For utility functions like navigation control, use the dedicated `/utils` import path:
-
-```javascript
-// ✅ Recommended for Svelte-only projects
-import { toggleNavigation } from '@gsa-tts/graymatter-ui/utils';
+Individual components can also be imported by path, which is useful for
+server-rendered/island setups such as Astro:
 
-// ❌ Avoid this in Svelte-only projects (may cause build issues)
-import { toggleNavigation } from '@gsa-tts/graymatter-ui';
+```svelte
+<script>
+  import Button from '@gsa-tts/graymatter-ui/components/Button.svelte';
+</script>
 ```
 
-**Note:** The `/utils` path only exports TypeScript files and doesn't pull in Astro components, making it safe for Svelte-only projects that don't have Astro configured in their build system.
+### Utility Functions
 
-### 3. Web Components (for any framework or vanilla JS)
+Utility functions are available via the dedicated `/utils` import path:
 
-```html
-<graymatter-desktop-side-nav show-app-icons="true" ssr-selected-item="api">
-  <!-- Sub navigation content -->
-</graymatter-desktop-side-nav>
+```javascript
+import { toggleNavigation } from '@gsa-tts/graymatter-ui/utils';
 ```
 
+**Note:** The `/utils` path only exports plain TypeScript, so it never pulls in
+Svelte components — safe to use from non-Svelte code.
+
 ## Navigation URL Configuration
 
-Navigation components (`DesktopSideNav`, `MobileBottomNav`) support flexible URL configuration via props:
+Navigation components (`DesktopSideNav`, `MobileBottomNav`) support flexible URL
+configuration via props:
 
 ### Option 1: Component Props (Recommended)
 ```svelte
@@ -105,11 +105,13 @@ Navigation components (`DesktopSideNav`, `MobileBottomNav`) support flexible URL
 </DesktopSideNav>
 ```
 
-**Fallback Behavior:** When no URL is provided for a navigation item, it will use `#` as the href, preventing navigation and keeping users on the current page.
+**Fallback Behavior:** When no URL is provided for a navigation item, it will use
+`#` as the href, preventing navigation and keeping users on the current page.
 
 ### Discover Icon Control
 
-The discover icon can be conditionally shown/hidden using the `hideDiscover` prop for both desktop and mobile navigation:
+The discover icon can be conditionally shown/hidden using the `hideDiscover` prop
+for both desktop and mobile navigation:
 
 ```svelte
 <!-- Hide discover icon (default) -->
@@ -121,25 +123,13 @@ The discover icon can be conditionally shown/hidden using the `hideDiscover` pro
 <MobileBottomNav showAppIcons={true} hideDiscover={false}>
 ```
 
-**Note:** The discover icon is hidden by default (`hideDiscover={true}`) since the discover page may not be available in all deployments. This gives you control over when to enable the discover functionality across all consuming applications.
+**Note:** The discover icon is hidden by default (`hideDiscover={true}`) since the
+discover page may not be available in all deployments. This gives you control over
+when to enable the discover functionality across all consuming applications.
 
 ## Available Components
 
-### Web Components (Universal - Any Framework)
-
-All components with `.webcomponent.svelte` extension are available as web components:
-
-- `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:
+Import from `@gsa-tts/graymatter-ui/components` (or the package root):
 
 ```javascript
 import { 
@@ -166,18 +156,6 @@ import {
 } from '@gsa-tts/graymatter-ui/components';
 ```
 
-### Astro Components
-
-Available for Astro applications:
-
-```javascript
-import { 
-  Head,
-  BaseLayout,
-  GlobalAppLayout
-} from '@gsa-tts/graymatter-ui/layouts';
-```
-
 ## Component Categories
 
 ### Navigation Components
@@ -185,11 +163,7 @@ import {
 - **MobileTopNav** - Mobile header navigation
 - **MobileBottomNav** - Mobile bottom navigation bar
 - **MobileSideMenu** - Mobile slide-out navigation menu
-
-### Layout Components
-- **GlobalAppLayout** - Main application layout wrapper
-- **BaseLayout** - Base page layout structure
-- **DocsLayout** - Documentation layout with dynamic navigation (Astro only)
+- **DesktopHeader** - Desktop header component
 
 ### UI Components
 - **ProfileMenu** - User profile dropdown menu with event-driven actions
@@ -200,6 +174,7 @@ import {
 ### Utility Components
 - **UsaBanner** - Government banner component
 - **UsaSkipNav** - Skip navigation link for accessibility
+- **NavigationInitializer** - Initializes navigation state on the client
 
 ### Utility Functions
 Available via the `/utils` import path:
@@ -219,11 +194,17 @@ 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
 
+Navigation-control events (`graymatter-desktop-nav-control`) are dispatched
+directly on `window` with `bubbles: true`. `ProfileMenu` dispatches
+`profileMenuAction` from its component element with `bubbles: true` and
+`composed: true` (so it crosses Shadow DOM boundaries). Either event can be
+observed on `window`.
+
 ### 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
+- **Custom Events** - Decoupled action handling without prop drilling
 
 ### Accessibility
 - **WCAG 2.1 AA Compliant** - Built with accessibility in mind
@@ -237,40 +218,27 @@ Detailed documentation for specific components is available in the package:
 - **[NAVIGATION_CONTROL.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/NAVIGATION_CONTROL.md)** - DesktopSideNav external control system with event-based API
 - **[PROFILE_MENU.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/PROFILE_MENU.md)** - ProfileMenu component usage and event handling
 - **[MODAL_COMPONENTS.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/MODAL_COMPONENTS.md)** - Modal component with examples, API reference, and visual screenshots
-- **[README_DocsLayout.md](https://github.com/GSA-TTS/usai-gov/blob/main/packages/ui/README_DocsLayout.md)** - DocsLayout component with dynamic navigation generation (Astro only)
-
-These files are also included with the package in your `node_modules/@gsa-tts/graymatter-ui/` directory. If you don't have access to the private repository, you can find the documentation files locally after installation.
-
-## Framework Support
-
-- **Svelte 5** - Native Svelte components (individual components only)
-- **Astro** - Full support with client-side hydration (including DocsLayout)
-- **React/Vue/Angular** - Via web components (individual components only)
-- **Vanilla JavaScript** - Via web components (individual components only)
-
-**Note:** The `DocsLayout` component is Astro-specific and cannot be used in other frameworks. For non-Astro applications, use the individual Svelte components and shared utilities instead.
 
-## Troubleshooting
+> **Application layouts:** Page layouts (`BaseLayout`, `GlobalAppLayout`,
+> `DocsLayout`, etc.) are owned by the consuming application, not this package.
+> For the USAi site, see `apps/site/src/layouts/`.
 
-### Build Issues with Astro Files
+These files are also included with the package in your
+`node_modules/@gsa-tts/graymatter-ui/` directory. If you don't have access to the
+private repository, you can find the documentation files locally after
+installation.
 
-If you're getting build errors related to Astro files in a Svelte-only project, use the dedicated import paths:
-
-```javascript
-// ✅ For Svelte-only projects using web components
-import { toggleNavigation } from '@gsa-tts/graymatter-ui/utils';
-// Use web components in HTML: <graymatter-button>, <graymatter-logo>, etc.
-
-// ❌ Avoid in Svelte-only projects
-import { toggleNavigation } from '@gsa-tts/graymatter-ui';
-```
+## Framework Support
 
-**Common Error:** `Unexpected token '{'. Expected '.' or '('` when importing from the main package in Svelte-only projects.
+- **Svelte 5** - Native Svelte components
+- **Astro** - Consume the Svelte components as islands with client-side hydration
+- **SvelteKit** - Native Svelte components
 
-**Solution:** Use the `/utils` path for utility functions. For UI components, use web components instead of importing Svelte components directly.
+Consuming applications provide their own page layouts and framework
+configuration; this package ships the shared Svelte components, styles, and
+utilities they build on.
 
 ## Browser Support
 
 - **Modern Browsers** - Chrome, Firefox, Safari, Edge (latest 2 versions)
-- **Web Components** - Native support or polyfill required
-- **Custom Events** - Native support in all modern browsers 
+- **Custom Events** - Native support in all modern browsers