@fragments-sdk/ui 0.8.4 → 0.8.5

package/src/components/DatePicker/index.tsx

@@ -1,17 +1,16 @@
 import * as React from 'react';
 import { Popover as BasePopover } from '@base-ui/react/popover';
-import { DayPicker, UI, SelectionState, DayFlag } from 'react-day-picker';
-import { format } from 'date-fns';
 import styles from './DatePicker.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';
 
 // ============================================
-// Types
+// Types (self-owned — no external dependency for types)
 // ============================================
 
-export type { DateRange, Matcher } from 'react-day-picker';
-import type { DateRange, Matcher, Locale } from 'react-day-picker';
+export type DateRange = { from: Date | undefined; to?: Date | undefined };
+export type Matcher = Date | DateRange | ((date: Date) => boolean) | Date[];
+type Locale = { [key: string]: unknown };
 
 export interface DatePickerProps {
   children: React.ReactNode;
@@ -75,6 +74,39 @@ export interface DatePickerPresetProps {
   className?: string;
 }
 
+// ============================================
+// Lazy-loaded dependencies (react-day-picker + date-fns)
+// ============================================
+
+let _DayPicker: any = null;
+let _dpUI: any = null;
+let _SelectionState: any = null;
+let _DayFlag: any = null;
+let _formatDate: ((date: Date, fmt: string) => string) | null = null;
+let _dpLoaded = false;
+let _dpFailed = false;
+
+function loadDatePickerDeps() {
+  if (_dpLoaded) return;
+  _dpLoaded = true;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rdp = require('react-day-picker');
+    _DayPicker = rdp.DayPicker;
+    _dpUI = rdp.UI;
+    _SelectionState = rdp.SelectionState;
+    _DayFlag = rdp.DayFlag;
+  } catch {
+    _dpFailed = true;
+  }
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _formatDate = require('date-fns').format;
+  } catch {
+    _dpFailed = true;
+  }
+}
+
 // ============================================
 // Icons
 // ============================================
@@ -178,45 +210,53 @@ function useDatePickerContext() {
 // ============================================
 
 function defaultFormatDate(date: Date): string {
-  return format(date, 'PPP');
+  if (_formatDate) return _formatDate(date, 'PPP');
+  return date.toLocaleDateString();
 }
 
 function defaultFormatRange(range: DateRange): string {
   if (!range.from) return '';
-  if (!range.to) return format(range.from, 'LLL dd, y');
-  return `${format(range.from, 'LLL dd, y')} - ${format(range.to, 'LLL dd, y')}`;
+  if (_formatDate) {
+    if (!range.to) return _formatDate(range.from, 'LLL dd, y');
+    return `${_formatDate(range.from, 'LLL dd, y')} - ${_formatDate(range.to, 'LLL dd, y')}`;
+  }
+  if (!range.to) return range.from.toLocaleDateString();
+  return `${range.from.toLocaleDateString()} - ${range.to.toLocaleDateString()}`;
 }
 
 // ============================================
-// ClassNames mapping
+// ClassNames mapping (built lazily)
 // ============================================
 
-const calendarClassNames = {
-  [UI.Root]: styles.calendar,
-  [UI.Months]: styles.months,
-  [UI.Month]: styles.month,
-  [UI.MonthCaption]: styles.monthCaption,
-  [UI.CaptionLabel]: styles.captionLabel,
-  [UI.Nav]: styles.nav,
-  [UI.PreviousMonthButton]: styles.navButton,
-  [UI.NextMonthButton]: styles.navButton,
-  [UI.MonthGrid]: styles.monthGrid,
-  [UI.Weekdays]: styles.weekdays,
-  [UI.Weekday]: styles.weekday,
-  [UI.Weeks]: styles.weeks,
-  [UI.Week]: styles.week,
-  [UI.Day]: styles.day,
-  [UI.DayButton]: styles.dayButton,
-  [UI.Chevron]: styles.chevron,
-  [SelectionState.selected]: styles.selected,
-  [SelectionState.range_start]: styles.rangeStart,
-  [SelectionState.range_middle]: styles.rangeMiddle,
-  [SelectionState.range_end]: styles.rangeEnd,
-  [DayFlag.today]: styles.today,
-  [DayFlag.outside]: styles.outside,
-  [DayFlag.disabled]: styles.disabled,
-  [DayFlag.focused]: styles.focused,
-};
+function getCalendarClassNames() {
+  if (!_dpUI || !_SelectionState || !_DayFlag) return {};
+  return {
+    [_dpUI.Root]: styles.calendar,
+    [_dpUI.Months]: styles.months,
+    [_dpUI.Month]: styles.month,
+    [_dpUI.MonthCaption]: styles.monthCaption,
+    [_dpUI.CaptionLabel]: styles.captionLabel,
+    [_dpUI.Nav]: styles.nav,
+    [_dpUI.PreviousMonthButton]: styles.navButton,
+    [_dpUI.NextMonthButton]: styles.navButton,
+    [_dpUI.MonthGrid]: styles.monthGrid,
+    [_dpUI.Weekdays]: styles.weekdays,
+    [_dpUI.Weekday]: styles.weekday,
+    [_dpUI.Weeks]: styles.weeks,
+    [_dpUI.Week]: styles.week,
+    [_dpUI.Day]: styles.day,
+    [_dpUI.DayButton]: styles.dayButton,
+    [_dpUI.Chevron]: styles.chevron,
+    [_SelectionState.selected]: styles.selected,
+    [_SelectionState.range_start]: styles.rangeStart,
+    [_SelectionState.range_middle]: styles.rangeMiddle,
+    [_SelectionState.range_end]: styles.rangeEnd,
+    [_DayFlag.today]: styles.today,
+    [_DayFlag.outside]: styles.outside,
+    [_DayFlag.disabled]: styles.disabled,
+    [_DayFlag.focused]: styles.focused,
+  };
+}
 
 // ============================================
 // Components
@@ -241,6 +281,8 @@ function DatePickerRoot({
   onOpenChange,
   name,
 }: DatePickerProps) {
+  // Load deps eagerly so date formatters are available in the trigger
+  loadDatePickerDeps();
   const [internalSelected, setInternalSelected] = React.useState<Date | null>(
     selectedProp ?? null
   );
@@ -439,13 +481,11 @@ function DatePickerContent({
 }
 
 function DatePickerCalendar({ numberOfMonths: numberOfMonthsProp, className }: DatePickerCalendarProps) {
+  loadDatePickerDeps();
+
   const ctx = useDatePickerContext();
   const monthCount = numberOfMonthsProp ?? ctx.numberOfMonths;
 
-  const calendarClasses = className
-    ? { ...calendarClassNames, [UI.Root]: [styles.calendar, className].join(' ') }
-    : calendarClassNames;
-
   const components = React.useMemo(
     () => ({
       Chevron: (props: { orientation?: string }) =>
@@ -454,16 +494,34 @@ function DatePickerCalendar({ numberOfMonths: numberOfMonthsProp, className }: D
     []
   );
 
+  if (_dpFailed || !_DayPicker) {
+    if (_dpFailed && process.env.NODE_ENV === 'development') {
+      console.warn(
+        '[@fragments-sdk/ui] DatePicker: react-day-picker and date-fns are not installed. ' +
+        'Install them with: npm install react-day-picker date-fns'
+      );
+    }
+    return null;
+  }
+
+  const calendarClassNames = getCalendarClassNames();
+
+  const calendarClasses = className
+    ? { ...calendarClassNames, [_dpUI.Root]: [styles.calendar, className].join(' ') }
+    : calendarClassNames;
+
+  const DayPickerComponent = _DayPicker;
+
   if (ctx.mode === 'range') {
     const rangeSelected = ctx.selectedRange
       ? { from: ctx.selectedRange.from ?? undefined, to: ctx.selectedRange.to ?? undefined }
       : undefined;
 
     return (
-      <DayPicker
+      <DayPickerComponent
         mode="range"
         selected={rangeSelected}
-        onSelect={(range) => {
+        onSelect={(range: any) => {
           ctx.setSelectedRange(range ? { from: range.from ?? undefined, to: range.to ?? undefined } : null);
         }}
         numberOfMonths={monthCount}
@@ -478,10 +536,10 @@ function DatePickerCalendar({ numberOfMonths: numberOfMonthsProp, className }: D
   }
 
   return (
-    <DayPicker
+    <DayPickerComponent
       mode="single"
       selected={ctx.selected ?? undefined}
-      onSelect={(date) => {
+      onSelect={(date: any) => {
         ctx.setSelected(date ?? null);
       }}
       numberOfMonths={monthCount}

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

@@ -1,6 +1,7 @@
 import React from 'react';
 import { defineFragment } from '@fragments/core';
 import { Header } from '.';
+import { NavigationMenu } from '../NavigationMenu';
 import { ThemeToggle, ThemeProvider } from '../Theme';
 import { Button } from '../Button';
 import { Input } from '../Input';
@@ -40,6 +41,8 @@ export default defineFragment({
       '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',
+      'For rich dropdown content (titles, descriptions, icons), use NavigationMenu instead of Header.Nav',
+      'NavigationMenu also provides an automatic mobile drawer, replacing Header.Trigger + Sidebar for mobile nav',
     ],
     accessibility: [
       'Include Header.SkipLink for keyboard users',
@@ -73,6 +76,7 @@ export default defineFragment({
     { component: 'AppShell', relationship: 'parent', note: 'Header is typically used inside AppShell.Header' },
     { component: 'Sidebar', relationship: 'sibling', note: 'Header.Trigger toggles Sidebar on mobile' },
     { component: 'Theme', relationship: 'child', note: 'ThemeToggle is commonly placed in Header.Actions' },
+    { component: 'NavigationMenu', relationship: 'child', note: 'Use NavigationMenu inside Header for rich dropdown nav with auto mobile drawer' },
   ],
 
   ai: {
@@ -211,5 +215,38 @@ export default defineFragment({
         </Header>
       ),
     },
+    {
+      name: 'With NavigationMenu',
+      description: 'Header using NavigationMenu for rich dropdown content panels with titles, descriptions, and automatic mobile drawer.',
+      render: () => (
+        <ThemeProvider defaultMode="light">
+          <Header>
+            <Header.Brand href="/">MyApp</Header.Brand>
+            <NavigationMenu aria-label="Site navigation">
+              <NavigationMenu.List>
+                <NavigationMenu.Item value="products">
+                  <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
+                  <NavigationMenu.Content>
+                    <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '200px' }}>
+                      <NavigationMenu.Link href="/analytics" title="Analytics" description="Track your metrics." />
+                      <NavigationMenu.Link href="/automation" title="Automation" description="Automate workflows." />
+                    </div>
+                  </NavigationMenu.Content>
+                </NavigationMenu.Item>
+                <NavigationMenu.Item>
+                  <NavigationMenu.Link href="/pricing">Pricing</NavigationMenu.Link>
+                </NavigationMenu.Item>
+              </NavigationMenu.List>
+              <NavigationMenu.Viewport />
+            </NavigationMenu>
+            <Header.Spacer />
+            <Header.Actions>
+              <ThemeToggle size="md" />
+              <Button variant="primary" size="sm">Sign Up</Button>
+            </Header.Actions>
+          </Header>
+        </ThemeProvider>
+      ),
+    },
   ],
 });

package/src/components/Link/Link.fragment.tsx

@@ -64,6 +64,11 @@ export default defineFragment({
       description: 'Opens in new tab with noopener noreferrer',
       default: 'false',
     },
+    asChild: {
+      type: 'boolean',
+      description: 'Render as child element (polymorphic). Merges link props onto the single child. Useful for rendering as Next.js Link for client-side navigation.',
+      default: 'false',
+    },
   },
 
   relations: [
@@ -78,6 +83,7 @@ export default defineFragment({
       'variant: default|subtle|muted - visual style',
       'underline: always|hover|none - underline behavior',
       'external: boolean - opens in new tab',
+      'asChild: boolean - render as child element for polymorphic usage (e.g. Next.js Link)',
     ],
     scenarioTags: [
       'navigation.link',
@@ -124,5 +130,16 @@ export default defineFragment({
         </Link>
       ),
     },
+    {
+      name: 'As Child (Polymorphic)',
+      description: 'Renders as a custom element while applying Link styles. Useful with Next.js Link for client-side navigation.',
+      render: () => (
+        <Link asChild variant="subtle">
+          <button type="button" onClick={() => alert('Navigated!')}>
+            Polymorphic link as button
+          </button>
+        </Link>
+      ),
+    },
   ],
 });

package/src/components/Link/Link.test.tsx

@@ -30,6 +30,29 @@ describe('Link', () => {
     expect(ref).toHaveBeenCalled();
   });
 
+  it('renders as child element when asChild is true', () => {
+    render(
+      <Link asChild variant="subtle">
+        <button type="button">Click me</button>
+      </Link>
+    );
+    const btn = screen.getByRole('button', { name: 'Click me' });
+    expect(btn.tagName).toBe('BUTTON');
+    expect(btn).toHaveClass('link');
+    expect(btn).toHaveClass('subtle');
+  });
+
+  it('merges classNames when asChild is true', () => {
+    render(
+      <Link asChild variant="default">
+        <a href="/test" className="custom-class">Test</a>
+      </Link>
+    );
+    const link = screen.getByRole('link', { name: 'Test' });
+    expect(link).toHaveClass('link');
+    expect(link).toHaveClass('custom-class');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Link href="/page">Accessible link</Link>);
     await expectNoA11yViolations(container);

package/src/components/Link/index.tsx

@@ -10,6 +10,11 @@ export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement>
   underline?: 'always' | 'hover' | 'none';
   /** Open in new tab (adds rel="noopener noreferrer") */
   external?: boolean;
+  /**
+   * Render as child element (polymorphic). When true, clones the single child
+   * and merges link props onto it. Useful for rendering as Next.js Link, etc.
+   */
+  asChild?: boolean;
   /** Additional class name */
   className?: string;
   /** Inline styles */
@@ -23,6 +28,7 @@ const LinkRoot = React.forwardRef<HTMLAnchorElement, LinkProps>(
       variant = 'default',
       underline = 'hover',
       external = false,
+      asChild = false,
       className,
       style,
       target,
@@ -48,6 +54,20 @@ const LinkRoot = React.forwardRef<HTMLAnchorElement, LinkProps>(
         }
       : { target, rel };
 
+    if (asChild && React.isValidElement(children)) {
+      const childProps = children.props as Record<string, unknown>;
+      const mergedProps: Record<string, unknown> = {
+        ref,
+        className: childProps.className
+          ? `${classes} ${childProps.className}`
+          : classes,
+        style: { ...style, ...(childProps.style as React.CSSProperties | undefined) },
+        ...externalProps,
+        ...props,
+      };
+      return React.cloneElement(children, mergedProps);
+    }
+
     return (
       <a ref={ref} className={classes} style={style} {...externalProps} {...props}>
         {children}

package/src/components/Markdown/Markdown.fragment.tsx

@@ -85,6 +85,10 @@ export default defineFragment({
     status: 'stable',
     tags: ['markdown', 'prose', 'content', 'text', 'ai', 'chat'],
     since: '0.7.0',
+    dependencies: [
+      { name: 'react-markdown', version: '>=9.0.0', reason: 'Markdown parsing and rendering' },
+      { name: 'remark-gfm', version: '>=4.0.0', reason: 'GitHub Flavored Markdown support (optional)' },
+    ],
   },
 
   usage: {

package/src/components/NavigationMenu/NavigationMenu.fragment.tsx

@@ -0,0 +1,270 @@
+import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { NavigationMenu } from '.';
+
+export default defineFragment({
+  component: NavigationMenu,
+
+  meta: {
+    name: 'NavigationMenu',
+    description: 'Rich navigation menu for site headers with dropdown content panels, animated viewport transitions, and automatic mobile drawer. Supports structured links with titles, descriptions, and icons.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['navigation', 'menu', 'header', 'dropdown', 'navbar', 'mobile', 'responsive', 'drawer'],
+    since: '0.9.0',
+  },
+
+  usage: {
+    when: [
+      'Site-level header navigation with rich dropdown content',
+      'Navigation with titles, descriptions, and icons in dropdowns',
+      'Responsive navigation that converts to a mobile drawer automatically',
+      'Multi-section navigation requiring animated viewport transitions',
+    ],
+    whenNot: [
+      'Simple flat navigation without dropdowns (use Header.Nav)',
+      'Application menus with actions like cut/paste (use Menu)',
+      'Sidebar navigation (use Sidebar)',
+      'Breadcrumb trail navigation (use Breadcrumbs)',
+    ],
+    guidelines: [
+      'Place inside Header component for site-level navigation',
+      'Use NavigationMenu.Viewport for animated content panel transitions',
+      'Use NavigationMenu.MobileContent to add extra sections to the mobile drawer',
+      'Use structured links (title + description) for rich dropdown content',
+      'Use simple NavigationMenu.Link for items without dropdown content',
+      'Triggers open on hover (desktop) with configurable delay',
+    ],
+    accessibility: [
+      'Uses disclosure pattern (not menu role) per W3C guidance',
+      'Keyboard: Arrow keys navigate between triggers, Enter/Space toggles, Escape closes',
+      'Content panels have role="region" with aria-labelledby pointing to trigger',
+      'Mobile drawer has focus trap, Escape to close, and aria-modal',
+      'Supports prefers-reduced-motion for all animations',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'NavigationMenu.List, NavigationMenu.Viewport, and optionally NavigationMenu.MobileContent',
+      required: true,
+    },
+    value: {
+      type: 'string',
+      description: 'Controlled open item value',
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Default open item value',
+      default: "''",
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Callback when open item changes',
+    },
+    orientation: {
+      type: 'string',
+      description: "'horizontal' | 'vertical'",
+      default: "'horizontal'",
+    },
+    delayDuration: {
+      type: 'number',
+      description: 'Hover delay before opening (ms)',
+      default: '200',
+    },
+    skipDelayDuration: {
+      type: 'number',
+      description: 'Duration after close during which moving to another trigger opens instantly (ms)',
+      default: '300',
+    },
+  },
+
+  relations: [
+    { component: 'Header', relationship: 'sibling', note: 'Place NavigationMenu inside Header for site navigation' },
+    { component: 'Sidebar', relationship: 'alternative', note: 'Use Sidebar for persistent side navigation, NavigationMenu for header dropdowns' },
+    { component: 'Menu', relationship: 'alternative', note: 'Use Menu for action menus (role=menu), NavigationMenu for site navigation (disclosure pattern)' },
+    { component: 'Breadcrumbs', relationship: 'sibling', note: 'Use Breadcrumbs for hierarchical page trail, NavigationMenu for site-level navigation' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string — controlled open item',
+      'onValueChange: (value) => void — open state handler',
+      'orientation: horizontal | vertical — layout direction',
+      'delayDuration: number — hover open delay (default: 200ms)',
+      'NavigationMenu.Link: title + description + icon for structured links, or children for simple links',
+      'NavigationMenu.MobileContent: slot for extra mobile-only sections',
+    ],
+    scenarioTags: [
+      'navigation.site',
+      'navigation.dropdown',
+      'navigation.mobile',
+      'layout.header',
+    ],
+    a11yRules: ['A11Y_DISCLOSURE_PATTERN', 'A11Y_KEYBOARD_NAV', 'A11Y_FOCUS_TRAP'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['List', 'Item', 'Trigger', 'Content', 'Link', 'Indicator', 'Viewport', 'MobileContent', 'MobileSection'],
+    requiredChildren: ['List'],
+    commonPatterns: [
+      '<NavigationMenu><NavigationMenu.List><NavigationMenu.Item value="docs"><NavigationMenu.Trigger>Docs</NavigationMenu.Trigger><NavigationMenu.Content><NavigationMenu.Link href="/guides" title="Guides" description="Learn the basics" /></NavigationMenu.Content></NavigationMenu.Item></NavigationMenu.List><NavigationMenu.Viewport /></NavigationMenu>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Two trigger items with dropdown content and one direct link',
+      render: () => (
+        <NavigationMenu>
+          <NavigationMenu.List>
+            <NavigationMenu.Item value="products">
+              <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
+              <NavigationMenu.Content>
+                <NavigationMenu.Link href="/analytics" title="Analytics" description="Track your metrics and KPIs." />
+                <NavigationMenu.Link href="/automation" title="Automation" description="Automate your workflows." />
+              </NavigationMenu.Content>
+            </NavigationMenu.Item>
+            <NavigationMenu.Item value="resources">
+              <NavigationMenu.Trigger>Resources</NavigationMenu.Trigger>
+              <NavigationMenu.Content>
+                <NavigationMenu.Link href="/docs" title="Documentation" description="Comprehensive API reference." />
+                <NavigationMenu.Link href="/blog" title="Blog" description="Latest news and updates." />
+              </NavigationMenu.Content>
+            </NavigationMenu.Item>
+            <NavigationMenu.Item>
+              <NavigationMenu.Link href="/pricing">Pricing</NavigationMenu.Link>
+            </NavigationMenu.Item>
+          </NavigationMenu.List>
+          <NavigationMenu.Viewport />
+        </NavigationMenu>
+      ),
+    },
+    {
+      name: 'With Rich Content',
+      description: 'Grid layout with icons, titles, and descriptions',
+      render: () => (
+        <NavigationMenu>
+          <NavigationMenu.List>
+            <NavigationMenu.Item value="platform">
+              <NavigationMenu.Trigger>Platform</NavigationMenu.Trigger>
+              <NavigationMenu.Content>
+                <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '4px', padding: '8px', minWidth: '400px' }}>
+                  <NavigationMenu.Link
+                    href="/dashboard"
+                    title="Dashboard"
+                    description="Overview of your project metrics."
+                  />
+                  <NavigationMenu.Link
+                    href="/analytics"
+                    title="Analytics"
+                    description="Deep dive into your data."
+                  />
+                  <NavigationMenu.Link
+                    href="/reports"
+                    title="Reports"
+                    description="Generate custom reports."
+                  />
+                  <NavigationMenu.Link
+                    href="/settings"
+                    title="Settings"
+                    description="Configure your workspace."
+                  />
+                </div>
+              </NavigationMenu.Content>
+            </NavigationMenu.Item>
+          </NavigationMenu.List>
+          <NavigationMenu.Viewport />
+        </NavigationMenu>
+      ),
+    },
+    {
+      name: 'With Simple Links',
+      description: 'Mix of triggers with simple link lists and plain links',
+      render: () => (
+        <NavigationMenu>
+          <NavigationMenu.List>
+            <NavigationMenu.Item value="company">
+              <NavigationMenu.Trigger>Company</NavigationMenu.Trigger>
+              <NavigationMenu.Content>
+                <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '160px' }}>
+                  <NavigationMenu.Link href="/about">About</NavigationMenu.Link>
+                  <NavigationMenu.Link href="/careers">Careers</NavigationMenu.Link>
+                  <NavigationMenu.Link href="/contact">Contact</NavigationMenu.Link>
+                </div>
+              </NavigationMenu.Content>
+            </NavigationMenu.Item>
+            <NavigationMenu.Item>
+              <NavigationMenu.Link href="/blog">Blog</NavigationMenu.Link>
+            </NavigationMenu.Item>
+            <NavigationMenu.Item>
+              <NavigationMenu.Link href="/docs">Docs</NavigationMenu.Link>
+            </NavigationMenu.Item>
+          </NavigationMenu.List>
+          <NavigationMenu.Viewport />
+        </NavigationMenu>
+      ),
+    },
+    {
+      name: 'With Featured Card',
+      description: 'Highlighted featured item alongside regular links',
+      render: () => (
+        <NavigationMenu>
+          <NavigationMenu.List>
+            <NavigationMenu.Item value="learn">
+              <NavigationMenu.Trigger>Learn</NavigationMenu.Trigger>
+              <NavigationMenu.Content>
+                <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '8px', padding: '8px', minWidth: '420px' }}>
+                  <NavigationMenu.Link
+                    href="/quickstart"
+                    title="Quick Start"
+                    description="Get up and running in 5 minutes with our getting started guide."
+                    featured
+                  />
+                  <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
+                    <NavigationMenu.Link href="/docs" title="Documentation" description="API reference and guides." />
+                    <NavigationMenu.Link href="/examples" title="Examples" description="Browse example projects." />
+                  </div>
+                </div>
+              </NavigationMenu.Content>
+            </NavigationMenu.Item>
+          </NavigationMenu.List>
+          <NavigationMenu.Viewport />
+        </NavigationMenu>
+      ),
+    },
+    {
+      name: 'Vertical',
+      description: 'Vertical orientation with content panels to the right',
+      render: () => (
+        <div style={{ display: 'flex' }}>
+          <NavigationMenu orientation="vertical">
+            <NavigationMenu.List>
+              <NavigationMenu.Item value="overview">
+                <NavigationMenu.Trigger>Overview</NavigationMenu.Trigger>
+                <NavigationMenu.Content>
+                  <div style={{ padding: '8px', minWidth: '200px' }}>
+                    <NavigationMenu.Link href="/intro" title="Introduction" description="Learn the basics." />
+                  </div>
+                </NavigationMenu.Content>
+              </NavigationMenu.Item>
+              <NavigationMenu.Item value="guides">
+                <NavigationMenu.Trigger>Guides</NavigationMenu.Trigger>
+                <NavigationMenu.Content>
+                  <div style={{ padding: '8px', minWidth: '200px' }}>
+                    <NavigationMenu.Link href="/install" title="Installation" description="Get started quickly." />
+                    <NavigationMenu.Link href="/config" title="Configuration" description="Customize your setup." />
+                  </div>
+                </NavigationMenu.Content>
+              </NavigationMenu.Item>
+            </NavigationMenu.List>
+            <NavigationMenu.Viewport />
+          </NavigationMenu>
+        </div>
+      ),
+    },
+  ],
+});