@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Message/Message.contract.json

@@ -1,22 +1,16 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Message",
-  "description": "Individual chat message display with role-based styling",
+  "description": "Shows one chat message, styled by who sent it.",
   "category": "ai",
-  "tags": [
-    "message",
-    "chat",
-    "ai",
-    "conversation",
-    "bubble"
-  ],
+  "tags": ["message", "chat", "ai", "conversation", "bubble"],
   "status": "stable",
   "sourcePath": "src/components/Message/index.tsx",
   "exportName": "Message",
   "propsSummary": [
     "role: user|assistant|system (required)",
     "children: node (required)",
-    "status: sending|streaming|complete|error (default: complete)",
+    "status: pending|streaming|complete|error (default: complete)",
     "timestamp: object",
     "avatar: node",
     "actions: node"
@@ -26,11 +20,7 @@
       "type": "enum",
       "description": "Message role determines styling and alignment",
       "required": true,
-      "values": [
-        "user",
-        "assistant",
-        "system"
-      ]
+      "values": ["user", "assistant", "system"]
     },
     "children": {
       "type": "node",
@@ -42,12 +32,7 @@
       "description": "Message state",
       "default": "complete",
       "required": false,
-      "values": [
-        "sending",
-        "streaming",
-        "complete",
-        "error"
-      ]
+      "values": ["pending", "streaming", "complete", "error"]
     },
     "timestamp": {
       "type": "object",
@@ -67,24 +52,24 @@
   },
   "usage": {
     "when": [
-      "Displaying individual messages in a chat interface",
-      "Building AI assistant or chatbot UIs",
-      "Need role-based message styling (user vs assistant)",
-      "Messages need actions like copy, regenerate, or feedback"
+      "Individual turns in a chat transcript",
+      "AI assistant and chatbot interfaces",
+      "User and assistant turns that must read differently",
+      "Turns carrying copy, regenerate, or feedback actions"
     ],
     "whenNot": [
-      "Simple text display without chat context (use Text)",
-      "Notification-style messages (use Alert or Toast)",
-      "Comment threads with nested replies (use Card with custom layout)"
+      "Plain text with no chat context (use Text)",
+      "Notifications (use Alert or Toast)",
+      "Threads with nested replies (use Card with a custom layout)"
     ],
     "guidelines": [
-      "Always provide a role prop to determine styling",
-      "Use status prop to show message state (sending, streaming, error)",
-      "Pass avatar={null}, or set showAvatars={false} on the parent ConversationList, to hide avatars; avatarless assistant content is flush while the user's own bubble keeps compact space-1/space-2 padding",
-      "User message bubbles are capped at 80% of the available inline measure so they remain visually distinct from assistant responses",
-      "User and assistant message chrome uses neutral surface tokens with the primary text foreground; reserve brand accent for actions or semantic state",
-      "Consider showing timestamps for longer conversations",
-      "Provide hover actions for assistant messages (copy, regenerate)"
+      "Always set role — it drives alignment, avatar, and chrome",
+      "status covers pending, streaming, and error",
+      "Hide avatars with avatar={null}, or showAvatars={false} on ConversationList",
+      "User bubbles cap at 80% of the inline measure so the two sides stay distinct",
+      "Chrome stays on neutral surfaces; reserve accent for actions and semantic state",
+      "Add timestamps once a conversation runs long",
+      "Give assistant turns hover actions such as copy and regenerate"
     ],
     "accessibility": [
       "Uses semantic HTML for message structure",
@@ -96,43 +81,43 @@
   "examples": [
     {
       "name": "User Message",
-      "description": "Message from the user (right-aligned)",
+      "description": "Right-aligned and capped at 80% of the available width.",
       "code": "<Message role=\"user\">\n  <Message.Content>\n    Hello! Can you help me with a coding question?\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Assistant Message",
-      "description": "Response from the AI assistant",
+      "description": "Left-aligned with an avatar and a wider measure.",
       "code": "<Message role=\"assistant\">\n  <Message.Content>\n    Of course! I'd be happy to help. What would you like to know?\n  </Message.Content>\n</Message>"
     },
     {
       "name": "System Message",
-      "description": "System notification or context",
+      "description": "Centred and quiet, for context rather than conversation.",
       "code": "<Message role=\"system\">\n  <Message.Content>\n    Conversation started. Model: GPT-4\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Streaming",
-      "description": "Message being streamed (with cursor)",
+      "description": "A blinking caret trails the text as it arrives.",
       "code": "<Message role=\"assistant\" status=\"streaming\">\n  <Message.Content>\n    I'm currently generating a response for you\n  </Message.Content>\n</Message>"
     },
     {
       "name": "With Timestamp",
-      "description": "Message with timestamp display",
+      "description": "A relative send time sits beneath the bubble.",
       "code": "<Message role=\"assistant\" timestamp={new Date(Date.now() - 300000)}>\n  <Message.Content>\n    This message was sent 5 minutes ago.\n  </Message.Content>\n  <Message.Timestamp />\n</Message>"
     },
     {
       "name": "Error State",
-      "description": "Message that failed to send",
+      "description": "A failed send turns the bubble and its border red.",
       "code": "<Message role=\"user\" status=\"error\">\n  <Message.Content>\n    This message failed to send.\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Custom Avatars",
-      "description": "Messages with image-based avatars",
+      "description": "Photos replace the default glyphs on both sides.",
       "code": "<>\n  <Message\n    role=\"user\"\n    avatar={<Message.Avatar src=\"https://i.pravatar.cc/64?u=user\" alt=\"Jane\" />}\n  >\n    <Message.Content>\n      Can you help me understand this error?\n    </Message.Content>\n  </Message>\n  <Message\n    role=\"assistant\"\n    avatar={<Message.Avatar src=\"https://i.pravatar.cc/64?u=bot\" alt=\"AI Assistant\" />}\n  >\n    <Message.Content>\n      Sure! Let me take a look at that for you.\n    </Message.Content>\n  </Message>\n</>"
     },
     {
       "name": "With Actions",
-      "description": "Message with hover actions",
-      "code": "<Message\n  role=\"assistant\"\n  actions={\n    <>\n      <button style={{ padding: '4px 8px', fontSize: '12px' }}>Copy</button>\n      <button style={{ padding: '4px 8px', fontSize: '12px' }}>Regenerate</button>\n    </>\n  }\n>\n  <Message.Content>\n    Hover over this message to see the actions.\n  </Message.Content>\n</Message>"
+      "description": "Controls stay hidden until the pointer enters the row.",
+      "code": "<Message\n  role=\"assistant\"\n  actions={\n    <>\n      <Button variant=\"ghost\" size=\"sm\">\n        Copy\n      </Button>\n      <Button variant=\"ghost\" size=\"sm\">\n        Regenerate\n      </Button>\n    </>\n  }\n>\n  <Message.Content>\n    Hover over this message to see the actions.\n  </Message.Content>\n</Message>"
     }
   ],
   "relations": [
@@ -156,26 +141,18 @@
     "propsSummary": [
       "role: \"user\" | \"assistant\" | \"system\" - determines styling",
       "children: ReactNode - message content",
-      "status: \"sending\" | \"streaming\" | \"complete\" | \"error\" - message state",
+      "status: \"pending\" | \"streaming\" | \"complete\" | \"error\" - message state",
       "timestamp: Date - when message was sent",
       "avatar: ReactNode - custom avatar (null to hide)",
       "actions: ReactNode - hover actions",
       "Avatar.src: string - image URL for avatar",
       "Avatar.alt: string - alt text for image avatar"
     ],
-    "a11yRules": [
-      "A11Y_COLOR_CONTRAST",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_COLOR_CONTRAST", "A11Y_MOTION_PREFERENCE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Content",
-      "Actions",
-      "Timestamp",
-      "Avatar"
-    ]
+    "subComponents": ["Content", "Actions", "Timestamp", "Avatar"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Message/Message.module.scss

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/layout" as layout;
 @use "../../recipes/prose" as prose;
 @use "../../recipes/typography" as typography;
@@ -26,12 +27,16 @@
   flex-direction: row-reverse;
   margin-inline-start: auto;
 
+  // Cap against the conversation width, not the bubble's own shrink-wrapped
+  // width. On .content the percentage resolves against an already-collapsed
+  // parent and squeezes short messages until they break mid-word.
+  max-inline-size: 80%;
+
   .body {
     align-items: flex-end;
   }
 
   .content {
-    max-inline-size: 80%;
     background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
     color: var(--fui-text-primary, $fui-text-primary);
   }
@@ -58,13 +63,15 @@
 }
 
 .error .content {
-  border: var(--fui-stroke-hairline) solid var(--fui-color-danger-border, $fui-color-danger-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--fui-color-danger-border, $fui-color-danger-border);
   background: var(--fui-color-danger-bg, $fui-color-danger-bg);
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
-.sending {
-  opacity: 0.7;
+// In-flight messages dim with the one disabled opacity until they land.
+.pending {
+  opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
 }
 
 .avatar {
@@ -83,7 +90,7 @@
 }
 
 .avatarImage {
-  padding: 0;
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 .body {
@@ -102,7 +109,9 @@
   padding-block: layout.gap("sm");
   padding-inline: layout.gap("md");
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  overflow-wrap: anywhere;
+  // break-word, not anywhere: `anywhere` drops min-content to a single
+  // character, collapsing every shrink-to-fit ancestor around the bubble.
+  overflow-wrap: break-word;
 
   p {
     @include prose.paragraph;
@@ -119,7 +128,7 @@
     background-color: var(--fui-bg-subtle, $fui-bg-subtle);
 
     code {
-      padding: 0;
+      padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
       background: none;
       font: inherit;
       letter-spacing: inherit;
@@ -140,9 +149,9 @@
   display: inline-block;
   inline-size: 0.5em;
   block-size: 1em;
-  margin-inline-start: var(--fui-raw-space-2);
+  margin-inline-start: var(--fui-raw-space-2, #{measurements.raw-space(2)});
   background-color: currentColor;
-  animation: blink 1s step-end infinite;
+  animation: blink var(--fui-duration-pulse, $fui-duration-pulse) step-end infinite;
 }
 
 @keyframes blink {

package/src/components/Message/index.tsx

@@ -11,7 +11,7 @@ import { Markdown } from '../Markdown';
 // ============================================
 
 export type MessageRole = 'user' | 'assistant' | 'system';
-export type MessageStatus = 'sending' | 'streaming' | 'complete' | 'error';
+export type MessageStatus = 'pending' | 'streaming' | 'complete' | 'error';
 
 export interface MessageProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Message role determines styling and alignment */
@@ -264,7 +264,7 @@ function MessageRoot({
     styles.message,
     styles[role],
     status === 'error' && styles.error,
-    status === 'sending' && styles.sending,
+    status === 'pending' && styles.pending,
     !showAvatar && styles.withoutAvatar,
     className,
   ].filter(Boolean).join(' ');

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

@@ -1,18 +1,9 @@
 {
   "$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.",
+  "description": "Site navigation whose dropdowns become a drawer on small screens.",
   "category": "navigation",
-  "tags": [
-    "navigation",
-    "menu",
-    "header",
-    "dropdown",
-    "navbar",
-    "mobile",
-    "responsive",
-    "drawer"
-  ],
+  "tags": ["navigation", "menu", "header", "dropdown", "navbar", "mobile", "responsive", "drawer"],
   "status": "stable",
   "sourcePath": "src/components/NavigationMenu/index.tsx",
   "exportName": "NavigationMenu",
@@ -24,7 +15,8 @@
     "orientation: horizontal|vertical (default: horizontal)",
     "delayDuration: number (default: 200)",
     "skipDelayDuration: number (default: 300)",
-    "icons: object"
+    "icons: object",
+    "mobileBreakpoint: md|lg (default: md)"
   ],
   "props": {
     "children": {
@@ -53,10 +45,7 @@
       "description": "'horizontal' | 'vertical'",
       "default": "horizontal",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical"
-      ]
+      "values": ["horizontal", "vertical"]
     },
     "delayDuration": {
       "type": "number",
@@ -74,30 +63,37 @@
       "type": "object",
       "description": "Optional icon overrides for triggerChevron, mobileMenu, mobileClose, and drawerClose controls",
       "required": false
+    },
+    "mobileBreakpoint": {
+      "type": "enum",
+      "description": "Viewport breakpoint below which the mobile drawer replaces desktop navigation",
+      "default": "md",
+      "required": false,
+      "values": ["md", "lg"]
     }
   },
   "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"
+      "Header navigation with more than links",
+      "Dropdowns carrying titles, descriptions, or icons",
+      "Navigation that must survive a phone screen",
+      "Several sections that animate between each other"
     ],
     "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)"
+      "Flat links with no dropdowns (use Header.Nav)",
+      "Application actions like cut and paste (use Menu)",
+      "Persistent side navigation (use Sidebar)",
+      "Showing where the user already is (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"
+      "Place it inside Header for site-level navigation",
+      "Add Viewport to animate between panels",
+      "Use MobileContent for sections that only make sense in the drawer",
+      "Title plus description for rich panels, plain Link for the rest",
+      "asChild on Link composes your handler and honours preventDefault()",
+      "Desktop triggers open on hover after a configurable delay",
+      "Point icons at your own icon package to replace the chevrons",
+      "Set mobileBreakpoint=\"lg\" when the shell drops its sidebar below 1024px"
     ],
     "accessibility": [
       "Uses disclosure pattern (not menu role) per W3C guidance",
@@ -110,27 +106,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Two trigger items with dropdown content and one direct link",
+      "description": "Two dropdowns beside one plain 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",
+      "description": "A grid of 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",
+      "description": "Link lists where descriptions would be noise.",
       "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",
+      "description": "One promoted item leads the panel.",
       "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",
+      "description": "Panels open to the side instead of below.",
       "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>"
     }
   ],
@@ -163,15 +159,12 @@
       "orientation: horizontal | vertical — layout direction",
       "delayDuration: number — hover open delay (default: 200ms)",
       "icons: { triggerChevron?, mobileMenu?, mobileClose?, drawerClose? } — custom internal control icons",
+      "mobileBreakpoint: md | lg — mobile drawer breakpoint (default: md)",
       "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"
-    ]
+    "a11yRules": ["A11Y_DISCLOSURE_PATTERN", "A11Y_KEYBOARD_NAV", "A11Y_FOCUS_TRAP"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -187,9 +180,7 @@
       "MobileContent",
       "MobileSection"
     ],
-    "requiredChildren": [
-      "List"
-    ],
+    "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>"
     ]