@crafter/rn-ai-elements 0.0.1

package/src/chatbot/index.ts

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// @crafter/rn-ai-elements/chatbot — public surface
+// ---------------------------------------------------------------------------
+
+// --- Conversation (generic list wrapper) -----------------------------------
+export { Conversation } from './Conversation';
+export type {
+  ConversationProps,
+  ConversationRef,
+  ConversationMessage,
+  ConversationMessageOrder,
+  ConversationScrollBehavior,
+} from './Conversation';
+
+// --- ConversationScrollButton (floating "scroll to latest" affordance) -----
+export { ConversationScrollButton } from './ConversationScrollButton';
+export type { ConversationScrollButtonProps } from './ConversationScrollButton';
+
+// --- ChatMessageItem (default assistant/user message composition) ---------
+export { ChatMessageItem } from './ChatMessageItem';
+export type { ChatMessageItemProps } from './ChatMessageItem';
+
+// --- ChatErrorBoundary (per-message error containment) --------------------
+export { ChatErrorBoundary } from './ChatErrorBoundary';
+export type { ChatErrorBoundaryProps } from './ChatErrorBoundary';
+
+// --- Canonical chat data types (consumed by ChatMessageItem) --------------
+export type {
+  ChatMessageData,
+  ChatReasoning,
+  ChatTool,
+} from './types';
+
+// --- AI SDK adapter -------------------------------------------------------
+export { uiMessageToChatMessageData } from './adapters/uiMessageAdapter';
+
+// --- Message compound (user bubbles + default content rendering) ----------
+export {
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageActions,
+} from './Message';
+export type {
+  ChatMessage,
+  MessageContextValue,
+  MessageProps,
+  MessageAvatarProps,
+  MessageContentProps,
+  MessageActionsProps,
+} from './Message';
+
+// --- PromptInput (sticky bottom input bar) --------------------------------
+export { PromptInput } from './PromptInput';
+export type {
+  PromptInputProps,
+  PromptInputRef,
+  PromptInputStatus,
+} from './PromptInput';
+
+// --- Reasoning ------------------------------------------------------------
+export { Reasoning } from './Reasoning';
+export type { ReasoningProps } from './Reasoning';
+
+// --- Suggestion -----------------------------------------------------------
+export { Suggestion } from './Suggestion';
+export type { SuggestionProps, SuggestionItem } from './Suggestion';
+
+// --- Shimmer --------------------------------------------------------------
+export { Shimmer } from './Shimmer';
+export type { ShimmerProps } from './Shimmer';
+
+// --- Tool -----------------------------------------------------------------
+export { Tool, ToolHeader, ToolArgs, ToolResult } from './Tool';
+export type {
+  ToolProps,
+  ToolStatus,
+  ToolHeaderProps,
+  ToolArgsProps,
+  ToolResultProps,
+} from './Tool';
+
+// --- Sources --------------------------------------------------------------
+export { Sources } from './Sources';
+export type { Source, SourcesProps } from './Sources';
+
+// --- Attachments ----------------------------------------------------------
+export { Attachments } from './Attachments';
+export type {
+  Attachment,
+  AttachmentVariant,
+  AttachmentsProps,
+} from './Attachments';
+
+// --- AIImage --------------------------------------------------------------
+export { AIImage } from './AIImage';
+export type { AIImageProps, AIImageSource } from './AIImage';

package/src/chatbot/types.ts

@@ -0,0 +1,66 @@
+import type { ChatMessage } from './Message';
+import type { Source } from './Sources';
+import type { ToolStatus } from './Tool';
+
+// ---------------------------------------------------------------------------
+// Canonical chat-message shape rendered by `ChatMessageItem`.
+// ---------------------------------------------------------------------------
+//
+// Real AI SDKs (Vercel `ai`, OpenAI, Anthropic) all expose a different set
+// of fields for streaming reasoning, tool calls, and sources. Rather than
+// pick one provider's shape, we define a small canonical type and ask
+// callers to map their messages to it inside their `renderMessage`. The
+// adapter is usually 5-10 lines and clarifies exactly what's being rendered.
+//
+// For `@ai-sdk/react` consumers, we ship a ready-made adapter —
+// `uiMessageToChatMessageData` — that handles the mapping from `UIMessage`
+// to this shape.
+// ---------------------------------------------------------------------------
+
+/** Reasoning ("thinking") content attached to an assistant message. */
+export interface ChatReasoning {
+  /** The reasoning text (rendered as markdown). */
+  content: string;
+  /** True while the reasoning is still streaming. */
+  isStreaming?: boolean;
+}
+
+/** A tool / function invocation attached to an assistant message. */
+export interface ChatTool {
+  /** Tool / function name (e.g. `"search_docs"`). */
+  name: string;
+  /** Lifecycle state. */
+  status: ToolStatus;
+  /** Arguments the tool was called with. */
+  args?: Record<string, unknown>;
+  /** Tool output, once the call resolves. */
+  result?: string;
+}
+
+/**
+ * The canonical message shape consumed by `ChatMessageItem`. Map your
+ * own message type to this shape inside your `renderMessage` callback.
+ *
+ * @example
+ * ```ts
+ * const data: ChatMessageData = {
+ *   id: msg.id,
+ *   role: msg.role,
+ *   content: msg.content,
+ *   reasoning: msg.reasoning && {
+ *     content: msg.reasoning,
+ *     isStreaming: msg.reasoningStreaming,
+ *   },
+ *   tool: msg.tool,
+ *   sources: msg.sources,
+ * };
+ * ```
+ */
+export interface ChatMessageData {
+  id: string;
+  role: ChatMessage['role'];
+  content: string;
+  reasoning?: ChatReasoning;
+  tool?: ChatTool;
+  sources?: Source[];
+}

package/src/hooks/index.ts

@@ -0,0 +1,17 @@
+export { useAutoScroll } from './useAutoScroll';
+export type { UseAutoScrollOptions, UseAutoScrollReturn } from './useAutoScroll';
+
+export { useClipboard } from './useClipboard';
+export type { UseClipboardReturn } from './useClipboard';
+
+export { useStickToBottom } from './useStickToBottom';
+export type {
+  UseStickToBottomOptions,
+  UseStickToBottomReturn,
+} from './useStickToBottom';
+
+export { useCollapsible } from './useCollapsible';
+export type {
+  UseCollapsibleOptions,
+  UseCollapsibleReturn,
+} from './useCollapsible';

package/src/hooks/useAutoScroll.ts

@@ -0,0 +1,43 @@
+import { useCallback, useRef } from 'react';
+import type { FlatList } from 'react-native';
+
+export interface UseAutoScrollOptions {
+  /** When true, auto-scrolls to bottom on content size changes. Defaults to `true`. */
+  enabled?: boolean;
+}
+
+export interface UseAutoScrollReturn<T = any> {
+  /** Ref to attach to your FlatList. */
+  ref: React.RefObject<FlatList<T> | null>;
+  /** Imperatively scroll to the end of the list. */
+  scrollToEnd: () => void;
+  /** Pass as the `onContentSizeChange` prop on your FlatList. */
+  onContentSizeChange: () => void;
+}
+
+/**
+ * Provides a FlatList ref and helpers that keep the list pinned to the bottom.
+ *
+ * ```tsx
+ * const { ref, onContentSizeChange } = useAutoScroll();
+ * <FlatList ref={ref} onContentSizeChange={onContentSizeChange} ... />
+ * ```
+ */
+export function useAutoScroll<T = any>(
+  options: UseAutoScrollOptions = {},
+): UseAutoScrollReturn<T> {
+  const { enabled = true } = options;
+  const ref = useRef<FlatList<T>>(null);
+
+  const scrollToEnd = useCallback(() => {
+    ref.current?.scrollToEnd({ animated: true });
+  }, []);
+
+  const onContentSizeChange = useCallback(() => {
+    if (enabled) {
+      ref.current?.scrollToEnd({ animated: true });
+    }
+  }, [enabled]);
+
+  return { ref, scrollToEnd, onContentSizeChange };
+}

package/src/hooks/useClipboard.ts

@@ -0,0 +1,46 @@
+import { useCallback, useRef, useState } from 'react';
+import { Clipboard } from 'react-native';
+
+export interface UseClipboardReturn {
+  /** Copy text to the clipboard. Resolves once the text has been written. */
+  copy: (text: string) => Promise<void>;
+  /** `true` for 2 seconds after a successful `copy` call, then resets. */
+  copied: boolean;
+}
+
+const RESET_DELAY_MS = 2_000;
+
+/**
+ * Thin wrapper around the system clipboard with a transient `copied` flag.
+ *
+ * Uses the built-in `react-native` Clipboard API. The implementation is
+ * isolated so it can be swapped for `@react-native-clipboard/clipboard`
+ * without changing the public interface.
+ *
+ * ```tsx
+ * const { copy, copied } = useClipboard();
+ * <Pressable onPress={() => copy(code)}>
+ *   <Text>{copied ? 'Copied!' : 'Copy'}</Text>
+ * </Pressable>
+ * ```
+ */
+export function useClipboard(): UseClipboardReturn {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const copy = useCallback(async (text: string): Promise<void> => {
+    Clipboard.setString(text);
+    setCopied(true);
+
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+    }
+
+    timerRef.current = setTimeout(() => {
+      setCopied(false);
+      timerRef.current = null;
+    }, RESET_DELAY_MS);
+  }, []);
+
+  return { copy, copied };
+}

package/src/hooks/useCollapsible.ts

@@ -0,0 +1,42 @@
+import { useCallback, useState } from 'react';
+
+export interface UseCollapsibleOptions {
+  /** Initial open state. Defaults to `false`. */
+  defaultOpen?: boolean;
+}
+
+export interface UseCollapsibleReturn {
+  /** Whether the collapsible section is currently open. */
+  isOpen: boolean;
+  /** Toggle between open and closed. */
+  toggle: () => void;
+  /** Set to open. */
+  open: () => void;
+  /** Set to closed. */
+  close: () => void;
+}
+
+/**
+ * Minimal state hook for a collapsible section.
+ *
+ * ```tsx
+ * const { isOpen, toggle } = useCollapsible({ defaultOpen: true });
+ *
+ * <Pressable onPress={toggle}>
+ *   <Text>{isOpen ? 'Hide' : 'Show'}</Text>
+ * </Pressable>
+ * {isOpen && <View>...</View>}
+ * ```
+ */
+export function useCollapsible(
+  options: UseCollapsibleOptions = {},
+): UseCollapsibleReturn {
+  const { defaultOpen = false } = options;
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+
+  const toggle = useCallback(() => setIsOpen((prev: boolean) => !prev), []);
+  const open = useCallback(() => setIsOpen(true), []);
+  const close = useCallback(() => setIsOpen(false), []);
+
+  return { isOpen, toggle, open, close };
+}

package/src/hooks/useStickToBottom.ts

@@ -0,0 +1,82 @@
+import { useCallback, useRef, useState } from 'react';
+import type {
+  FlatList,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+} from 'react-native';
+
+export interface UseStickToBottomOptions {
+  /** Distance (in px) from the bottom that still counts as "at the bottom". Defaults to `50`. */
+  threshold?: number;
+}
+
+export interface UseStickToBottomReturn<T = any> {
+  /** Whether the list is currently scrolled to (or near) the bottom. */
+  isAtBottom: boolean;
+  /** Imperatively scroll to the bottom. */
+  scrollToBottom: () => void;
+  /** Pass as the `onScroll` prop on your FlatList / ScrollView. */
+  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  /** Pass as the `onContentSizeChange` prop to auto-scroll when already at bottom. */
+  onContentSizeChange: () => void;
+  /** Ref to attach to your FlatList. */
+  ref: React.RefObject<FlatList<T> | null>;
+}
+
+/**
+ * Chat-style "stick to bottom" behaviour for a FlatList.
+ *
+ * When the user is scrolled to (or near) the bottom and new content arrives,
+ * the list automatically scrolls down. If the user scrolls up to read history,
+ * auto-scrolling pauses until they return to the bottom.
+ *
+ * ```tsx
+ * const { ref, onScroll, onContentSizeChange, isAtBottom, scrollToBottom } =
+ *   useStickToBottom();
+ *
+ * <FlatList
+ *   ref={ref}
+ *   onScroll={onScroll}
+ *   onContentSizeChange={onContentSizeChange}
+ *   scrollEventThrottle={16}
+ *   ...
+ * />
+ * ```
+ */
+export function useStickToBottom<T = any>(
+  options: UseStickToBottomOptions = {},
+): UseStickToBottomReturn<T> {
+  const { threshold = 50 } = options;
+  const ref = useRef<FlatList<T>>(null);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+
+  const onScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, contentSize, layoutMeasurement } =
+        event.nativeEvent;
+
+      const distanceFromBottom =
+        contentSize.height - layoutMeasurement.height - contentOffset.y;
+
+      setIsAtBottom(distanceFromBottom <= threshold);
+    },
+    [threshold],
+  );
+
+  const scrollToBottom = useCallback(() => {
+    ref.current?.scrollToEnd({ animated: true });
+  }, []);
+
+  // Keep a ref so the callback doesn't re-create on every isAtBottom change,
+  // but still reads the latest value.
+  const isAtBottomRef = useRef(isAtBottom);
+  isAtBottomRef.current = isAtBottom;
+
+  const onContentSizeChange = useCallback(() => {
+    if (isAtBottomRef.current) {
+      ref.current?.scrollToEnd({ animated: true });
+    }
+  }, []);
+
+  return { isAtBottom, scrollToBottom, onScroll, onContentSizeChange, ref };
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+// ---------------------------------------------------------------------------
+// @crafter/rn-ai-elements — public surface
+// ---------------------------------------------------------------------------
+
+// --- Theme ----------------------------------------------------------------
+export {
+  AIElementsProvider,
+  useAIElementsTheme,
+  lightTheme,
+  darkTheme,
+} from './theme';
+export type {
+  AIElementsProviderProps,
+  ColorSchemeMode,
+  AIElementsTheme,
+  ColorTokens,
+  SpacingTokens,
+  RadiusTokens,
+  TypographyTokens,
+} from './theme';
+
+// --- Primitives -----------------------------------------------------------
+export {
+  Button,
+  Badge,
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+  ScrollArea,
+} from './primitives';
+export type {
+  ButtonProps,
+  ButtonVariant,
+  ButtonSize,
+  BadgeProps,
+  BadgeVariant,
+  CardProps,
+  CardHeaderProps,
+  CardTitleProps,
+  CardDescriptionProps,
+  CardContentProps,
+  CardFooterProps,
+  CollapsibleProps,
+  CollapsibleTriggerProps,
+  CollapsibleContentProps,
+  ScrollAreaProps,
+} from './primitives';
+
+// --- Streaming Markdown ---------------------------------------------------
+export { StreamingMarkdown } from './streaming';
+export type { StreamingMarkdownProps } from './streaming';
+
+// --- Hooks ----------------------------------------------------------------
+export {
+  useAutoScroll,
+  useClipboard,
+  useStickToBottom,
+  useCollapsible,
+} from './hooks';
+export type {
+  UseAutoScrollOptions,
+  UseAutoScrollReturn,
+  UseClipboardReturn,
+  UseStickToBottomOptions,
+  UseStickToBottomReturn,
+  UseCollapsibleOptions,
+  UseCollapsibleReturn,
+} from './hooks';
+
+// --- Chatbot components ---------------------------------------------------
+export {
+  Conversation,
+  ConversationScrollButton,
+  ChatMessageItem,
+  ChatErrorBoundary,
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageActions,
+  PromptInput,
+  Reasoning,
+  Suggestion,
+  Shimmer,
+  Tool,
+  ToolHeader,
+  ToolArgs,
+  ToolResult,
+  Sources,
+  Attachments,
+  AIImage,
+  uiMessageToChatMessageData,
+} from './chatbot';
+
+// --- Chatbot types --------------------------------------------------------
+export type {
+  // Conversation
+  ConversationProps,
+  ConversationRef,
+  ConversationMessage,
+  ConversationMessageOrder,
+  ConversationScrollBehavior,
+  // ConversationScrollButton
+  ConversationScrollButtonProps,
+  // ChatMessageItem
+  ChatMessageItemProps,
+  // ChatErrorBoundary
+  ChatErrorBoundaryProps,
+  // Canonical message data
+  ChatMessageData,
+  ChatReasoning,
+  ChatTool,
+  // Message compound
+  ChatMessage,
+  MessageProps,
+  MessageAvatarProps,
+  MessageContentProps,
+  MessageActionsProps,
+  // PromptInput
+  PromptInputProps,
+  PromptInputRef,
+  PromptInputStatus,
+  // Others
+  ReasoningProps,
+  SuggestionProps,
+  ShimmerProps,
+  ToolProps,
+  ToolStatus,
+  Source,
+  SourcesProps,
+  Attachment,
+  AttachmentsProps,
+  AIImageProps,
+} from './chatbot';

package/src/primitives/Badge.tsx

@@ -0,0 +1,119 @@
+import React, { type ReactNode } from 'react';
+import {
+  View,
+  Text,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+  type TextStyle,
+} from 'react-native';
+import { useAIElementsTheme } from '../theme';
+import type { AIElementsTheme } from '../theme';
+
+export type BadgeVariant =
+  | 'default'
+  | 'secondary'
+  | 'outline'
+  | 'destructive'
+  | 'success'
+  | 'warning';
+
+export interface BadgeProps {
+  variant?: BadgeVariant;
+  children?: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+function getVariantStyles(
+  variant: BadgeVariant,
+  theme: AIElementsTheme
+): { container: ViewStyle; text: TextStyle } {
+  const { colors } = theme;
+
+  switch (variant) {
+    case 'default':
+      return {
+        container: { backgroundColor: colors.primary },
+        text: { color: colors.primaryForeground },
+      };
+    case 'secondary':
+      return {
+        container: { backgroundColor: colors.secondary },
+        text: { color: colors.secondaryForeground },
+      };
+    case 'outline':
+      return {
+        container: {
+          backgroundColor: 'transparent',
+          borderWidth: 1,
+          borderColor: colors.border,
+        },
+        text: { color: colors.foreground },
+      };
+    case 'destructive':
+      return {
+        container: { backgroundColor: colors.destructive },
+        text: { color: colors.destructiveForeground },
+      };
+    case 'success':
+      return {
+        container: { backgroundColor: colors.success },
+        text: { color: colors.successForeground },
+      };
+    case 'warning':
+      return {
+        container: { backgroundColor: colors.warning },
+        text: { color: colors.warningForeground },
+      };
+  }
+}
+
+export function Badge({ variant = 'default', children, style }: BadgeProps) {
+  const theme = useAIElementsTheme();
+  const variantStyles = getVariantStyles(variant, theme);
+
+  const textStyle: TextStyle = {
+    ...variantStyles.text,
+    fontSize: theme.typography.fontSize.xs,
+    fontWeight: theme.typography.fontWeight.semibold as TextStyle['fontWeight'],
+    fontFamily: theme.typography.fontFamily,
+    // Intentionally no lineHeight override — on iOS, lineHeight much larger
+    // than fontSize creates a tall line box with the glyph sitting at the
+    // baseline, which looks pushed-down inside a short pill. Letting RN use
+    // the native font metrics + the container's `alignItems: center` gives
+    // proper vertical centering.
+    textAlignVertical: 'center', // Android
+    includeFontPadding: false, // Android — strip extra font padding
+  };
+
+  return (
+    <View
+      style={[
+        styles.base,
+        { borderRadius: theme.radius.full },
+        variantStyles.container,
+        style,
+      ]}
+    >
+      {typeof children === 'string' ? (
+        <Text style={textStyle}>{children}</Text>
+      ) : (
+        children
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  base: {
+    alignSelf: 'flex-start',
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 10,
+    paddingVertical: 3,
+    // Consistent pill height regardless of rendered font metrics — keeps
+    // every variant the same visual size even when text differs.
+    minHeight: 22,
+  },
+});