@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Command/index.tsx

@@ -1,7 +1,7 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './Command.module.scss';
+import * as React from "react";
+import styles from "./Command.module.scss";
 
 // ============================================
 // Types
@@ -30,7 +30,7 @@ export interface CommandListProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
 }
 
-export interface CommandItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+export interface CommandItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
   children: React.ReactNode;
   /** Value used for filtering (falls back to text content) */
   value?: string;
@@ -78,13 +78,13 @@ function defaultFilter(value: string, search: string, keywords?: string[]): numb
 }
 
 function getTextContent(node: React.ReactNode): string {
-  if (typeof node === 'string' || typeof node === 'number') return String(node);
-  if (Array.isArray(node)) return node.map(getTextContent).join(' ');
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(getTextContent).join(" ");
   if (React.isValidElement(node)) {
     const childProps = node.props as { children?: React.ReactNode };
     return getTextContent(childProps.children);
   }
-  return '';
+  return "";
 }
 
 // ============================================
@@ -115,7 +115,7 @@ const CommandContext = React.createContext<CommandContextValue | null>(null);
 
 function useCommandContext() {
   const ctx = React.useContext(CommandContext);
-  if (!ctx) throw new Error('Command sub-components must be used within <Command>');
+  if (!ctx) throw new Error("Command sub-components must be used within <Command>");
   return ctx;
 }
 
@@ -150,7 +150,7 @@ function SearchIcon() {
 function CommandRoot({
   children,
   search: controlledSearch,
-  defaultSearch = '',
+  defaultSearch = "",
   onSearchChange,
   filter = defaultFilter,
   loop = true,
@@ -231,14 +231,25 @@ function CommandRoot({
       visibleCount,
       listId,
     }),
-    [search, setSearch, filter, scores, registerItem, unregisterItem, activeId, loop, visibleCount, listId]
+    [
+      search,
+      setSearch,
+      filter,
+      scores,
+      registerItem,
+      unregisterItem,
+      activeId,
+      loop,
+      visibleCount,
+      listId,
+    ]
   );
 
   return (
     <CommandContext.Provider value={contextValue}>
       <div
         {...htmlProps}
-        className={[styles.command, className].filter(Boolean).join(' ')}
+        className={[styles.command, className].filter(Boolean).join(" ")}
         role="search"
       >
         {children}
@@ -247,12 +258,7 @@ function CommandRoot({
   );
 }
 
-function CommandInput({
-  className,
-  onChange,
-  onKeyDown,
-  ...htmlProps
-}: CommandInputProps) {
+function CommandInput({ className, onChange, onKeyDown, ...htmlProps }: CommandInputProps) {
   const { search, setSearch, listRef, setActiveId, activeId, loop, listId } = useCommandContext();
   const inputRef = React.useRef<HTMLInputElement>(null);
 
@@ -261,7 +267,7 @@ function CommandInput({
     if (!list) return [];
     return Array.from(
       list.querySelectorAll<HTMLElement>('[data-command-item]:not([data-disabled="true"])')
-    ).filter((el) => el.style.display !== 'none');
+    ).filter((el) => el.style.display !== "none");
   }, [listRef]);
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
@@ -270,45 +276,48 @@ function CommandInput({
 
     const items = getEnabledItems();
     if (items.length === 0) return;
+    const firstItem = items[0];
+    const lastItem = items.at(-1);
+    if (!firstItem || !lastItem) return;
 
-    const currentIndex = activeId
-      ? items.findIndex((item) => item.id === activeId)
-      : -1;
+    const currentIndex = activeId ? items.findIndex((item) => item.id === activeId) : -1;
 
     switch (event.key) {
-      case 'ArrowDown': {
+      case "ArrowDown": {
         event.preventDefault();
         if (currentIndex < 0) {
-          setActiveId(items[0].id);
+          setActiveId(firstItem.id);
         } else if (currentIndex < items.length - 1) {
-          setActiveId(items[currentIndex + 1].id);
+          const nextItem = items[currentIndex + 1];
+          if (nextItem) setActiveId(nextItem.id);
         } else if (loop) {
-          setActiveId(items[0].id);
+          setActiveId(firstItem.id);
         }
         break;
       }
-      case 'ArrowUp': {
+      case "ArrowUp": {
         event.preventDefault();
         if (currentIndex < 0) {
-          setActiveId(items[items.length - 1].id);
+          setActiveId(lastItem.id);
         } else if (currentIndex > 0) {
-          setActiveId(items[currentIndex - 1].id);
+          const previousItem = items[currentIndex - 1];
+          if (previousItem) setActiveId(previousItem.id);
         } else if (loop) {
-          setActiveId(items[items.length - 1].id);
+          setActiveId(lastItem.id);
         }
         break;
       }
-      case 'Home': {
+      case "Home": {
         event.preventDefault();
-        setActiveId(items[0].id);
+        setActiveId(firstItem.id);
         break;
       }
-      case 'End': {
+      case "End": {
         event.preventDefault();
-        setActiveId(items[items.length - 1].id);
+        setActiveId(lastItem.id);
         break;
       }
-      case 'Enter': {
+      case "Enter": {
         event.preventDefault();
         if (activeId) {
           const activeItem = items.find((item) => item.id === activeId);
@@ -343,7 +352,7 @@ function CommandInput({
           setSearch(e.target.value);
         }}
         onKeyDown={handleKeyDown}
-        className={[styles.input, className].filter(Boolean).join(' ')}
+        className={[styles.input, className].filter(Boolean).join(" ")}
       />
     </div>
   );
@@ -358,7 +367,7 @@ function CommandList({ children, className, ...htmlProps }: CommandListProps) {
       {...htmlProps}
       id={listId}
       role="listbox"
-      className={[styles.list, className].filter(Boolean).join(' ')}
+      className={[styles.list, className].filter(Boolean).join(" ")}
     >
       {children}
     </div>
@@ -402,11 +411,13 @@ function CommandItem({
   // Scroll active item into view
   React.useEffect(() => {
     if (isActive && itemRef.current) {
-      itemRef.current.scrollIntoView({ block: 'nearest' });
+      itemRef.current.scrollIntoView({ block: "nearest" });
     }
   }, [isActive]);
 
-  const activateItem = (event: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>) => {
+  const activateItem = (
+    event: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>
+  ) => {
     if (disabled) return;
     onItemSelect?.(textValue, event);
   };
@@ -440,7 +451,7 @@ function CommandItem({
       onKeyDown={(e) => {
         onKeyDown?.(e);
         if (e.defaultPrevented) return;
-        if (e.key === 'Enter' || e.key === ' ') {
+        if (e.key === "Enter" || e.key === " ") {
           e.preventDefault();
           activateItem(e);
         }
@@ -453,8 +464,8 @@ function CommandItem({
         className,
       ]
         .filter(Boolean)
-        .join(' ')}
-      style={{ ...style, display: isVisible ? undefined : 'none' }}
+        .join(" ")}
+      style={{ ...style, display: isVisible ? undefined : "none" }}
     >
       {children}
     </div>
@@ -470,8 +481,8 @@ function CommandGroup({ children, heading, className, ...htmlProps }: CommandGro
   // Check if any children are visible after each score update
   React.useEffect(() => {
     if (!groupRef.current) return;
-    const items = groupRef.current.querySelectorAll<HTMLElement>('[data-command-item]');
-    const anyVisible = Array.from(items).some((item) => item.style.display !== 'none');
+    const items = groupRef.current.querySelectorAll<HTMLElement>("[data-command-item]");
+    const anyVisible = Array.from(items).some((item) => item.style.display !== "none");
     setHasVisibleChildren(anyVisible);
   }, [scores]);
 
@@ -483,8 +494,8 @@ function CommandGroup({ children, heading, className, ...htmlProps }: CommandGro
       {...restHtmlProps}
       role="group"
       aria-labelledby={heading ? labelId : undefined}
-      className={[styles.group, className].filter(Boolean).join(' ')}
-      style={{ ...style, display: hasVisibleChildren ? undefined : 'none' }}
+      className={[styles.group, className].filter(Boolean).join(" ")}
+      style={{ ...style, display: hasVisibleChildren ? undefined : "none" }}
     >
       {heading && (
         <div id={labelId} className={styles.groupHeading}>
@@ -507,7 +518,7 @@ function CommandEmpty({ children, className, ...htmlProps }: CommandEmptyProps)
       role="option"
       aria-disabled="true"
       aria-selected="false"
-      className={[styles.empty, className].filter(Boolean).join(' ')}
+      className={[styles.empty, className].filter(Boolean).join(" ")}
     >
       {children}
     </div>
@@ -519,7 +530,7 @@ function CommandSeparator({ className, ...htmlProps }: CommandSeparatorProps) {
     <div
       {...htmlProps}
       role="separator"
-      className={[styles.separator, className].filter(Boolean).join(' ')}
+      className={[styles.separator, className].filter(Boolean).join(" ")}
     />
   );
 }

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

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ConversationList",
-  "description": "Scrollable message container with auto-scroll and history loading",
+  "description": "Stacks chat messages in a scroller that follows new arrivals.",
   "category": "ai",
-  "tags": [
-    "conversation",
-    "chat",
-    "messages",
-    "scroll",
-    "ai",
-    "list"
-  ],
+  "tags": ["conversation", "chat", "messages", "scroll", "ai", "list"],
   "status": "stable",
   "sourcePath": "src/components/ConversationList/index.tsx",
   "exportName": "ConversationList",
@@ -73,24 +66,24 @@
   },
   "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"
+      "Chat interfaces holding many messages",
+      "Transcripts that should follow new arrivals",
+      "Paging back through older message history",
+      "Runs of messages grouped day by day"
     ],
     "whenNot": [
-      "Simple list of items without chat context (use List)",
-      "Single message display (use Message directly)",
-      "Non-scrolling message layout"
+      "Plain item lists with no chat context (use List)",
+      "A single message (use Message directly)",
+      "Layouts that never scroll"
     ],
     "guidelines": [
-      "Use autoScroll=\"smart\" for best UX (only auto-scrolls when near bottom)",
-      "Set showAvatars={false} for avatarless transcripts; messages remove their outer inline inset automatically",
-      "Conversation chrome uses neutral surfaces and the body foreground; reserve brand accent for actions or semantic state",
-      "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"
+      "autoScroll=\"smart\" follows only when the reader is already near the bottom",
+      "showAvatars={false} drops the avatar gutter and the inset that goes with it",
+      "Chrome stays on neutral surfaces; reserve accent for actions and semantic state",
+      "Implement onScrollTop to page in older messages",
+      "Your onScroll handler composes with the internal auto-scroll and history logic",
+      "Give new conversations an emptyState",
+      "Put a DateSeparator between messages from different days"
     ],
     "accessibility": [
       "Uses proper ARIA roles for separators",
@@ -102,28 +95,33 @@
   "examples": [
     {
       "name": "Basic",
-      "description": "Simple conversation with messages",
+      "description": "Three turns stacked in reading order.",
       "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",
+      "description": "A labelled rule marks where one day ends.",
       "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": "Without Avatars",
-      "description": "Compact transcript without message or typing-indicator avatars",
+      "description": "Turns sit flush when nothing needs an avatar gutter.",
       "code": "<ConversationList showAvatars={false}>\n  <Message role=\"user\">\n    <Message.Content>Hello!</Message.Content>\n  </Message>\n  <Message role=\"assistant\">\n    <Message.Content>How can I help?</Message.Content>\n  </Message>\n</ConversationList>"
     },
     {
       "name": "With Typing Indicator",
-      "description": "Shows assistant is typing",
+      "description": "Animated dots hold the reply's place before it lands.",
       "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",
+      "description": "A spinner pins to the top while older turns load.",
       "code": "<ConversationList loadingHistory>\n  <Message role=\"user\">\n    <Message.Content>This is the latest message</Message.Content>\n  </Message>\n</ConversationList>"
+    },
+    {
+      "name": "Empty",
+      "description": "A fresh conversation shows its placeholder instead of blank space.",
+      "code": "<ConversationList\n  emptyState={\n    <EmptyState>\n      <EmptyState.Title>No messages yet</EmptyState.Title>\n      <EmptyState.Description>\n        Ask a question to get started.\n      </EmptyState.Description>\n    </EmptyState>\n  }\n/>"
     }
   ],
   "relations": [
@@ -152,10 +150,7 @@
       "loadingHistory: boolean - show history loading spinner",
       "emptyState: ReactNode - empty conversation content"
     ],
-    "a11yRules": [
-      "A11Y_ARIA_ROLES",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_ARIA_ROLES", "A11Y_MOTION_PREFERENCE"]
   },
   "provenance": {
     "source": "migrated",

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

@@ -1,5 +1,7 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../recipes/layout" as layout;
+@use "../../recipes/representation" as representation;
+@use "../../recipes/typography" as typography;
 
 // ============================================
 // Conversation List Root
@@ -23,8 +25,8 @@
 .content {
   display: flex;
   flex-direction: column;
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-space-3, $fui-space-3);
+  gap: layout.gap("md");
+  padding: layout.gap("lg");
   min-height: 100%;
   // Own the full height of the conversation. As a shrinkable flex item it was
   // squashed to the height of the scroll port while its messages overflowed
@@ -43,27 +45,10 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-space-3, $fui-space-3);
+  gap: layout.gap("sm");
+  padding: layout.gap("md");
   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);
-  }
+  @include typography.role("caption");
 }
 
 // ============================================
@@ -73,19 +58,19 @@
 .dateSeparator {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-space-2, $fui-space-2) 0;
+  gap: layout.gap("sm");
+  padding-block: layout.gap("sm");
 }
 
 .dateSeparatorLine {
   flex: 1;
-  height: 1px;
+  height: var(--fui-stroke-hairline, 1px);
   background-color: var(--fui-border, $fui-border);
 }
 
 .dateSeparatorText {
-  @include helper-text;
-  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  @include typography.role("ui-compact");
+
   color: var(--fui-text-secondary, $fui-text-secondary);
   white-space: nowrap;
   text-transform: uppercase;
@@ -99,8 +84,8 @@
 .typingIndicator {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-space-2, $fui-space-2);
+  gap: layout.gap("sm");
+  padding: layout.gap("sm");
 }
 
 .withoutAvatar {
@@ -112,61 +97,18 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  width: 2rem;
-  height: 2rem;
+  inline-size: representation.avatar-size("sm");
+  block-size: representation.avatar-size("sm");
   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);
+  padding-block: layout.gap("sm");
+  padding-inline: layout.gap("md");
   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;
-  }
-}