@thewhileloop/whileui 4.0.0 → 4.1.1

package/README.md

@@ -11,6 +11,18 @@ production targets — iOS and Android set the interaction baseline. See
 [ROADMAP.md](./ROADMAP.md) for the product boundary and extraction rules, and
 [PLAN.md](./PLAN.md) for the supported stack and production contracts.
 
+## See it in action
+
+One React Native component contract across native and web, with semantic typography,
+token-driven light and dark themes, accessible controls, and application-owned chat
+composition. The same component tree can feel airy and atmospheric or compact and
+editorial by changing tokens alone.
+
+<p align="center">
+  <img src="./docs/assets/whileui-showcase.gif" width="300" alt="WhileUI Cosmic Aura mobile theme demonstrating light and dark modes, controls, Select, and composable chat" />
+  <img src="./docs/assets/whileui-showcase-atelier.gif" width="300" alt="WhileUI Atelier mobile theme demonstrating compact controls, authentication forms, Select, and composable chat" />
+</p>
+
 ## Installation
 
 ```bash
@@ -18,6 +30,8 @@ bun add @thewhileloop/whileui
 bun add react@^19.3.0 react-native@^0.88.0 uniwind@^1.12.2 tailwindcss@^4.0.0 react-native-reanimated react-native-safe-area-context react-native-screens
 # Only if you use Select, Popover, Tooltip, or HoverCard:
 bun add @rn-primitives/portal @rn-primitives/hooks @rn-primitives/slot @rn-primitives/select @rn-primitives/popover @rn-primitives/tooltip @rn-primitives/hover-card
+# Only if you import @thewhileloop/whileui/markdown:
+bun add markdown-it
 ```
 
 Use `npm install` instead of `bun add` if you prefer npm.
@@ -230,17 +244,33 @@ function MyScreen() {
   `@source './node_modules/@thewhileloop/whileui/dist';` or every component renders unstyled.
 - **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
 
+### Composition grammar
+
+- Start with one page canvas and flat sections. Add a `Surface` only when grouping or
+  elevation communicates something; do not wrap every section in a card.
+- Use `level="base"` for grouped content, `raised` for selectable or floating regions,
+  and `overlay` for content above the page. Avoid nesting more than one surfaced level.
+- Express hierarchy through `Text` variants before custom font-size classes. Keep one
+  primary action per region and constrain long-form content with `Container`.
+- Forms use `FormField`; its disabled and invalid state flows into `Input`, `Textarea`,
+  `NumericInput`, and `Select`. Pass a control prop only to override that inherited state.
+- Chat mechanics belong to `ChatConversation` + `SmartInput`. Message payloads, tools,
+  reasoning, approvals, sources, and action rows are application-owned compositions.
+- Import Markdown and code rendering from their optional subpaths. Do not make the root
+  package pay for content rendering when the screen does not use it.
+
 ## Components
 
 ### Primitives
 
-| Component     | Notes                            |
-| ------------- | -------------------------------- |
-| **Text**      | Themed text with variant support |
-| **View**      | Themed view wrapper              |
-| **Pressable** | Themed pressable wrapper         |
-| **Stack**     | Vertical flex layout with gap    |
-| **Row**       | Horizontal flex layout with gap  |
+| Component     | Notes                                            |
+| ------------- | ------------------------------------------------ |
+| **Text**      | Themed text with variant support                 |
+| **Surface**   | Token-backed base, raised, and overlay container |
+| **View**      | Themed view wrapper                              |
+| **Pressable** | Themed pressable wrapper                         |
+| **Stack**     | Vertical flex layout with gap                    |
+| **Row**       | Horizontal flex layout with gap                  |
 
 ### Root Providers
 
@@ -273,6 +303,7 @@ function MyScreen() {
 | Component       | Variants                                                | Notes                                                                           |
 | --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | **Card**        | padding (none, sm, default, lg), unstyled               | Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter |
+| **Surface**     | level (base, raised, overlay)                           | Shared radius, padding, border, shadow, and optional frosted treatment          |
 | **Badge**       | default, secondary, destructive, outline, success       | BadgeText sub-component                                                         |
 | **FAB**         | default, secondary, destructive, surface; sm/default/lg | Floating action button. `label` required; pass your own icon as children        |
 | **Alert**       | default, destructive, success, warning                  | AlertTitle & AlertDescription                                                   |
@@ -364,11 +395,12 @@ Copy from `apps/showcase/templates/auth/`:
 
 ### Chat
 
-| Block                 | Description                                      |
-| --------------------- | ------------------------------------------------ |
-| **Chat**              | AI-style chat: messages, suggestions, SmartInput |
-| **ChatMessageBubble** | Message bubble (user/assistant, big/small text)  |
-| **ChatSuggestions**   | Suggestion chips when empty                      |
+| Block                 | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| **Chat**              | Opinionated messages, suggestions, and SmartInput composition   |
+| **ChatConversation**  | Constrained conversation viewport that follows streaming output |
+| **ChatMessageBubble** | Message bubble (user/assistant, big/small text)                 |
+| **ChatSuggestions**   | Suggestion chips when empty                                     |
 
 ### Profile & Settings (Copy from showcase templates)
 
@@ -405,9 +437,9 @@ Copy from `apps/showcase/templates/profile/`:
 
 ### Media
 
-| Block          | Description                         |
-| -------------- | ----------------------------------- |
-| **SmartImage** | Image with aspect ratio and loading |
+| Block          | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| **SmartImage** | Image with explicit loading, loaded, fallback, and error lifecycle |
 
 ### Date Picker
 
@@ -447,6 +479,11 @@ soft variant, overlay, surface, interaction state and shadow. Those are exactly
 `deriveThemeColors` computes, so hand-writing them produces a second derivation that
 drifts from the library's. Override a derived value by assigning to the result.
 
+`WHILEUI_PRESET_SOFT` is the airy default. `WHILEUI_PRESET_ATELIER` is the stronger
+product preset: tighter geometry, opaque surfaces, firmer borders, real shadows, and no
+blur. Use it as the acceptance check that a screen still has enough visual weight when
+the soft treatment is removed.
+
 ### FAB
 
 One primary action, raised above the content. It owns no icon dependency — pass the
@@ -558,7 +595,7 @@ import { AppShell, Header, BottomNav, ScrollView } from '@thewhileloop/whileui';
 | Forms      | FormField + Input/NumericInput/LabeledField + DatePickerModal + FormModalScreen    |
 | Settings   | ProfileHeader + SettingsSection + SettingsItem (+ FormModalScreen for edits)       |
 | E-commerce | ProductCard list → CheckoutSummary + ActionBar                                     |
-| Chat       | Chat + ChatSuggestions + SmartInput (attach, send). Extensible for images/tags     |
+| Chat       | Chat, or ChatConversation + SmartInput for custom message/tool/source compositions |
 | App shell  | AppShell + Header + BottomNav + content                                            |
 | Loading    | AppShell (`loading`) + PageSkeleton/ScreenSkeleton (keep header mounted)           |
 
@@ -901,6 +938,9 @@ const adapter: ThemeBridgeAdapter = {
 const { mode, resolvedTheme, setMode, cycleMode } = useThemeBridge({ adapter });
 ```
 
+The bridge loads a new adapter before saving into it. If a user changes the mode while
+storage is still loading, that explicit choice wins over the late persisted value.
+
 When another store already owns the mode, mount the controlled bridge once near the
 application root. Change `mode` in the owning event handler; the bridge applies and
 persists it without mirroring state back through a callback effect.
@@ -1000,6 +1040,17 @@ import { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';
 | loading   | `boolean`                                                                     | `false`     | Show a spinner, expose busy state, and block input |
 | className | `string`                                                                      | —           | Additional Tailwind classes                        |
 
+## Text
+
+`Text` maps semantic roles to the active visual typography tokens; custom font-size
+classes are unnecessary for normal hierarchy. `heading` also sets
+`accessibilityRole="header"` unless the caller supplies another role.
+
+| Prop    | Type                                                                                          | Default     |
+| ------- | --------------------------------------------------------------------------------------------- | ----------- |
+| variant | `'default' \| 'heading' \| 'title' \| 'subtitle' \| 'body' \| 'caption' \| 'label' \| 'code'` | `'default'` |
+| size    | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`                                    | by variant  |
+
 ## Input
 
 ```tsx
@@ -1008,6 +1059,9 @@ import { Input } from '@thewhileloop/whileui';
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
 ```
 
+On web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their
+themed background, foreground, and caret when the browser autofills them.
+
 | Prop                 | Type                              | Default     | Description                                                           |
 | -------------------- | --------------------------------- | ----------- | --------------------------------------------------------------------- |
 | variant              | `'default' \| 'error' \| 'plain'` | `'default'` | Input style; `plain` drops border and fill for a large display figure |
@@ -1088,6 +1142,30 @@ import {
 </FormField>;
 ```
 
+`invalid` and `disabled` are inherited by `Input`, `Textarea`, `NumericInput`, and
+`Select`. An explicit control prop wins. `useFormFieldState()` exposes the same state for
+custom controls; labels, hints, messages, density, and required indicators remain part
+of the compound field rather than each input.
+
+## Surface
+
+```tsx
+import { Surface } from '@thewhileloop/whileui';
+
+<Surface level="raised" padding="default">
+  {/* grouped content */}
+</Surface>;
+```
+
+| Prop     | Type                                  | Default     | Description                         |
+| -------- | ------------------------------------- | ----------- | ----------------------------------- |
+| level    | `'base' \| 'raised' \| 'overlay'`     | `'base'`    | Semantic background and depth tier  |
+| padding  | `'none' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Token-backed interior spacing       |
+| radius   | `'sm' \| 'md' \| 'lg' \| 'xl'`        | `'xl'`      | Token-backed corner radius          |
+| bordered | `boolean`                             | `true`      | Draw the theme hairline border      |
+| shadow   | `'none' \| 'sm' \| 'md' \| 'lg'`      | by level    | Override the level's depth          |
+| frosted  | `boolean`                             | `false`     | Enable the optional frosted overlay |
+
 ## LabeledField
 
 ```tsx
@@ -1380,6 +1458,12 @@ import {
 </Select>;
 ```
 
+Focused and pressed options use the subtle interaction-state tokens; the primary token
+marks the selected indicator without replacing the option's foreground colour. Long
+selected values stay on one line and truncate without displacing the trigger chevron.
+For popover presentation on web, the options panel matches the trigger width, caps
+itself to the collision-available viewport, and wraps long option labels inside it.
+
 `SelectContent` supports optional frosted props:
 
 | Prop          | Type                                                               | Default       |
@@ -1440,7 +1524,7 @@ import {
 import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 
 <Avatar size="default">
-  <AvatarImage src="https://..." />
+  <AvatarImage source={{ uri: 'https://...' }} />
   <AvatarFallback>JD</AvatarFallback>
 </Avatar>;
 ```
@@ -1449,6 +1533,10 @@ import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 | ---- | --------------------------- | ----------- |
 | size | `'sm' \| 'default' \| 'lg'` | `'default'` |
 
+`AvatarImage` keeps `AvatarFallback` visible while loading or after an error. Its
+`onLoadingStatusChange` callback reports `'loading'`, `'loaded'`, and `'error'`, including
+when a changed source begins loading, while the standard image event callbacks still run.
+
 ## Progress
 
 ```tsx
@@ -1485,6 +1573,9 @@ toast({ title: 'Success', description: 'Saved!', variant: 'success' });
 | variant       | `'default' \| 'success' \| 'destructive'` |
 | duration      | `number` (ms)                             |
 
+Each toast owns its duration from the moment it appears; adding or dismissing another
+toast does not restart timers already in progress.
+
 ## Popover
 
 ```tsx
@@ -1738,9 +1829,34 @@ import { SmartInput, Button, ButtonText } from '@thewhileloop/whileui';
 />;
 ```
 
-## Chat
+## ChatConversation / Chat
 
-AI-style chat: message list, suggestion chips when empty, SmartInput with attach/send slots. Uses semantic tokens; theme via `global.css`. Copy-paste block — edit directly. `renderMessage` for markdown/code, `loadingIndicator` for typing state.
+`ChatConversation` is the low-level viewport for custom conversation screens. Its content stays constrained on wide windows, follows new or streaming output while the reader is near the bottom, and stops following after the reader scrolls upward. Compose it with `SmartInput`; the application owns message data, streaming, tools, approvals, and sources.
+
+It is a `ScrollView` for a bounded active transcript. Paginate or window historical messages; use a virtualized list when the full history can grow without a bound.
+
+```tsx
+import { ChatConversation, SmartInput, View } from '@thewhileloop/whileui';
+
+<View className="flex-1">
+  <ChatConversation contentContainerClassName="gap-4 px-4 py-6">
+    {messages.map((message) => (
+      <ProductMessage key={message.id} message={message} />
+    ))}
+  </ChatConversation>
+  <SmartInput
+    value={value}
+    onChangeText={setValue}
+    onSubmitEditing={send}
+    submitBehavior="submit"
+    leftSlot={<AttachButton />}
+    centerSlot={<ModelSelect />}
+    rightSlot={<SendButton />}
+  />
+</View>;
+```
+
+`Chat` is the opinionated convenience composition: message bubbles, suggestion chips, and `SmartInput` with attach/send slots. It uses semantic tokens; theme via `global.css`. Use `renderMessage` for markdown, code, tool calls, reasoning, or sources, and `loadingIndicator` for streaming feedback.
 
 ```tsx
 import { Chat, type ChatMessage } from '@thewhileloop/whileui';
@@ -1777,6 +1893,56 @@ const [value, setValue] = useState('');
 | `inputSafeArea`          | `boolean`            | SmartInput safe-area (default `true`)             |
 | `keyboardVerticalOffset` | `number`             | For header offset when keyboard opens             |
 
+`ChatConversation` extends React Native `ScrollViewProps`, forwards its ref, and adds `contentContainerClassName` to style the constrained inner column. Caller `onScroll` and `onContentSizeChange` callbacks are preserved.
+
+### Optional Markdown and code
+
+These are explicit subpaths so the root package remains independent of a Markdown
+parser. Install `markdown-it` only in applications that render Markdown.
+
+```tsx
+import { Markdown } from '@thewhileloop/whileui/markdown';
+import { CodeBlock } from '@thewhileloop/whileui/code';
+
+<Markdown onLinkPress={openLink}>{assistantText}</Markdown>
+<CodeBlock code={source} language="TypeScript" actions={<CopyButton />} />
+```
+
+`Markdown` supports headings, paragraphs, emphasis, links, lists, quotes, rules, inline
+code, and fenced code. It never opens links or writes to the clipboard itself:
+`onLinkPress` and `codeActions` keep those capabilities in the application. `CodeBlock`
+is dependency-free and accepts an application-owned `actions` slot.
+
+## SmartImage
+
+```tsx
+import { SmartImage } from '@thewhileloop/whileui';
+
+<SmartImage
+  source={{ uri: imageUrl }}
+  fallbackSource={{ uri: fallbackUrl }}
+  alt="Product preview"
+  className="h-48 w-full"
+/>;
+```
+
+| Prop                | Type                                               | Default   |
+| ------------------- | -------------------------------------------------- | --------- |
+| `source`            | `ImageProps['source']`                             | required  |
+| `alt`               | `string`                                           | required  |
+| `fallbackSource`    | `ImageProps['source']`                             | —         |
+| `skeleton`          | `boolean`                                          | `true`    |
+| `skeletonClassName` | `string`                                           | —         |
+| `transition`        | `number`                                           | `200`     |
+| `radius`            | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`    |
+| `objectFit`         | `'cover' \| 'contain' \| 'fill' \| 'scale-down'`   | `'cover'` |
+| `onLoad`            | `() => void`                                       | —         |
+| `onError`           | `() => void`                                       | —         |
+
+The skeleton returns whenever the primary image starts loading again. A failed primary
+source switches to `fallbackSource` when supplied without re-entering a primary/fallback
+loop.
+
 ## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal
 
 Date selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.
@@ -2298,7 +2464,7 @@ Tracked work items for future releases.
 ### Documentation Gaps
 
 - [ ] Add `## API` sections for: Textarea, Toggle, ToggleGroup, Label, Separator, Skeleton, AspectRatio, Collapsible, Text, View
-- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, SmartImage, TimelineFeed
+- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, TimelineFeed
 
 ### Infrastructure
 

package/dist/blocks/chat/chat-conversation.d.ts

@@ -0,0 +1,8 @@
+import { type ScrollViewInstance, type ScrollViewProps } from 'react-native';
+import type { ForwardRefComponent } from '../../lib/ref-types';
+/** ScrollView viewport for a bounded active transcript; virtualize unbounded history. */
+export interface ChatConversationProps extends ScrollViewProps {
+    contentContainerClassName?: string;
+}
+declare const ChatConversation: ForwardRefComponent<ScrollViewInstance, ChatConversationProps>;
+export { ChatConversation };

package/dist/blocks/chat/chat-conversation.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useCallback, useRef } from 'react';
+import { ScrollView, View, } from 'react-native';
+import { cn } from '../../lib/cn';
+const BOTTOM_THRESHOLD = 48;
+function assignRef(ref, value) {
+    if (typeof ref === 'function') {
+        ref(value);
+    }
+    else if (ref) {
+        ref.current = value;
+    }
+}
+const ChatConversation = React.forwardRef(({ className, contentContainerClassName, contentContainerStyle, keyboardShouldPersistTaps = 'handled', onContentSizeChange, onScroll, scrollEventThrottle = 64, children, ...props }, forwardedRef) => {
+    const scrollRef = useRef(null);
+    const followsOutputRef = useRef(true);
+    const setRef = useCallback((instance) => {
+        scrollRef.current = instance;
+        assignRef(forwardedRef, instance);
+    }, [forwardedRef]);
+    const handleScroll = useCallback((event) => {
+        const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+        const distanceFromBottom = contentSize.height - layoutMeasurement.height - contentOffset.y;
+        followsOutputRef.current = distanceFromBottom <= BOTTOM_THRESHOLD;
+        onScroll?.(event);
+    }, [onScroll]);
+    const handleContentSizeChange = useCallback((width, height) => {
+        onContentSizeChange?.(width, height);
+        if (followsOutputRef.current) {
+            scrollRef.current?.scrollToEnd({ animated: true });
+        }
+    }, [onContentSizeChange]);
+    return (_jsx(ScrollView, { ref: setRef, className: cn('flex-1', className), contentContainerStyle: { flexGrow: 1 }, keyboardShouldPersistTaps: keyboardShouldPersistTaps, onContentSizeChange: handleContentSizeChange, onScroll: handleScroll, scrollEventThrottle: scrollEventThrottle, ...props, children: _jsx(View, { className: cn('w-full max-w-3xl flex-1 self-center', contentContainerClassName), style: contentContainerStyle, children: children }) }));
+});
+ChatConversation.displayName = 'ChatConversation';
+export { ChatConversation };

package/dist/blocks/chat/chat.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { useRef, useEffect } from 'react';
-import { View, ScrollView, Pressable, KeyboardAvoidingView, Platform, useWindowDimensions, } from 'react-native';
+import React from 'react';
+import { View, Pressable, KeyboardAvoidingView, Platform, useWindowDimensions } from 'react-native';
 import { Text } from '../../components/text';
 import { SmartInput } from '../layout/smart-input';
+import { ChatConversation } from './chat-conversation';
 import { cn } from '../../lib/cn';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
@@ -49,23 +50,16 @@ export function ChatSuggestions({ suggestions, onSelect, className }) {
 }
 const EMPTY_SUGGESTIONS = [];
 export function Chat({ messages, value, onChangeText, onSend, placeholder = 'Message...', suggestions = EMPTY_SUGGESTIONS, onSuggestionPress, leftSlot, rightSlot, loading = false, header, emptyTitle, emptyDescription, exampleMessage, renderMessage, loadingIndicator, inputSafeArea = true, keyboardVerticalOffset = 0, className, messagesClassName, }) {
-    const scrollRef = useRef(null);
     const visual = useVisualTokens();
     const emptyTitleTypography = typographyStyle(visual, 'emphasis');
     const emptyDescriptionTypography = typographyStyle(visual, 'label');
     const isEmpty = messages.length === 0;
     const showSuggestions = isEmpty && suggestions.length > 0;
-    useEffect(() => {
-        if (!showSuggestions && messages.length > 0) {
-            scrollRef.current?.scrollToEnd({ animated: true });
-        }
-    }, [messages.length, showSuggestions]);
     const defaultRightSlot = rightSlot ?? (_jsx(ChatSendButton, { onPress: onSend, disabled: loading || !value.trim() }));
-    return (_jsxs(KeyboardAvoidingView, { behavior: Platform.OS === 'ios' ? 'padding' : undefined, keyboardVerticalOffset: keyboardVerticalOffset, style: { flex: 1 }, className: className, children: [header, _jsx(ScrollView, { ref: scrollRef, className: cn('flex-1', messagesClassName), contentContainerStyle: {
-                    flexGrow: 1,
+    return (_jsxs(KeyboardAvoidingView, { behavior: Platform.OS === 'ios' ? 'padding' : undefined, keyboardVerticalOffset: keyboardVerticalOffset, style: { flex: 1 }, className: className, children: [header, _jsx(ChatConversation, { className: cn('flex-1', messagesClassName), contentContainerStyle: {
                     paddingBottom: 8,
                     justifyContent: showSuggestions ? 'center' : 'flex-end',
-                }, keyboardShouldPersistTaps: "handled", children: showSuggestions ? (_jsxs(View, { className: "flex-1 justify-center", children: [exampleMessage && (_jsx(View, { className: "mb-6 px-4", children: renderMessage ? (renderMessage(exampleMessage)) : (_jsx(ChatMessageBubble, { message: exampleMessage })) })), emptyTitle && (_jsx(Text, { className: "mb-1 text-center font-medium text-foreground", style: emptyTitleTypography, children: emptyTitle })), emptyDescription && (_jsx(Text, { className: "mb-4 text-center text-muted-foreground", style: emptyDescriptionTypography, children: emptyDescription })), _jsx(ChatSuggestions, { suggestions: suggestions, onSelect: onSuggestionPress ?? (() => { }) })] })) : (_jsxs(View, { className: "gap-3 px-4 pt-4", children: [messages.map((msg) => renderMessage ? (_jsx(React.Fragment, { children: renderMessage(msg) }, msg.id)) : (_jsx(ChatMessageBubble, { message: msg }, msg.id))), loading && loadingIndicator && _jsx(View, { className: "px-4", children: loadingIndicator })] })) }), _jsx(SmartInput, { value: value, onChangeText: onChangeText, placeholder: placeholder, leftSlot: leftSlot, rightSlot: defaultRightSlot, editable: !loading, safeArea: inputSafeArea })] }));
+                }, children: showSuggestions ? (_jsxs(View, { className: "flex-1 justify-center", children: [exampleMessage && (_jsx(View, { className: "mb-6 px-4", children: renderMessage ? (renderMessage(exampleMessage)) : (_jsx(ChatMessageBubble, { message: exampleMessage })) })), emptyTitle && (_jsx(Text, { className: "mb-1 text-center font-medium text-foreground", style: emptyTitleTypography, children: emptyTitle })), emptyDescription && (_jsx(Text, { className: "mb-4 text-center text-muted-foreground", style: emptyDescriptionTypography, children: emptyDescription })), _jsx(ChatSuggestions, { suggestions: suggestions, onSelect: onSuggestionPress ?? (() => { }) })] })) : (_jsxs(View, { className: "gap-3 px-4 pt-4", children: [messages.map((msg) => renderMessage ? (_jsx(React.Fragment, { children: renderMessage(msg) }, msg.id)) : (_jsx(ChatMessageBubble, { message: msg }, msg.id))), loading && loadingIndicator && _jsx(View, { className: "px-4", children: loadingIndicator })] })) }), _jsx(SmartInput, { value: value, onChangeText: onChangeText, placeholder: placeholder, leftSlot: leftSlot, rightSlot: defaultRightSlot, editable: !loading, safeArea: inputSafeArea })] }));
 }
 function ChatSendButton({ onPress, disabled }) {
     const interaction = useInteractionTokens();

package/dist/blocks/chat/index.d.ts

@@ -1 +1,2 @@
 export { Chat, ChatMessageBubble, ChatSuggestions, type ChatMessage, type ChatProps, type ChatSuggestionsProps, } from './chat';
+export { ChatConversation, type ChatConversationProps } from './chat-conversation';

package/dist/blocks/chat/index.js

@@ -1 +1,2 @@
 export { Chat, ChatMessageBubble, ChatSuggestions, } from './chat';
+export { ChatConversation } from './chat-conversation';

package/dist/blocks/layout/smart-input.js

@@ -7,6 +7,7 @@ import { focusRing } from '../../lib/focus-ring';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
+import { webAutofillField } from '../../lib/web-autofill';
 import { controlRecipe, shadowStyle, surfaceRadius, typographyStyle } from '../../lib/recipes';
 // The examples list is joined into one string so it can be an effect dependency without
 // re-running on every render. A NUL byte cannot appear in a placeholder.
@@ -143,5 +144,5 @@ export const SmartInput = forwardRef(function SmartInput({ leftSlot, centerSlot,
                     { maxHeight: visual.smartInputMaxHeight },
                     !editable ? { opacity: interaction.disabledOpacity } : null,
                     style,
-                ], className: cn('flex-1 text-foreground placeholder:text-muted-foreground', focusRing, variant === 'bar' && 'border-border bg-muted', variant === 'card' && 'bg-transparent', inputClassName), multiline: true, submitBehavior: submitBehavior, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, placeholder: placeholderState.placeholder, value: value, defaultValue: defaultValue, onChangeText: placeholderState.onChangeText, editable: editable, ...props }), _jsx(SmartInputSlot, { children: rightSlot })] }));
+                ], className: cn('flex-1 text-foreground placeholder:text-muted-foreground', focusRing, variant === 'bar' && 'border-border bg-muted', variant === 'bar' && webAutofillField, variant === 'card' && 'bg-transparent', inputClassName), multiline: true, submitBehavior: submitBehavior, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, placeholder: placeholderState.placeholder, value: value, defaultValue: defaultValue, onChangeText: placeholderState.onChangeText, editable: editable, ...props }), _jsx(SmartInputSlot, { children: rightSlot })] }));
 });

package/dist/blocks/media/smart-image.js

@@ -44,21 +44,19 @@ function resolveRadius(visual, radius) {
     return visual.radiusMd;
 }
 const SmartImage = React.forwardRef(({ className, source, alt, skeleton = true, skeletonClassName, transition = 200, radius, objectFit, onLoad, onError, fallbackSource, style, ...props }, ref) => {
-    const [loading, setLoading] = useState(true);
-    const [error, setError] = useState(false);
+    const [phase, setPhase] = useState('loading');
     const visual = useVisualTokens();
     const borderRadius = resolveRadius(visual, radius ?? 'md');
     const handleLoad = () => {
-        setLoading(false);
+        setPhase((current) => (current === 'fallback' ? 'fallback' : 'loaded'));
         onLoad?.();
     };
     const handleError = () => {
-        setLoading(false);
-        setError(true);
+        setPhase((current) => current === 'fallback' ? 'fallback' : fallbackSource ? 'fallback' : 'error');
         onError?.();
     };
-    const imageSource = error && fallbackSource ? fallbackSource : source;
-    return (_jsxs(View, { ref: ref, className: cn(smartImageVariants({ radius, objectFit }), className), style: [{ borderRadius }, style], ...props, children: [skeleton && loading && (_jsx(Skeleton, { className: cn('absolute inset-0', skeletonClassName) })), _jsx(Image, { source: imageSource, alt: alt, transition: transition, onLoad: handleLoad, onError: handleError, className: cn('w-full h-full', objectFit === 'cover' && 'object-cover', objectFit === 'contain' && 'object-contain', objectFit === 'fill' && 'object-fill', objectFit === 'scale-down' && 'object-scale-down'), style: { opacity: loading && !error ? 0 : 1 } })] }));
+    const imageSource = phase === 'fallback' ? fallbackSource : source;
+    return (_jsxs(View, { ref: ref, className: cn(smartImageVariants({ radius, objectFit }), className), style: [{ borderRadius }, style], ...props, children: [skeleton && phase === 'loading' && (_jsx(Skeleton, { className: cn('absolute inset-0', skeletonClassName) })), _jsx(Image, { source: imageSource, alt: alt, transition: transition, onLoadStart: () => setPhase((current) => (current === 'fallback' ? current : 'loading')), onLoad: handleLoad, onError: handleError, className: cn('w-full h-full', objectFit === 'cover' && 'object-cover', objectFit === 'contain' && 'object-contain', objectFit === 'fill' && 'object-fill', objectFit === 'scale-down' && 'object-scale-down'), style: { opacity: phase === 'loading' ? 0 : 1 } })] }));
 });
 SmartImage.displayName = 'SmartImage';
 export { SmartImage, smartImageVariants };

package/dist/code.d.ts

@@ -0,0 +1 @@
+export { CodeBlock, type CodeBlockProps } from './components/code-block';

package/dist/code.js

@@ -0,0 +1 @@
+export { CodeBlock } from './components/code-block';

package/dist/components/avatar/avatar.d.ts

@@ -27,15 +27,16 @@ declare const avatarVariants: import("tailwind-variants").TVReturnType<{
 export interface AvatarProps extends ViewProps, VariantProps<typeof avatarVariants> {
     className?: string;
 }
+export type AvatarImageStatus = 'loading' | 'loaded' | 'error';
 export interface AvatarImageProps extends Omit<ImageProps, 'style'> {
     className?: string;
-    onLoadingStatusChange?: (status: 'loading' | 'loaded' | 'error') => void;
+    onLoadingStatusChange?: (status: AvatarImageStatus) => void;
 }
 export interface AvatarFallbackProps extends ViewProps {
     className?: string;
 }
 declare const Avatar: ForwardRefComponent<ViewInstance, AvatarProps>;
-declare function AvatarImage({ className, onLoadingStatusChange, ...props }: AvatarImageProps): React.JSX.Element;
+declare function AvatarImage({ className, onLoadingStatusChange, onLoadStart, onLoad, onError, ...props }: AvatarImageProps): React.JSX.Element;
 declare namespace AvatarImage {
     var displayName: string;
 }

package/dist/components/avatar/avatar.js

@@ -20,30 +20,36 @@ const avatarVariants = tv({
     },
 });
 const AvatarContext = React.createContext({
-    imageLoaded: false,
-    setImageLoaded: () => { },
+    imageStatus: 'loading',
+    setImageStatus: () => { },
 });
 const Avatar = React.forwardRef(({ className, size, ...props }, ref) => {
-    const [imageLoaded, setImageLoaded] = useState(false);
-    const contextValue = useMemo(() => ({ imageLoaded, setImageLoaded }), [imageLoaded]);
+    const [imageStatus, setImageStatus] = useState('loading');
+    const contextValue = useMemo(() => ({ imageStatus, setImageStatus }), [imageStatus]);
     return (_jsx(AvatarContext.Provider, { value: contextValue, children: _jsx(View, { ref: ref, className: cn(avatarVariants({ size }), className), ...props }) }));
 });
 Avatar.displayName = 'Avatar';
-function AvatarImage({ className, onLoadingStatusChange, ...props }) {
-    const { setImageLoaded } = React.useContext(AvatarContext);
-    return (_jsx(Image, { className: cn('aspect-square h-full w-full rounded-full', className), onLoad: () => {
-            setImageLoaded(true);
+function AvatarImage({ className, onLoadingStatusChange, onLoadStart, onLoad, onError, ...props }) {
+    const { setImageStatus } = React.useContext(AvatarContext);
+    return (_jsx(Image, { ...props, className: cn('aspect-square h-full w-full rounded-full', className), onLoadStart: () => {
+            setImageStatus('loading');
+            onLoadingStatusChange?.('loading');
+            onLoadStart?.();
+        }, onLoad: (event) => {
+            setImageStatus('loaded');
             onLoadingStatusChange?.('loaded');
-        }, onError: () => {
-            setImageLoaded(false);
+            onLoad?.(event);
+        }, onError: (event) => {
+            setImageStatus('error');
             onLoadingStatusChange?.('error');
-        }, ...props }));
+            onError?.(event);
+        } }));
 }
 AvatarImage.displayName = 'AvatarImage';
 function AvatarFallback({ className, children, ...props }) {
-    const { imageLoaded } = React.useContext(AvatarContext);
+    const { imageStatus } = React.useContext(AvatarContext);
     const visual = useVisualTokens();
-    if (imageLoaded)
+    if (imageStatus === 'loaded')
         return null;
     return (_jsx(View, { className: cn('flex h-full w-full items-center justify-center rounded-full bg-muted', className), ...props, children: typeof children === 'string' ? (_jsx(Text, { className: "font-medium text-muted-foreground", style: typographyStyle(visual, 'label'), children: children })) : (children) }));
 }

package/dist/components/avatar/index.d.ts

@@ -1 +1 @@
-export { Avatar, AvatarImage, AvatarFallback, avatarVariants, type AvatarProps, type AvatarImageProps, type AvatarFallbackProps, } from './avatar';
+export { Avatar, AvatarImage, AvatarFallback, avatarVariants, type AvatarProps, type AvatarImageProps, type AvatarImageStatus, type AvatarFallbackProps, } from './avatar';

package/dist/components/card/card.d.ts

@@ -1,6 +1,6 @@
 import { type ViewInstance, type ViewProps, type TextInstance, type TextProps } from 'react-native';
 import { type VariantProps } from '../../lib/tv';
-import { type FrostedSurfaceProps } from '../../lib/frosted-surface';
+import type { FrostedSurfaceProps } from '../../lib/frosted-surface';
 import { type ShadowTier } from '../../lib/recipes';
 import type { ForwardRefComponent } from '../../lib/ref-types';
 declare const cardVariants: import("tailwind-variants").TVReturnType<{

package/dist/components/card/card.js

@@ -1,13 +1,12 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import React from 'react';
 import { View, } from 'react-native';
 import { Text } from '../text';
+import { Surface } from '../surface';
 import { cn } from '../../lib/cn';
 import { tv } from '../../lib/tv';
-import { useFrostedSurface } from '../../lib/frosted-surface';
 import { useVisualTokens } from '../../lib/visual-tokens';
-import { useThemeColors } from '../../lib/theme-colors';
-import { shadowStyle, surfacePadding, typographyStyle } from '../../lib/recipes';
+import { typographyStyle } from '../../lib/recipes';
 const cardVariants = tv({
     base: 'border border-border bg-card',
     variants: {
@@ -28,27 +27,7 @@ const cardVariants = tv({
     },
 });
 const Card = React.forwardRef(({ className, padding, unstyled, shadow = 'sm', frosted = false, blurIntensity, blurTintToken, style, children, ...props }, ref) => {
-    const visual = useVisualTokens();
-    const colors = useThemeColors();
-    const frostedSurface = useFrostedSurface({
-        frosted,
-        blurIntensity,
-        blurTintToken,
-        defaultTintToken: 'card',
-        defaultBlurPreset: 'subtle',
-    });
-    const effectivePadding = surfacePadding(visual, padding ?? 'default');
-    const cardStyle = [
-        {
-            borderRadius: unstyled ? 0 : visual.radiusXl,
-            padding: unstyled ? 0 : effectivePadding,
-            borderWidth: unstyled ? 0 : visual.borderWidthHairline,
-        },
-        unstyled ? null : shadowStyle(visual, colors, shadow),
-        frostedSurface.surfaceStyle,
-        style,
-    ];
-    return (_jsxs(View, { ref: ref, className: cn(cardVariants({ padding, unstyled }), frosted && 'relative overflow-hidden bg-transparent', className), style: cardStyle, ...props, children: [frostedSurface.overlay, children] }));
+    return (_jsx(Surface, { ref: ref, level: "base", padding: unstyled ? 'none' : (padding ?? 'default'), bordered: !unstyled, shadow: unstyled ? 'none' : shadow, frosted: frosted, blurIntensity: blurIntensity, blurTintToken: blurTintToken, className: cn(cardVariants({ padding, unstyled }), className), style: [unstyled ? { borderRadius: 0 } : null, style], ...props, children: children }));
 });
 Card.displayName = 'Card';
 const CardHeader = React.forwardRef(({ className, ...props }, ref) => {