@usefragments/ui 1.0.0

package/src/components/ConversationList/ConversationList.contract.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "ConversationList",
+  "description": "Scrollable message container with auto-scroll and history loading",
+  "category": "ai",
+  "tags": [
+    "conversation",
+    "chat",
+    "messages",
+    "scroll",
+    "ai",
+    "list"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/ConversationList/index.tsx",
+  "exportName": "ConversationList",
+  "propsSummary": [
+    "children: node (required)",
+    "autoScroll: union (default: smart)",
+    "onScrollTop: function",
+    "loadingHistory: boolean (default: false)",
+    "emptyState: node",
+    "scrollTopThreshold: number (default: 50)",
+    "scrollBottomThreshold: number (default: 100)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Message components",
+      "required": true
+    },
+    "autoScroll": {
+      "type": "union",
+      "description": "Auto-scroll behavior: true (always), false (never), or \"smart\" (only when near bottom)",
+      "default": "smart",
+      "required": false
+    },
+    "onScrollTop": {
+      "type": "function",
+      "description": "Callback when user scrolls to top (for loading history). Receives the scroll event.",
+      "required": false
+    },
+    "loadingHistory": {
+      "type": "boolean",
+      "description": "Show loading spinner at top when loading history",
+      "default": "false",
+      "required": false
+    },
+    "emptyState": {
+      "type": "node",
+      "description": "Content to show when conversation is empty",
+      "required": false
+    },
+    "scrollTopThreshold": {
+      "type": "number",
+      "description": "Pixels from top to trigger onScrollTop",
+      "default": "50",
+      "required": false
+    },
+    "scrollBottomThreshold": {
+      "type": "number",
+      "description": "Pixels from bottom for smart auto-scroll",
+      "default": "100",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Building a chat interface with multiple messages",
+      "Need auto-scroll behavior when new messages arrive",
+      "Require infinite scroll for loading message history",
+      "Want date separators between message groups"
+    ],
+    "whenNot": [
+      "Simple list of items without chat context (use List)",
+      "Single message display (use Message directly)",
+      "Non-scrolling message layout"
+    ],
+    "guidelines": [
+      "Use autoScroll=\"smart\" for best UX (only auto-scrolls when near bottom)",
+      "Implement onScrollTop for loading older messages",
+      "ConversationList composes your onScroll handler with internal auto-scroll/history logic",
+      "Provide an emptyState for new conversations",
+      "Use DateSeparator between messages from different days"
+    ],
+    "accessibility": [
+      "Uses proper ARIA roles for separators",
+      "Typing indicator has aria-label",
+      "Smooth scroll respects reduced motion preferences",
+      "Keyboard navigation works within scrollable container"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Basic",
+      "description": "Simple conversation with messages",
+      "code": "<ConversationList>\n  <Message role=\"user\">\n    <Message.Content>Hello!</Message.Content>\n  </Message>\n  <Message role=\"assistant\">\n    <Message.Content>Hi there! How can I help you today?</Message.Content>\n  </Message>\n  <Message role=\"user\">\n    <Message.Content>Can you explain React hooks?</Message.Content>\n  </Message>\n</ConversationList>"
+    },
+    {
+      "name": "With Date Separators",
+      "description": "Messages grouped by date",
+      "code": "<ConversationList>\n  <ConversationList.DateSeparator date={new Date(Date.now() - 86400000)} />\n  <Message role=\"user\">\n    <Message.Content>A message from yesterday</Message.Content>\n  </Message>\n  <ConversationList.DateSeparator date={new Date()} />\n  <Message role=\"assistant\">\n    <Message.Content>And a message from today!</Message.Content>\n  </Message>\n</ConversationList>"
+    },
+    {
+      "name": "With Typing Indicator",
+      "description": "Shows assistant is typing",
+      "code": "<ConversationList>\n  <Message role=\"user\">\n    <Message.Content>What is TypeScript?</Message.Content>\n  </Message>\n  <ConversationList.TypingIndicator name=\"Assistant\" />\n</ConversationList>"
+    },
+    {
+      "name": "Loading History",
+      "description": "Loading older messages",
+      "code": "<ConversationList loadingHistory>\n  <Message role=\"user\">\n    <Message.Content>This is the latest message</Message.Content>\n  </Message>\n</ConversationList>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Message",
+      "relationship": "child",
+      "note": "ConversationList contains Message components"
+    },
+    {
+      "component": "ThinkingIndicator",
+      "relationship": "child",
+      "note": "Show ThinkingIndicator at bottom while awaiting response"
+    },
+    {
+      "component": "Prompt",
+      "relationship": "sibling",
+      "note": "Typically paired with Prompt for input"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - Message components",
+      "autoScroll: boolean | \"smart\" - scroll behavior (default: \"smart\")",
+      "onScrollTop: (event?) => void - callback for loading history (receives scroll event)",
+      "loadingHistory: boolean - show history loading spinner",
+      "emptyState: ReactNode - empty conversation content"
+    ],
+    "a11yRules": [
+      "A11Y_ARIA_ROLES",
+      "A11Y_MOTION_PREFERENCE"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:53.889Z"
+  }
+}

package/src/components/ConversationList/ConversationList.module.scss

@@ -0,0 +1,160 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Conversation List Root
+// ============================================
+
+.conversationList {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scroll-behavior: smooth;
+
+  // Smooth scroll on reduced motion
+  @media (prefers-reduced-motion: reduce) {
+    scroll-behavior: auto;
+  }
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-3, $fui-space-3);
+  min-height: 100%;
+}
+
+// ============================================
+// Loading History
+// ============================================
+
+.loadingHistory {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-3, $fui-space-3);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.spinner {
+  animation: spin 1s linear infinite;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+// ============================================
+// Date Separator
+// ============================================
+
+.dateSeparator {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-2, $fui-space-2) 0;
+}
+
+.dateSeparatorLine {
+  flex: 1;
+  height: 1px;
+  background-color: var(--fui-border, $fui-border);
+}
+
+.dateSeparatorText {
+  @include helper-text;
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  white-space: nowrap;
+  text-transform: uppercase;
+  letter-spacing: var(--fui-letter-spacing-wide, $fui-letter-spacing-wide);
+}
+
+// ============================================
+// Typing Indicator
+// ============================================
+
+.typingIndicator {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-2, $fui-space-2);
+}
+
+.typingAvatar {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+.typingContent {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--fui-space-px, $fui-space-px) * 4);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+}
+
+.typingDot {
+  width: 6px;
+  height: 6px;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  animation: bounce 1.4s ease-in-out infinite;
+
+  &:nth-child(1) {
+    animation-delay: 0s;
+  }
+
+  &:nth-child(2) {
+    animation-delay: 0.2s;
+  }
+
+  &:nth-child(3) {
+    animation-delay: 0.4s;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 0.6;
+  }
+}
+
+@keyframes bounce {
+  0%,
+  60%,
+  100% {
+    transform: translateY(0);
+    opacity: 0.4;
+  }
+  30% {
+    transform: translateY(-$fui-anim-offset-sm);
+    opacity: 1;
+  }
+}

package/src/components/ConversationList/ConversationList.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ConversationList } from '.';
+
+/**
+ * Scrollable message container with auto-scroll and history loading.
+ * Holds message children, with autoScroll behavior (true/false/"smart"),
+ * an optional empty state, and ConversationList.DateSeparator /
+ * ConversationList.TypingIndicator subcomponents.
+ */
+const meta = {
+  title: 'Ai/ConversationList',
+  component: ConversationList,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Scrollable message container with auto-scroll and history loading.',
+      },
+    },
+  },
+  argTypes: {
+    loadingHistory: {
+      control: 'boolean',
+      description: 'Show loading spinner at top while loading history',
+    },
+  },
+  args: {
+    autoScroll: 'smart',
+    loadingHistory: false,
+    children: (
+      <>
+        <div>Hello!</div>
+        <div>Hi there! How can I help you today?</div>
+      </>
+    ),
+  },
+} satisfies Meta<typeof ConversationList>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <ConversationList {...args} style={{ height: 280 }}>
+      <div>Hello!</div>
+      <div>Hi there! How can I help you today?</div>
+      <div>Can you explain React hooks?</div>
+    </ConversationList>
+  ),
+};
+
+export const WithDateSeparators: Story = {
+  render: (args) => (
+    <ConversationList {...args} style={{ height: 280 }}>
+      <ConversationList.DateSeparator date={new Date(Date.now() - 86400000)} />
+      <div>A message from yesterday</div>
+      <ConversationList.DateSeparator date={new Date()} />
+      <div>And a message from today!</div>
+    </ConversationList>
+  ),
+};
+
+export const WithTypingIndicator: Story = {
+  render: (args) => (
+    <ConversationList {...args} style={{ height: 280 }}>
+      <div>What is TypeScript?</div>
+      <ConversationList.TypingIndicator name="Assistant" />
+    </ConversationList>
+  ),
+};
+
+export const LoadingHistory: Story = {
+  args: { loadingHistory: true },
+  render: (args) => (
+    <ConversationList {...args} style={{ height: 280 }}>
+      <div>This is the latest message</div>
+    </ConversationList>
+  ),
+};
+
+export const Empty: Story = {
+  render: (args) => (
+    <ConversationList
+      {...args}
+      style={{ height: 280 }}
+      emptyState={<div>Start the conversation</div>}
+    >
+      {null}
+    </ConversationList>
+  ),
+};

package/src/components/ConversationList/index.tsx

@@ -0,0 +1,257 @@
+'use client';
+
+import * as React from 'react';
+import styles from './ConversationList.module.scss';
+import { Loading } from '../Loading';
+
+// ============================================
+// Types
+// ============================================
+
+export type AutoScrollBehavior = boolean | 'smart';
+
+export interface ConversationListProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Message components */
+  children: React.ReactNode;
+  /** Auto-scroll behavior: true (always), false (never), or 'smart' (only when near bottom) */
+  autoScroll?: AutoScrollBehavior;
+  /** Callback when user scrolls to top (for loading history) */
+  onScrollTop?: (event?: React.UIEvent<HTMLDivElement>) => void;
+  /** Show loading spinner at top when loading history */
+  loadingHistory?: boolean;
+  /** Content to show when conversation is empty */
+  emptyState?: React.ReactNode;
+  /** Threshold in pixels from top to trigger onScrollTop */
+  scrollTopThreshold?: number;
+  /** Threshold in pixels from bottom for smart auto-scroll */
+  scrollBottomThreshold?: number;
+}
+
+export interface DateSeparatorProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Date to display */
+  date: Date;
+  /** Custom format function */
+  format?: (date: Date) => string;
+}
+
+export interface TypingIndicatorProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Who is typing */
+  name?: string;
+  /** Custom avatar */
+  avatar?: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface ConversationListContextValue {
+  scrollToBottom: () => void;
+}
+
+const ConversationListContext = React.createContext<ConversationListContextValue | null>(null);
+
+export function useConversationList() {
+  const context = React.useContext(ConversationListContext);
+  if (!context) {
+    throw new Error('useConversationList must be used within a ConversationList');
+  }
+  return context;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function formatDateSeparator(date: Date): string {
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const yesterday = new Date(today.getTime() - 86400000);
+  const dateOnly = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+
+  if (dateOnly.getTime() === today.getTime()) {
+    return 'Today';
+  }
+  if (dateOnly.getTime() === yesterday.getTime()) {
+    return 'Yesterday';
+  }
+
+  return date.toLocaleDateString(undefined, {
+    weekday: 'long',
+    month: 'long',
+    day: 'numeric',
+  });
+}
+
+
+// ============================================
+// Sub-components
+// ============================================
+
+function DateSeparator({
+  date,
+  format: customFormat,
+  className,
+  ...htmlProps
+}: DateSeparatorProps) {
+  const formatted = customFormat ? customFormat(date) : formatDateSeparator(date);
+
+  const classes = [styles.dateSeparator, className].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={classes} role="separator">
+      <span className={styles.dateSeparatorLine} />
+      <span className={styles.dateSeparatorText}>{formatted}</span>
+      <span className={styles.dateSeparatorLine} />
+    </div>
+  );
+}
+
+function TypingIndicator({
+  name = 'Assistant',
+  avatar,
+  className,
+  ...htmlProps
+}: TypingIndicatorProps) {
+  const classes = [styles.typingIndicator, className].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={classes} aria-label={`${name} is typing`}>
+      {avatar && <div className={styles.typingAvatar}>{avatar}</div>}
+      <div className={styles.typingContent}>
+        <span className={styles.typingDot} />
+        <span className={styles.typingDot} />
+        <span className={styles.typingDot} />
+      </div>
+    </div>
+  );
+}
+
+// ============================================
+// Main Component
+// ============================================
+
+function ConversationListRoot({
+  children,
+  autoScroll = 'smart',
+  onScrollTop,
+  loadingHistory = false,
+  emptyState,
+  scrollTopThreshold = 50,
+  scrollBottomThreshold = 100,
+  className,
+  ...htmlProps
+}: ConversationListProps) {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const contentRef = React.useRef<HTMLDivElement>(null);
+  const isNearBottomRef = React.useRef(true);
+  const prevChildrenCountRef = React.useRef(0);
+  const userOnScroll = htmlProps.onScroll;
+
+  // Check if user is near the bottom
+  const checkIsNearBottom = React.useCallback(() => {
+    const container = containerRef.current;
+    if (!container) return true;
+
+    const { scrollTop, scrollHeight, clientHeight } = container;
+    return scrollHeight - scrollTop - clientHeight <= scrollBottomThreshold;
+  }, [scrollBottomThreshold]);
+
+  // Scroll to bottom
+  const scrollToBottom = React.useCallback((behavior: ScrollBehavior = 'smooth') => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    container.scrollTo({
+      top: container.scrollHeight,
+      behavior,
+    });
+  }, []);
+
+  // Handle scroll events
+  const handleScroll = React.useCallback((event: React.UIEvent<HTMLDivElement>) => {
+    userOnScroll?.(event);
+    if (event.defaultPrevented) return;
+
+    const container = containerRef.current;
+    if (!container) return;
+
+    // Update near-bottom status for smart scroll
+    isNearBottomRef.current = checkIsNearBottom();
+
+    // Check for scroll-to-top (history loading)
+    if (onScrollTop && container.scrollTop <= scrollTopThreshold) {
+      onScrollTop(event);
+    }
+  }, [checkIsNearBottom, onScrollTop, scrollTopThreshold, userOnScroll]);
+
+  // Auto-scroll on new messages
+  React.useEffect(() => {
+    const childrenCount = React.Children.count(children);
+    const hasNewMessages = childrenCount > prevChildrenCountRef.current;
+    prevChildrenCountRef.current = childrenCount;
+
+    if (!hasNewMessages) return;
+
+    if (autoScroll === true) {
+      scrollToBottom();
+    } else if (autoScroll === 'smart' && isNearBottomRef.current) {
+      scrollToBottom();
+    }
+  }, [children, autoScroll, scrollToBottom]);
+
+  // Initial scroll to bottom
+  React.useEffect(() => {
+    if (autoScroll) {
+      scrollToBottom('instant');
+    }
+  }, [autoScroll, scrollToBottom]);
+
+  const contextValue: ConversationListContextValue = {
+    scrollToBottom,
+  };
+
+  const hasChildren = React.Children.count(children) > 0;
+
+  const classes = [
+    styles.conversationList,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <ConversationListContext.Provider value={contextValue}>
+      <div
+        {...htmlProps}
+        ref={containerRef}
+        className={classes}
+        onScroll={handleScroll}
+      >
+        {loadingHistory && (
+          <div className={styles.loadingHistory}>
+            <Loading size="md" variant="spinner" color="muted" label="Loading history" />
+            <span>Loading history...</span>
+          </div>
+        )}
+
+        <div ref={contentRef} className={styles.content}>
+          {hasChildren ? children : emptyState}
+        </div>
+      </div>
+    </ConversationListContext.Provider>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const ConversationList = Object.assign(ConversationListRoot, {
+  DateSeparator,
+  TypingIndicator,
+});
+
+export {
+  ConversationListRoot,
+  DateSeparator,
+  TypingIndicator,
+};