@usefragments/ui 1.0.0

package/src/components/Menu/index.tsx

@@ -0,0 +1,411 @@
+'use client';
+
+import * as React from 'react';
+import { Menu as BaseMenu } from '@base-ui/react/menu';
+import styles from './Menu.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface MenuProps {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  modal?: boolean;
+}
+
+type MenuTriggerAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  children: React.ReactNode;
+  asChild?: false;
+};
+type MenuTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+export type MenuTriggerProps = MenuTriggerAsButtonProps | MenuTriggerAsChildProps;
+
+export interface MenuContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+}
+
+export interface MenuItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children' | 'onSelect'> {
+  children: React.ReactNode;
+  disabled?: boolean;
+  danger?: boolean;
+  onSelect?: (event: React.MouseEvent<HTMLElement>) => void;
+  icon?: React.ReactNode;
+  shortcut?: string;
+  /** When passed, renders a check indicator. `true` shows a checkmark, `false` reserves space. */
+  checked?: boolean;
+}
+
+export interface MenuCheckboxItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children' | 'onChange'> {
+  children: React.ReactNode;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  disabled?: boolean;
+}
+
+export interface MenuRadioGroupProps {
+  children: React.ReactNode;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+}
+
+export interface MenuRadioItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+  value: string;
+  disabled?: boolean;
+}
+
+export interface MenuGroupProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+export interface MenuGroupLabelProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+export type MenuSeparatorProps = React.HTMLAttributes<HTMLElement>;
+
+export interface MenuSubmenuProps {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface MenuSubmenuTriggerProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  disabled?: boolean;
+  icon?: React.ReactNode;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function CheckmarkIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={3}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M5 13l4 4L19 7" />
+    </svg>
+  );
+}
+
+function DotIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="12"
+      height="12"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <circle cx="12" cy="12" r="5" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function MenuRoot({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal = true,
+}: MenuProps) {
+  return (
+    <BaseMenu.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      modal={modal}
+    >
+      {children}
+    </BaseMenu.Root>
+  );
+}
+
+function MenuTrigger({ children, asChild, className, ...htmlProps }: MenuTriggerProps) {
+  if (asChild) {
+    if (!React.isValidElement(children)) {
+      throw new Error('Menu.Trigger with asChild requires a single valid React element child.');
+    }
+    return (
+      <BaseMenu.Trigger {...htmlProps} className={className} render={children as React.ReactElement}>
+        {null}
+      </BaseMenu.Trigger>
+    );
+  }
+
+  return (
+    <BaseMenu.Trigger
+      {...htmlProps}
+      type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
+      className={className}
+    >
+      {children}
+    </BaseMenu.Trigger>
+  );
+}
+
+function MenuContent({
+  children,
+  className,
+  side = 'bottom',
+  align = 'start',
+  sideOffset = 4,
+  ...htmlProps
+}: MenuContentProps) {
+  const popupClasses = [styles.popup, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseMenu.Portal>
+      <BaseMenu.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        className={styles.positioner}
+      >
+        <BaseMenu.Popup {...htmlProps} className={popupClasses}>
+          <BaseMenu.Viewport className={styles.viewport}>
+            {children}
+          </BaseMenu.Viewport>
+        </BaseMenu.Popup>
+      </BaseMenu.Positioner>
+    </BaseMenu.Portal>
+  );
+}
+
+function MenuItem({
+  children,
+  disabled,
+  danger,
+  onSelect,
+  className,
+  icon,
+  shortcut,
+  checked,
+  ...htmlProps
+}: MenuItemProps) {
+  const handleClick = React.useCallback(
+    (event: React.MouseEvent<HTMLElement>) => {
+      (htmlProps.onClick as React.MouseEventHandler<HTMLElement> | undefined)?.(event);
+      onSelect?.(event);
+    },
+    [htmlProps, onSelect],
+  );
+
+  const hasChecked = checked !== undefined;
+  const classes = [
+    styles.item,
+    danger && styles.itemDanger,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <BaseMenu.Item
+      {...htmlProps}
+      disabled={disabled}
+      onClick={handleClick as React.MouseEventHandler<HTMLElement>}
+      className={classes}
+    >
+      {hasChecked && (
+        <span className={styles.checkIndicator}>
+          {checked ? <CheckmarkIcon /> : null}
+        </span>
+      )}
+      {icon && <span className={styles.itemIcon}>{icon}</span>}
+      <span className={styles.itemLabel}>{children}</span>
+      {shortcut && <span className={styles.itemShortcut}>{shortcut}</span>}
+    </BaseMenu.Item>
+  );
+}
+
+function MenuCheckboxItem({
+  children,
+  checked: checkedProp,
+  defaultChecked,
+  onCheckedChange,
+  disabled,
+  className,
+  ...htmlProps
+}: MenuCheckboxItemProps) {
+  const isControlled = checkedProp !== undefined;
+  const [internalChecked, setInternalChecked] = React.useState(defaultChecked ?? false);
+  const visualChecked = isControlled ? checkedProp : internalChecked;
+
+  const handleCheckedChange = React.useCallback(
+    (value: boolean) => {
+      if (!isControlled) setInternalChecked(value);
+      onCheckedChange?.(value);
+    },
+    [isControlled, onCheckedChange],
+  );
+
+  const classes = [styles.item, styles.checkboxItem, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseMenu.CheckboxItem
+      {...htmlProps}
+      checked={checkedProp}
+      defaultChecked={defaultChecked}
+      onCheckedChange={handleCheckedChange}
+      disabled={disabled}
+      className={classes}
+    >
+      <span className={styles.checkIndicator}>
+        {visualChecked ? <CheckmarkIcon /> : null}
+      </span>
+      <span className={styles.itemLabel}>{children}</span>
+    </BaseMenu.CheckboxItem>
+  );
+}
+
+function MenuRadioGroup({
+  children,
+  value,
+  defaultValue,
+  onValueChange,
+}: MenuRadioGroupProps) {
+  return (
+    <BaseMenu.RadioGroup
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={onValueChange}
+    >
+      {children}
+    </BaseMenu.RadioGroup>
+  );
+}
+
+function MenuRadioItem({
+  children,
+  value,
+  disabled,
+  className,
+  ...htmlProps
+}: MenuRadioItemProps) {
+  const classes = [styles.item, styles.radioItem, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseMenu.RadioItem {...htmlProps} value={value} disabled={disabled} className={classes}>
+      <span className={styles.radioIndicator}>
+        <DotIcon />
+      </span>
+      <span className={styles.itemLabel}>{children}</span>
+    </BaseMenu.RadioItem>
+  );
+}
+
+function MenuGroup({ children, className, ...htmlProps }: MenuGroupProps) {
+  const classes = [styles.group, className].filter(Boolean).join(' ');
+  return <BaseMenu.Group {...htmlProps} className={classes}>{children}</BaseMenu.Group>;
+}
+
+function MenuGroupLabel({ children, className, ...htmlProps }: MenuGroupLabelProps) {
+  const classes = [styles.groupLabel, className].filter(Boolean).join(' ');
+  return <BaseMenu.GroupLabel {...htmlProps} className={classes}>{children}</BaseMenu.GroupLabel>;
+}
+
+function MenuSeparator({ className, ...htmlProps }: MenuSeparatorProps) {
+  const classes = [styles.separator, className].filter(Boolean).join(' ');
+  return <BaseMenu.Separator {...htmlProps} className={classes} />;
+}
+
+function MenuSubmenu({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+}: MenuSubmenuProps) {
+  return (
+    <BaseMenu.SubmenuRoot
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+    >
+      {children}
+    </BaseMenu.SubmenuRoot>
+  );
+}
+
+function MenuSubmenuTrigger({
+  children,
+  disabled,
+  className,
+  icon,
+  ...htmlProps
+}: MenuSubmenuTriggerProps) {
+  const classes = [styles.item, styles.submenuTrigger, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseMenu.SubmenuTrigger {...htmlProps} disabled={disabled} className={classes}>
+      {icon && <span className={styles.itemIcon}>{icon}</span>}
+      <span className={styles.itemLabel}>{children}</span>
+    </BaseMenu.SubmenuTrigger>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Menu = Object.assign(MenuRoot, {
+  Trigger: MenuTrigger,
+  Content: MenuContent,
+  Item: MenuItem,
+  CheckboxItem: MenuCheckboxItem,
+  RadioGroup: MenuRadioGroup,
+  RadioItem: MenuRadioItem,
+  Group: MenuGroup,
+  GroupLabel: MenuGroupLabel,
+  Separator: MenuSeparator,
+  Submenu: MenuSubmenu,
+  SubmenuTrigger: MenuSubmenuTrigger,
+});
+
+// Re-export individual components
+export {
+  MenuRoot,
+  MenuTrigger,
+  MenuContent,
+  MenuItem,
+  MenuCheckboxItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuSeparator,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
+};

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

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Message",
+  "description": "Individual chat message display with role-based styling",
+  "category": "ai",
+  "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)",
+    "timestamp: object",
+    "avatar: node",
+    "actions: node"
+  ],
+  "props": {
+    "role": {
+      "type": "enum",
+      "description": "Message role determines styling and alignment",
+      "required": true,
+      "values": [
+        "user",
+        "assistant",
+        "system"
+      ]
+    },
+    "children": {
+      "type": "node",
+      "description": "Message content",
+      "required": true
+    },
+    "status": {
+      "type": "enum",
+      "description": "Message state",
+      "default": "complete",
+      "required": false,
+      "values": [
+        "sending",
+        "streaming",
+        "complete",
+        "error"
+      ]
+    },
+    "timestamp": {
+      "type": "object",
+      "description": "When the message was sent",
+      "required": false
+    },
+    "avatar": {
+      "type": "node",
+      "description": "Custom avatar override (null to hide)",
+      "required": false
+    },
+    "actions": {
+      "type": "node",
+      "description": "Hover actions (copy, regenerate)",
+      "required": false
+    }
+  },
+  "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"
+    ],
+    "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)"
+    ],
+    "guidelines": [
+      "Always provide a role prop to determine styling",
+      "Use status prop to show message state (sending, streaming, error)",
+      "Consider showing timestamps for longer conversations",
+      "Provide hover actions for assistant messages (copy, regenerate)"
+    ],
+    "accessibility": [
+      "Uses semantic HTML for message structure",
+      "Role-based styling has sufficient color contrast",
+      "Actions are keyboard accessible",
+      "Streaming indicator respects reduced motion preferences"
+    ]
+  },
+  "examples": [
+    {
+      "name": "User Message",
+      "description": "Message from the user (right-aligned)",
+      "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",
+      "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",
+      "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)",
+      "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",
+      "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",
+      "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",
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "ConversationList",
+      "relationship": "parent",
+      "note": "Messages are typically used within ConversationList"
+    },
+    {
+      "component": "Avatar",
+      "relationship": "child",
+      "note": "Use Avatar component for custom avatar content"
+    },
+    {
+      "component": "ThinkingIndicator",
+      "relationship": "sibling",
+      "note": "Show ThinkingIndicator while awaiting assistant response"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "role: \"user\" | \"assistant\" | \"system\" - determines styling",
+      "children: ReactNode - message content",
+      "status: \"sending\" | \"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"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Content",
+      "Actions",
+      "Timestamp",
+      "Avatar"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:00.333Z"
+  }
+}