@usefragments/ui 1.0.0

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

@@ -0,0 +1,238 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// ============================================
+// Message Root
+// ============================================
+
+.message {
+  display: flex;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    .actions {
+      opacity: 1;
+    }
+  }
+
+  &:focus-within {
+    .actions {
+      opacity: 1;
+    }
+  }
+}
+
+// Role-based styles
+.user {
+  flex-direction: row-reverse;
+  margin-left: auto;
+
+  .body {
+    align-items: flex-end;
+  }
+
+  .content {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+    color: var(--fui-color-on-accent, $fui-color-on-accent);
+  }
+}
+
+.assistant {
+  .content {
+    background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.system {
+  max-width: 100%;
+  justify-content: center;
+
+  .content {
+    background-color: var(--fui-color-info-bg, $fui-color-info-bg);
+    color: var(--fui-text-secondary, $fui-text-secondary);
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+    text-align: center;
+  }
+
+  .avatar {
+    display: none;
+  }
+}
+
+// Status styles
+.error {
+  .content {
+    background: var(--fui-color-danger-bg, $fui-color-danger-bg);
+    border: 1px solid var(--fui-color-danger-border, $fui-color-danger-border);
+    color: var(--fui-color-danger-text, $fui-color-danger-text);
+  }
+}
+
+.sending {
+  opacity: 0.7;
+}
+
+// ============================================
+// Avatar
+// ============================================
+
+.avatar {
+  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;
+  }
+}
+
+.avatarUser {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-color-on-accent, $fui-color-on-accent);
+}
+
+.avatarAssistant {
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
+.avatarSystem {
+  background-color: var(--fui-color-info-bg, $fui-color-info-bg);
+  color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.avatarImage {
+  padding: 0;
+  overflow: hidden;
+}
+
+.avatarImg {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+// ============================================
+// Body (content container)
+// ============================================
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-1, $fui-space-1);
+  min-width: 0;
+  flex: 1;
+}
+
+// ============================================
+// Content
+// ============================================
+
+.content {
+  @include text-base;
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  word-wrap: break-word;
+
+  // Prose styling for markdown content
+  p {
+    margin: 0;
+
+    & + p {
+      margin-top: var(--fui-space-2, $fui-space-2);
+    }
+  }
+
+  code {
+    font-family: var(--fui-font-mono, $fui-font-mono);
+    font-size: 0.9em;
+    padding: 0.125em 0.375em;
+    border-radius: var(--fui-radius-sm, $fui-radius-sm);
+    background-color: var(--fui-bg-subtle, $fui-bg-subtle);
+  }
+
+  pre {
+    margin: var(--fui-space-2, $fui-space-2) 0;
+    padding: var(--fui-space-2, $fui-space-2);
+    border-radius: var(--fui-radius-md, $fui-radius-md);
+    background-color: var(--fui-bg-subtle, $fui-bg-subtle);
+    overflow-x: auto;
+
+    code {
+      padding: 0;
+      background: none;
+    }
+  }
+
+  ul,
+  ol {
+    margin: var(--fui-space-2, $fui-space-2) 0;
+    padding-left: var(--fui-space-4, $fui-space-4);
+  }
+}
+
+.streaming {
+  &::after {
+    content: "";
+    display: inline-block;
+    width: 0.5em;
+    height: 1em;
+    margin-left: 2px;
+    background-color: currentColor;
+    animation: blink 1s step-end infinite;
+  }
+}
+
+@keyframes blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
+}
+
+// ============================================
+// Actions
+// ============================================
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  opacity: 0;
+  transition: opacity var(--fui-transition-fast, $fui-transition-fast);
+}
+
+// ============================================
+// Timestamp
+// ============================================
+
+.timestamp {
+  @include helper-text;
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+// ============================================
+// Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .streaming::after {
+    animation: none;
+  }
+}

package/src/components/Message/Message.stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Message } from '.';
+
+/**
+ * Individual chat message with role-based styling and alignment. Compose with
+ * `Message.Content`, `Message.Timestamp`, `Message.Avatar`, and `Message.Actions`.
+ */
+const meta = {
+  title: 'Ai/Message',
+  component: Message,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Chat message display with role-based styling for AI conversation UIs.',
+      },
+    },
+  },
+  argTypes: {
+    role: {
+      control: 'select',
+      options: ['user', 'assistant', 'system'],
+      description: 'Message role determines styling and alignment',
+    },
+    status: {
+      control: 'select',
+      options: ['sending', 'streaming', 'complete', 'error'],
+      description: 'Message state',
+    },
+  },
+  args: {
+    role: 'assistant',
+    status: 'complete',
+    children: <Message.Content>How can I help you today?</Message.Content>,
+  },
+} satisfies Meta<typeof Message>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const UserMessage: Story = {
+  args: {
+    role: 'user',
+    children: (
+      <Message.Content>Hello! Can you help me with a coding question?</Message.Content>
+    ),
+  },
+};
+
+export const AssistantMessage: Story = {
+  args: {
+    role: 'assistant',
+    children: (
+      <Message.Content>
+        Of course! I&apos;d be happy to help. What would you like to know?
+      </Message.Content>
+    ),
+  },
+};
+
+export const SystemMessage: Story = {
+  args: {
+    role: 'system',
+    children: <Message.Content>Conversation started.</Message.Content>,
+  },
+};
+
+export const Streaming: Story = {
+  args: {
+    role: 'assistant',
+    status: 'streaming',
+    children: (
+      <Message.Content>I&apos;m currently generating a response for you</Message.Content>
+    ),
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    role: 'user',
+    status: 'error',
+    children: <Message.Content>This message failed to send.</Message.Content>,
+  },
+};

package/src/components/Message/index.tsx

@@ -0,0 +1,293 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Message.module.scss';
+import { Markdown } from '../Markdown';
+
+// ============================================
+// Types
+// ============================================
+
+export type MessageRole = 'user' | 'assistant' | 'system';
+export type MessageStatus = 'sending' | 'streaming' | 'complete' | 'error';
+
+export interface MessageProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Message role determines styling and alignment */
+  role: MessageRole;
+  /** Message content */
+  children: React.ReactNode;
+  /** Message status */
+  status?: MessageStatus;
+  /** When the message was sent */
+  timestamp?: Date;
+  /** Custom avatar override */
+  avatar?: React.ReactNode;
+  /** Hover actions (copy, regenerate) */
+  actions?: React.ReactNode;
+}
+
+export interface MessageContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** When true, renders string children as markdown */
+  markdown?: boolean;
+}
+
+export interface MessageActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface MessageTimestampProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Date to format */
+  date?: Date;
+  /** Custom format function */
+  format?: (date: Date) => string;
+}
+
+export interface MessageAvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+  children?: React.ReactNode;
+  /** Image URL for the avatar */
+  src?: string;
+  /** Alt text for image avatars */
+  alt?: string;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface MessageContextValue {
+  role: MessageRole;
+  status: MessageStatus;
+  timestamp?: Date;
+}
+
+const MessageContext = React.createContext<MessageContextValue | null>(null);
+
+function useMessageContext() {
+  const context = React.useContext(MessageContext);
+  if (!context) {
+    throw new Error('Message compound components must be used within a Message');
+  }
+  return context;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function formatTimestamp(date: Date): string {
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+
+  if (minutes < 1) return 'Just now';
+  if (minutes < 60) return `${minutes}m ago`;
+  if (hours < 24) return `${hours}h ago`;
+
+  return date.toLocaleDateString(undefined, {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function UserIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" />
+    </svg>
+  );
+}
+
+function AssistantIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M19 9l1.25-2.75L23 5l-2.75-1.25L19 1l-1.25 2.75L15 5l2.75 1.25L19 9zm-7.5.5L9 4 6.5 9.5 1 12l5.5 2.5L9 20l2.5-5.5L17 12l-5.5-2.5zM19 15l-1.25 2.75L15 19l2.75 1.25L19 23l1.25-2.75L23 19l-2.75-1.25L19 15z" />
+    </svg>
+  );
+}
+
+function SystemIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-6h2v6zm0-8h-2V7h2v2z" />
+    </svg>
+  );
+}
+
+// ============================================
+// Sub-components
+// ============================================
+
+function MessageContent({ children, markdown, className, ...htmlProps }: MessageContentProps) {
+  const { status } = useMessageContext();
+
+  const classes = [
+    styles.content,
+    status === 'streaming' && styles.streaming,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const content = markdown && typeof children === 'string'
+    ? <Markdown content={children} />
+    : children;
+
+  return (
+    <div {...htmlProps} className={classes}>
+      {content}
+    </div>
+  );
+}
+
+function MessageActions({ children, className, ...htmlProps }: MessageActionsProps) {
+  const classes = [styles.actions, className].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+}
+
+function MessageTimestamp({
+  date,
+  format: customFormat,
+  className,
+  ...htmlProps
+}: MessageTimestampProps) {
+  const { timestamp } = useMessageContext();
+  const dateToFormat = date ?? timestamp;
+
+  if (!dateToFormat) return null;
+
+  const formatted = customFormat ? customFormat(dateToFormat) : formatTimestamp(dateToFormat);
+
+  const classes = [styles.timestamp, className].filter(Boolean).join(' ');
+
+  return (
+    <span {...htmlProps} className={classes}>
+      {formatted}
+    </span>
+  );
+}
+
+function MessageAvatar({ children, src, alt, className, ...htmlProps }: MessageAvatarProps) {
+  const { role } = useMessageContext();
+
+  const classes = [
+    styles.avatar,
+    styles[`avatar${role.charAt(0).toUpperCase() + role.slice(1)}`],
+    src && styles.avatarImage,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const defaultIcon = role === 'user'
+    ? <UserIcon />
+    : role === 'assistant'
+      ? <AssistantIcon />
+      : <SystemIcon />;
+
+  const content = children ?? (src
+    ? <img src={src} alt={alt ?? role} className={styles.avatarImg} />
+    : defaultIcon);
+
+  return (
+    <div {...htmlProps} className={classes}>
+      {content}
+    </div>
+  );
+}
+
+// ============================================
+// Main Component
+// ============================================
+
+function MessageRoot({
+  role,
+  children,
+  status = 'complete',
+  timestamp,
+  avatar,
+  actions,
+  className,
+  ...htmlProps
+}: MessageProps) {
+  const contextValue: MessageContextValue = {
+    role,
+    status,
+    timestamp,
+  };
+
+  const classes = [
+    styles.message,
+    styles[role],
+    status === 'error' && styles.error,
+    status === 'sending' && styles.sending,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <MessageContext.Provider value={contextValue}>
+      <div
+        {...htmlProps}
+        className={classes}
+        data-role={role}
+        data-status={status}
+      >
+        {avatar !== undefined ? avatar : <MessageAvatar />}
+        <div className={styles.body}>
+          {children}
+          {actions && <MessageActions>{actions}</MessageActions>}
+        </div>
+      </div>
+    </MessageContext.Provider>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Message = Object.assign(MessageRoot, {
+  Content: MessageContent,
+  Actions: MessageActions,
+  Timestamp: MessageTimestamp,
+  Avatar: MessageAvatar,
+});
+
+export {
+  MessageRoot,
+  MessageContent,
+  MessageActions,
+  MessageTimestamp,
+  MessageAvatar,
+};
+
+export { useMessageContext };