@fragments-sdk/ui 0.7.5 → 0.8.1

package/src/components/Grid/Grid.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Grid } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: Grid,
 
   meta: {
@@ -39,6 +39,10 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'Grid items and content',
+    },
     columns: {
       type: 'union',
       description: 'Number of columns: a number (1-12), a responsive object { base, sm, md, lg, xl }, or "auto" for auto-fill',

package/src/components/Header/Header.fragment.tsx

@@ -1,27 +1,20 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Header } from '.';
 import { ThemeToggle, ThemeProvider } from '../Theme';
 import { Button } from '../Button';
 import { Input } from '../Input';
+import { MagnifyingGlass } from '@phosphor-icons/react';
 
-function SearchIcon() {
-  return (
-    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 256 256" fill="currentColor">
-      <path d="M229.66,218.34l-50.07-50.06a88.11,88.11,0,1,0-11.31,11.31l50.06,50.07a8,8,0,0,0,11.32-11.32ZM40,112a72,72,0,1,1,72,72A72.08,72.08,0,0,1,40,112Z" />
-    </svg>
-  );
-}
-
-export default defineSegment({
+export default defineFragment({
   component: Header,
 
   meta: {
     name: 'Header',
-    description: 'Composable header with slots for brand, navigation, search, and actions. Designed for use within AppShell with responsive mobile support.',
+    description: 'Composable header with slots for brand, navigation, search, and actions. Supports dropdown nav groups via Header.NavMenu. Designed for use within AppShell with responsive mobile support.',
     category: 'navigation',
     status: 'stable',
-    tags: ['header', 'navigation', 'navbar', 'brand', 'layout'],
+    tags: ['header', 'navigation', 'navbar', 'brand', 'layout', 'dropdown'],
     since: '0.5.0',
   },
 
@@ -31,6 +24,7 @@ export default defineSegment({
       'Navigation bar with branding (stacked layout)',
       'Search and actions bar (sidebar-inset layout)',
       'Header with responsive mobile menu trigger',
+      'Grouping related nav items under a dropdown menu',
     ],
     whenNot: [
       'Simple page titles (use heading elements)',
@@ -44,12 +38,15 @@ export default defineSegment({
       'Header.Trigger integrates with SidebarProvider for mobile menus',
       'Header.Nav is hidden on mobile; use sidebar for mobile navigation',
       'Use Header.Spacer to push items apart',
+      'Use Header.NavMenu to group related nav items under a dropdown',
+      'Use Header.NavMenuItem inside Header.NavMenu for dropdown items',
     ],
     accessibility: [
       'Include Header.SkipLink for keyboard users',
       'Navigation has aria-label for screen readers',
       'Active nav items use aria-current="page"',
       'Mobile trigger has aria-expanded state',
+      'NavMenu dropdown opens with click and is keyboard navigable',
     ],
   },
 
@@ -75,14 +72,15 @@ export default defineSegment({
   relations: [
     { component: 'AppShell', relationship: 'parent', note: 'Header is typically used inside AppShell.Header' },
     { component: 'Sidebar', relationship: 'sibling', note: 'Header.Trigger toggles Sidebar on mobile' },
-    { component: 'ThemeToggle', relationship: 'child', note: 'ThemeToggle is commonly placed in Header.Actions' },
+    { component: 'Theme', relationship: 'child', note: 'ThemeToggle is commonly placed in Header.Actions' },
   ],
 
   ai: {
     compositionPattern: 'compound',
-    subComponents: ['SkipLink', 'Trigger', 'Brand', 'Nav', 'NavItem', 'Search', 'Spacer', 'Actions'],
+    subComponents: ['SkipLink', 'Trigger', 'Brand', 'Nav', 'NavItem', 'NavMenu', 'NavMenuItem', 'Search', 'Spacer', 'Actions'],
     commonPatterns: [
       '<Header><Header.Brand href="/">{appName}</Header.Brand><Header.Nav><Header.NavItem href="/home" active>Home</Header.NavItem></Header.Nav><Header.Spacer /><Header.Actions>{actions}</Header.Actions></Header>',
+      '<Header><Header.Nav><Header.NavItem href="/home">Home</Header.NavItem><Header.NavMenu label="Docs" active><Header.NavMenuItem href="/cli">CLI</Header.NavMenuItem><Header.NavMenuItem href="/mcp">MCP</Header.NavMenuItem></Header.NavMenu></Header.Nav></Header>',
     ],
   },
 
@@ -110,6 +108,31 @@ export default defineSegment({
         </ThemeProvider>
       ),
     },
+    {
+      name: 'With Dropdown Nav',
+      description: 'Header with a dropdown menu grouping related navigation links.',
+      render: () => (
+        <ThemeProvider defaultMode="light">
+          <Header>
+            <Header.Brand href="/">MyApp</Header.Brand>
+            <Header.Nav>
+              <Header.NavItem href="/components" active>Components</Header.NavItem>
+              <Header.NavItem href="/blocks">Blocks</Header.NavItem>
+              <Header.NavMenu label="Docs">
+                <Header.NavMenuItem href="/getting-started">Getting Started</Header.NavMenuItem>
+                <Header.NavMenuItem href="/cli">CLI Reference</Header.NavMenuItem>
+                <Header.NavMenuItem href="/mcp">MCP Tools</Header.NavMenuItem>
+              </Header.NavMenu>
+              <Header.NavItem href="/blog">Blog</Header.NavItem>
+            </Header.Nav>
+            <Header.Spacer />
+            <Header.Actions>
+              <ThemeToggle size="md" />
+            </Header.Actions>
+          </Header>
+        </ThemeProvider>
+      ),
+    },
     {
       name: 'For Sidebar Inset Layout',
       description: 'Header without brand (logo is in sidebar). Use with AppShell layout="sidebar-inset".',
@@ -163,7 +186,7 @@ export default defineSegment({
                 fontSize: '14px',
                 width: '280px'
               }}>
-                <SearchIcon /> Search documentation...
+                <MagnifyingGlass size={16} /> Search documentation...
               </div>
             </Header.Search>
             <Header.Spacer />

package/src/components/Header/Header.module.scss

@@ -106,9 +106,122 @@
 }
 
 .navItemActive {
+  // Match sidebar active state: secondary surface + primary text
   color: var(--fui-text-primary, $fui-text-primary);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  background-color: var(--fui-bg-hover, $fui-bg-hover);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+
+  &:hover {
+    background-color: var(--fui-bg-secondary, $fui-bg-secondary) !important;
+    color: var(--fui-text-primary, $fui-text-primary) !important;
+  }
+
+  &:active {
+    background-color: var(--fui-bg-secondary, $fui-bg-secondary) !important;
+    color: var(--fui-text-primary, $fui-text-primary) !important;
+  }
+}
+
+// ============================================
+// NavMenu (dropdown trigger)
+// ============================================
+
+.navMenuTrigger {
+  gap: var(--fui-space-1, $fui-space-1);
+  cursor: pointer;
+}
+
+.navMenuChevron {
+  transition: transform var(--fui-transition-fast, $fui-transition-fast);
+  flex-shrink: 0;
+
+  [data-popup-open] > & {
+    transform: rotate(180deg);
+  }
+}
+
+// ============================================
+// NavMenu Popup (dropdown content)
+// ============================================
+
+.navMenuPositioner {
+  z-index: 52;
+  outline: none;
+}
+
+.navMenuPopup {
+  @include surface-elevated;
+
+  min-width: 10rem;
+  padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+
+  opacity: 0;
+  transform: scale(0.95);
+  transform-origin: var(--transform-origin);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &[data-open] {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+.navMenuItem {
+  @include button-reset;
+  @include text-base;
+
+  display: flex;
+  align-items: center;
+  width: 100%;
+  padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-md, $fui-padding-item-md);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
+  outline: none;
+
+  &[data-highlighted] {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.navMenuItemActive {
+  // Match active nav item treatment in both light and dark themes
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+
+  &[data-highlighted] {
+    background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .navMenuPopup {
+    transition: none;
+    transform: none;
+
+    &[data-starting-style],
+    &[data-ending-style] {
+      transform: none;
+    }
+  }
+
+  .navMenuChevron {
+    transition: none;
+  }
 }
 
 // ============================================

package/src/components/Header/Header.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { render, screen, userEvent, waitFor, expectNoA11yViolations } from '../../test/utils';
 import { Header } from './index';
 
 describe('Header', () => {
@@ -81,3 +81,108 @@ describe('Header', () => {
     await expectNoA11yViolations(container);
   });
 });
+
+describe('Header.NavMenu', () => {
+  it('renders a trigger button with the label', () => {
+    render(
+      <Header>
+        <Header.Nav>
+          <Header.NavMenu label="Docs">
+            <Header.NavMenuItem href="/cli">CLI</Header.NavMenuItem>
+          </Header.NavMenu>
+        </Header.Nav>
+      </Header>
+    );
+    expect(screen.getByRole('button', { name: /Docs/ })).toBeInTheDocument();
+  });
+
+  it('opens dropdown on click and shows menu items', async () => {
+    const user = userEvent.setup();
+    render(
+      <Header>
+        <Header.Nav>
+          <Header.NavMenu label="Docs">
+            <Header.NavMenuItem href="/cli">CLI Reference</Header.NavMenuItem>
+            <Header.NavMenuItem href="/mcp">MCP Tools</Header.NavMenuItem>
+          </Header.NavMenu>
+        </Header.Nav>
+      </Header>
+    );
+
+    await user.click(screen.getByRole('button', { name: /Docs/ }));
+    await waitFor(() => {
+      expect(screen.getByText('CLI Reference')).toBeInTheDocument();
+      expect(screen.getByText('MCP Tools')).toBeInTheDocument();
+    });
+  });
+
+  it('applies active class to trigger when active prop is true', () => {
+    render(
+      <Header>
+        <Header.Nav>
+          <Header.NavMenu label="Docs" active>
+            <Header.NavMenuItem href="/cli">CLI</Header.NavMenuItem>
+          </Header.NavMenu>
+        </Header.Nav>
+      </Header>
+    );
+    const trigger = screen.getByRole('button', { name: /Docs/ });
+    expect(trigger.className).toMatch(/navItemActive/);
+  });
+
+  it('renders NavMenuItem with href as a link', async () => {
+    const user = userEvent.setup();
+    render(
+      <Header>
+        <Header.Nav>
+          <Header.NavMenu label="Docs">
+            <Header.NavMenuItem href="/getting-started">Getting Started</Header.NavMenuItem>
+          </Header.NavMenu>
+        </Header.Nav>
+      </Header>
+    );
+
+    await user.click(screen.getByRole('button', { name: /Docs/ }));
+    await waitFor(() => {
+      const item = screen.getByText('Getting Started');
+      const link = item.closest('a') || item;
+      expect(link).toHaveAttribute('href', '/getting-started');
+    });
+  });
+
+  it('applies active class to NavMenuItem when active', async () => {
+    const user = userEvent.setup();
+    render(
+      <Header>
+        <Header.Nav>
+          <Header.NavMenu label="Docs">
+            <Header.NavMenuItem href="/cli" active>CLI</Header.NavMenuItem>
+          </Header.NavMenu>
+        </Header.Nav>
+      </Header>
+    );
+
+    await user.click(screen.getByRole('button', { name: /Docs/ }));
+    await waitFor(() => {
+      const item = screen.getByText('CLI');
+      expect(item.className).toMatch(/navMenuItemActive/);
+    });
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Header>
+        <Header.Nav aria-label="Main">
+          <Header.NavItem href="/home">Home</Header.NavItem>
+          <Header.NavMenu label="Docs">
+            <Header.NavMenuItem href="/cli">CLI</Header.NavMenuItem>
+            <Header.NavMenuItem href="/mcp">MCP</Header.NavMenuItem>
+          </Header.NavMenu>
+        </Header.Nav>
+      </Header>
+    );
+    await expectNoA11yViolations(container, {
+      disabledRules: ['aria-command-name'],
+    });
+  });
+});

package/src/components/Header/index.tsx

@@ -1,6 +1,8 @@
 'use client';
 
 import * as React from 'react';
+import { Menu as BaseMenu } from '@base-ui/react/menu';
+import { CaretDown, List, X } from '@phosphor-icons/react';
 import styles from './Header.module.scss';
 import { useSidebar } from '../Sidebar';
 // Import globals to ensure CSS variables are defined
@@ -71,38 +73,26 @@ export interface HeaderTriggerProps {
   className?: string;
 }
 
-// ============================================
-// Icons
-// ============================================
-
-function MenuIcon() {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="24"
-      height="24"
-      viewBox="0 0 256 256"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path d="M224,128a8,8,0,0,1-8,8H40a8,8,0,0,1,0-16H216A8,8,0,0,1,224,128ZM40,72H216a8,8,0,0,0,0-16H40a8,8,0,0,0,0,16ZM216,184H40a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Z" />
-    </svg>
-  );
+export interface HeaderNavMenuProps {
+  /** Trigger label text */
+  label: string;
+  /** Whether any child in the group is active */
+  active?: boolean;
+  /** Additional class name */
+  className?: string;
+  children: React.ReactNode;
 }
 
-function CloseIcon() {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="24"
-      height="24"
-      viewBox="0 0 256 256"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z" />
-    </svg>
-  );
+export interface HeaderNavMenuItemProps {
+  children: React.ReactNode;
+  /** Link destination */
+  href?: string;
+  /** Whether this item is active/current */
+  active?: boolean;
+  /** Render as child element (polymorphic) */
+  asChild?: boolean;
+  /** Additional class name */
+  className?: string;
 }
 
 // ============================================
@@ -302,7 +292,7 @@ function HeaderTrigger({
       aria-label={ariaLabel}
       aria-expanded={open}
     >
-      {children || (open ? <CloseIcon /> : <MenuIcon />)}
+      {children || (open ? <X size={24} aria-hidden /> : <List size={24} aria-hidden />)}
     </button>
   );
 }
@@ -315,6 +305,81 @@ function HeaderSpacer({ className }: { className?: string }) {
   return <div className={classes} />;
 }
 
+/**
+ * Header.NavMenu - Dropdown navigation group
+ */
+function HeaderNavMenu({
+  label,
+  active = false,
+  className,
+  children,
+}: HeaderNavMenuProps) {
+  const triggerClasses = [
+    styles.navItem,
+    styles.navMenuTrigger,
+    active && styles.navItemActive,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <li>
+      <BaseMenu.Root modal={false}>
+        <BaseMenu.Trigger className={triggerClasses}>
+          {label}
+          <CaretDown size={12} className={styles.navMenuChevron} aria-hidden />
+        </BaseMenu.Trigger>
+        <BaseMenu.Portal>
+          <BaseMenu.Positioner side="bottom" align="start" sideOffset={4} className={styles.navMenuPositioner}>
+            <BaseMenu.Popup className={styles.navMenuPopup}>
+              {children}
+            </BaseMenu.Popup>
+          </BaseMenu.Positioner>
+        </BaseMenu.Portal>
+      </BaseMenu.Root>
+    </li>
+  );
+}
+
+/**
+ * Header.NavMenuItem - Item inside a NavMenu dropdown
+ */
+function HeaderNavMenuItem({
+  children,
+  href,
+  active = false,
+  asChild = false,
+  className,
+}: HeaderNavMenuItemProps) {
+  const classes = [
+    styles.navMenuItem,
+    active && styles.navMenuItemActive,
+    className,
+  ].filter(Boolean).join(' ');
+
+  if (asChild && React.isValidElement(children)) {
+    return (
+      <BaseMenu.Item
+        className={classes}
+        render={children as React.ReactElement}
+      />
+    );
+  }
+
+  if (href) {
+    return (
+      <BaseMenu.Item className={classes} render={<a href={href} />}>
+        {children}
+      </BaseMenu.Item>
+    );
+  }
+
+  return (
+    <BaseMenu.Item className={classes}>
+      {children}
+    </BaseMenu.Item>
+  );
+}
+
 /**
  * Header.SkipLink - Skip to main content link (accessibility)
  */
@@ -343,6 +408,8 @@ export const Header = Object.assign(HeaderRoot, {
   Brand: HeaderBrand,
   Nav: HeaderNav,
   NavItem: HeaderNavItem,
+  NavMenu: HeaderNavMenu,
+  NavMenuItem: HeaderNavMenuItem,
   Search: HeaderSearch,
   Actions: HeaderActions,
   Trigger: HeaderTrigger,
@@ -355,6 +422,8 @@ export {
   HeaderBrand,
   HeaderNav,
   HeaderNavItem,
+  HeaderNavMenu,
+  HeaderNavMenuItem,
   HeaderSearch,
   HeaderActions,
   HeaderTrigger,

package/src/components/Icon/Icon.fragment.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Icon } from '.';
 import { Heart, Star, Check, Warning, Info } from '@phosphor-icons/react';
 
-export default defineSegment({
+export default defineFragment({
   component: Icon,
 
   meta: {
@@ -44,7 +44,7 @@ export default defineSegment({
 
   props: {
     icon: {
-      type: 'component',
+      type: 'custom',
       description: 'Phosphor icon component to render',
       required: true,
     },
@@ -66,6 +66,11 @@ export default defineSegment({
       values: ['default', 'primary', 'secondary', 'tertiary', 'accent', 'success', 'warning', 'error'],
       default: 'default',
     },
+    color: {
+      type: 'enum',
+      description: 'Deprecated alias for variant',
+      values: ['primary', 'secondary', 'tertiary', 'accent', 'success', 'warning', 'error'],
+    },
   },
 
   relations: [

package/src/components/Icon/index.tsx

@@ -24,7 +24,7 @@ const sizeMap: Record<NonNullable<IconProps['size']>, number> = {
   xl: 32,
 };
 
-export const Icon = React.forwardRef<HTMLSpanElement, IconProps>(
+const IconRoot = React.forwardRef<HTMLSpanElement, IconProps>(
   function Icon(
     {
       icon: IconComponent,
@@ -56,3 +56,7 @@ export const Icon = React.forwardRef<HTMLSpanElement, IconProps>(
     );
   }
 );
+
+export const Icon = Object.assign(IconRoot, {
+  Root: IconRoot,
+});

package/src/components/Image/Image.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Image } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: Image,
 
   meta: {
@@ -65,11 +65,11 @@ export default defineSegment({
       default: 'cover',
     },
     width: {
-      type: 'string | number',
+      type: 'union',
       description: 'Width of the image container',
     },
     height: {
-      type: 'string | number',
+      type: 'union',
       description: 'Height of the image container',
     },
     rounded: {

package/src/components/Image/index.tsx

@@ -27,7 +27,7 @@ export interface ImageProps {
   style?: React.CSSProperties;
 }
 
-export const Image = React.forwardRef<HTMLDivElement, ImageProps>(
+const ImageRoot = React.forwardRef<HTMLDivElement, ImageProps>(
   function Image(
     {
       src,
@@ -93,3 +93,7 @@ export const Image = React.forwardRef<HTMLDivElement, ImageProps>(
     );
   }
 );
+
+export const Image = Object.assign(ImageRoot, {
+  Root: ImageRoot,
+});