@usefragments/ui 1.0.0

package/src/components/NavigationMenu/NavigationMenu.contract.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "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",
+  "tags": [
+    "navigation",
+    "menu",
+    "header",
+    "dropdown",
+    "navbar",
+    "mobile",
+    "responsive",
+    "drawer"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/NavigationMenu/index.tsx",
+  "exportName": "NavigationMenu",
+  "propsSummary": [
+    "children: node (required)",
+    "value: string",
+    "defaultValue: string",
+    "onValueChange: function",
+    "orientation: horizontal|vertical (default: horizontal)",
+    "delayDuration: number (default: 200)",
+    "skipDelayDuration: number (default: 300)",
+    "icons: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "NavigationMenu.List, NavigationMenu.Viewport, and optionally NavigationMenu.MobileContent",
+      "required": true
+    },
+    "value": {
+      "type": "string",
+      "description": "Controlled open item value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Default open item value",
+      "default": "''",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Callback when open item changes",
+      "required": false
+    },
+    "orientation": {
+      "type": "enum",
+      "description": "'horizontal' | 'vertical'",
+      "default": "horizontal",
+      "required": false,
+      "values": [
+        "horizontal",
+        "vertical"
+      ]
+    },
+    "delayDuration": {
+      "type": "number",
+      "description": "Hover delay before opening (ms)",
+      "default": "200",
+      "required": false
+    },
+    "skipDelayDuration": {
+      "type": "number",
+      "description": "Duration after close during which moving to another trigger opens instantly (ms)",
+      "default": "300",
+      "required": false
+    },
+    "icons": {
+      "type": "object",
+      "description": "Optional icon overrides for triggerChevron, mobileMenu, mobileClose, and drawerClose controls",
+      "required": false
+    }
+  },
+  "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",
+      "NavigationMenu.Link asChild composes click handlers and respects event.preventDefault()",
+      "Triggers open on hover (desktop) with configurable delay",
+      "Use the icons prop to replace trigger chevrons and mobile drawer controls with icons from any package"
+    ],
+    "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"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Two trigger items with dropdown content and one direct link",
+      "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"products\">\n      <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics and KPIs.\" />\n        <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate your workflows.\" />\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item value=\"resources\">\n      <NavigationMenu.Trigger>Resources</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <NavigationMenu.Link href=\"/docs\" title=\"Documentation\" description=\"Comprehensive API reference.\" />\n        <NavigationMenu.Link href=\"/blog\" title=\"Blog\" description=\"Latest news and updates.\" />\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Link href=\"/pricing\">Pricing</NavigationMenu.Link>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
+    },
+    {
+      "name": "With Rich Content",
+      "description": "Grid layout with icons, titles, and descriptions",
+      "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"platform\">\n      <NavigationMenu.Trigger>Platform</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '4px', padding: '8px', minWidth: '400px' }}>\n          <NavigationMenu.Link\n            href=\"/dashboard\"\n            title=\"Dashboard\"\n            description=\"Overview of your project metrics.\"\n          />\n          <NavigationMenu.Link\n            href=\"/analytics\"\n            title=\"Analytics\"\n            description=\"Deep dive into your data.\"\n          />\n          <NavigationMenu.Link\n            href=\"/reports\"\n            title=\"Reports\"\n            description=\"Generate custom reports.\"\n          />\n          <NavigationMenu.Link\n            href=\"/settings\"\n            title=\"Settings\"\n            description=\"Configure your workspace.\"\n          />\n        </div>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
+    },
+    {
+      "name": "With Simple Links",
+      "description": "Mix of triggers with simple link lists and plain links",
+      "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"company\">\n      <NavigationMenu.Trigger>Company</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '160px' }}>\n          <NavigationMenu.Link href=\"/about\">About</NavigationMenu.Link>\n          <NavigationMenu.Link href=\"/careers\">Careers</NavigationMenu.Link>\n          <NavigationMenu.Link href=\"/contact\">Contact</NavigationMenu.Link>\n        </div>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Link href=\"/blog\">Blog</NavigationMenu.Link>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Link href=\"/docs\">Docs</NavigationMenu.Link>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
+    },
+    {
+      "name": "With Featured Card",
+      "description": "Highlighted featured item alongside regular links",
+      "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"learn\">\n      <NavigationMenu.Trigger>Learn</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '8px', padding: '8px', minWidth: '420px' }}>\n          <NavigationMenu.Link\n            href=\"/quickstart\"\n            title=\"Quick Start\"\n            description=\"Get up and running in 5 minutes with our getting started guide.\"\n            featured\n          />\n          <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>\n            <NavigationMenu.Link href=\"/docs\" title=\"Documentation\" description=\"API reference and guides.\" />\n            <NavigationMenu.Link href=\"/examples\" title=\"Examples\" description=\"Browse example projects.\" />\n          </div>\n        </div>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
+    },
+    {
+      "name": "Vertical",
+      "description": "Vertical orientation with content panels to the right",
+      "code": "<div style={{ display: 'flex' }}>\n  <NavigationMenu orientation=\"vertical\">\n    <NavigationMenu.List>\n      <NavigationMenu.Item value=\"overview\">\n        <NavigationMenu.Trigger>Overview</NavigationMenu.Trigger>\n        <NavigationMenu.Content>\n          <div style={{ padding: '8px', minWidth: '200px' }}>\n            <NavigationMenu.Link href=\"/intro\" title=\"Introduction\" description=\"Learn the basics.\" />\n          </div>\n        </NavigationMenu.Content>\n      </NavigationMenu.Item>\n      <NavigationMenu.Item value=\"guides\">\n        <NavigationMenu.Trigger>Guides</NavigationMenu.Trigger>\n        <NavigationMenu.Content>\n          <div style={{ padding: '8px', minWidth: '200px' }}>\n            <NavigationMenu.Link href=\"/install\" title=\"Installation\" description=\"Get started quickly.\" />\n            <NavigationMenu.Link href=\"/config\" title=\"Configuration\" description=\"Customize your setup.\" />\n          </div>\n        </NavigationMenu.Content>\n      </NavigationMenu.Item>\n    </NavigationMenu.List>\n    <NavigationMenu.Viewport />\n  </NavigationMenu>\n</div>"
+    }
+  ],
+  "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)",
+      "icons: { triggerChevron?, mobileMenu?, mobileClose?, drawerClose? } — custom internal control icons",
+      "NavigationMenu.Link: title + description + icon for structured links, or children for simple links",
+      "NavigationMenu.Link asChild: composes child and menu click handlers (preventDefault keeps menu open)",
+      "NavigationMenu.MobileContent: slot for extra mobile-only sections"
+    ],
+    "a11yRules": [
+      "A11Y_DISCLOSURE_PATTERN",
+      "A11Y_KEYBOARD_NAV",
+      "A11Y_FOCUS_TRAP"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "List",
+      "Item",
+      "Trigger",
+      "Content",
+      "Link",
+      "Indicator",
+      "Viewport",
+      "MobileBrand",
+      "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>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:01.458Z"
+  }
+}