@thewhileloop/whileui 3.0.0 → 4.1.0

package/README.md

@@ -18,6 +18,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.
@@ -27,16 +29,20 @@ Use `npm install` instead of `bun add` if you prefer npm.
 1. **metro.config.js** (wrap with withUniwindConfig):
 
 ```js
+const { getDefaultConfig } = require('expo/metro-config');
 const { withUniwindConfig } = require('uniwind/metro');
 
-module.exports = withUniwindConfig({
+/** @type {import('expo/metro-config').MetroConfig} */
+const config = getDefaultConfig(__dirname);
+
+module.exports = withUniwindConfig(config, {
   cssEntryFile: './global.css',
-})({
-  // your metro config
 });
 ```
 
-> `withUniwindConfig` must be the outermost wrapper. `cssEntryFile` must be a relative path string.
+> `withUniwindConfig(config, options)` takes the config first and returns the wrapped
+> config — it is not curried. It must wrap the outermost config object, and
+> `cssEntryFile` must be a relative path string.
 
 2. **global.css** at app root:
 
@@ -44,6 +50,11 @@ module.exports = withUniwindConfig({
 @import 'tailwindcss';
 @import 'uniwind';
 
+/* Required when WhileUI is installed from npm. Tailwind does not scan
+   node_modules, so without this its class names are never detected and every
+   component renders unstyled. */
+@source './node_modules/@thewhileloop/whileui/dist';
+
 /* WhileUI Noir theme - copy this or create your own */
 @layer theme {
   :root {
@@ -216,20 +227,38 @@ function MyScreen() {
 - **PortalHost:** Add `<PortalHost />` at app root for Select, Popover, Tooltip, HoverCard.
 - **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic
   durations, the responsive spring, and reduced-motion behavior.
-- **Uniwind:** `withUniwindConfig` must wrap metro config. `global.css` at app root, imported in `App.tsx`.
+- **Uniwind:** `withUniwindConfig(config, options)` wraps metro config — config first, not
+  curried. `global.css` at app root, imported in `App.tsx`. Installing from npm also needs
+  `@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
 
@@ -259,18 +288,20 @@ function MyScreen() {
 
 ### Display
 
-| Component       | Variants                                          | Notes                                                                           |
-| --------------- | ------------------------------------------------- | ------------------------------------------------------------------------------- |
-| **Card**        | padding (none, sm, default, lg), unstyled         | Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter |
-| **Badge**       | default, secondary, destructive, outline, success | BadgeText sub-component                                                         |
-| **Alert**       | default, destructive, success, warning            | AlertTitle & AlertDescription                                                   |
-| **Avatar**      | sm, default, lg                                   | AvatarImage + AvatarFallback                                                    |
-| **DataRow**     | default, compact                                  | DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value               |
-| **Separator**   | horizontal, vertical                              | Themed divider                                                                  |
-| **Progress**    | sm, default, lg                                   | Value-based progress bar with accessibility                                     |
-| **Spinner**     | sm, default, lg                                   | ActivityIndicator wrapper                                                       |
-| **Skeleton**    | pulse, shimmer                                    | Loading placeholder (pulse = opacity fade, shimmer = sweep)                     |
-| **AspectRatio** | —                                                 | Maintain aspect ratio container                                                 |
+| 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                                                   |
+| **Avatar**      | sm, default, lg                                         | AvatarImage + AvatarFallback                                                    |
+| **DataRow**     | default, compact                                        | DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value               |
+| **Separator**   | horizontal, vertical                                    | Themed divider                                                                  |
+| **Progress**    | sm, default, lg                                         | Value-based progress bar with accessibility                                     |
+| **Spinner**     | sm, default, lg                                         | ActivityIndicator wrapper                                                       |
+| **Skeleton**    | pulse, shimmer                                          | Loading placeholder (pulse = opacity fade, shimmer = sweep)                     |
+| **AspectRatio** | —                                                       | Maintain aspect ratio container                                                 |
 
 ### Layout
 
@@ -352,11 +383,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)
 
@@ -404,6 +436,7 @@ Copy from `apps/showcase/templates/profile/`:
 | **DatePickerModal**      | Bottom sheet modal with calendar, compact trigger |
 | **DatePickerInline**     | Inline calendar for forms or dashboards           |
 | **DateRangePickerModal** | Range selection modal with period marking         |
+| **TimePickerModal**      | Hour and minute wheels in the same bottom sheet   |
 
 **Tokens without a renderer.** `@thewhileloop/whileui/tokens` exports the theme
 and visual contracts, the presets, and `deriveThemeColors(base, scheme)` — give it
@@ -412,6 +445,60 @@ as the default presets. Safe in a build script (no React, RN or Uniwind
 imports); `useThemeColors()` uses it too, so a missing `--color-primary-soft`
 derives from the app's own primary instead of falling back to the default palette.
 
+**Building a product preset.** Use `createThemePreset` rather than a `ThemePreset`
+literal — it takes the 25 base colours per scheme and derives the rest:
+
+```ts
+import { createThemePreset, themePresetToCss } from '@thewhileloop/whileui/tokens';
+
+const preset = createThemePreset({
+  name: 'acme',
+  description: 'Acme brand palette.',
+  light: { background: '...', foreground: '...', primary: '...' /* 25 base keys */ },
+  dark: { background: '...', foreground: '...', primary: '...' },
+  visual: { radiusLg: 12 }, // optional, partial
+});
+
+writeFileSync('theme.generated.css', themePresetToCss(preset));
+```
+
+The literal form asks for all 52 colours per scheme, including every active variant,
+soft variant, overlay, surface, interaction state and shadow. Those are exactly what
+`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
+glyph as children and colour it from `useIconColors()`, because icon libraries need a
+concrete colour rather than a class.
+
+```tsx
+import { FAB, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
+
+<FAB label="New group" onPress={create}>
+  <Feather name="plus" size={24} color={icons.primaryForeground} />
+</FAB>;
+```
+
+| Prop        | Type                                             | Default    | Notes                                   |
+| ----------- | ------------------------------------------------ | ---------- | --------------------------------------- |
+| `label`     | `string`                                         | —          | Required. The accessible name           |
+| `variant`   | `default \| secondary \| destructive \| surface` | `default`  |                                         |
+| `size`      | `sm \| default \| lg`                            | `default`  | 48 / 56 / 64 — all clear touch minimums |
+| `placement` | `floating \| floating-left \| inline`            | `floating` | `inline` lets the caller position it    |
+
+`FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
+needs `hitSlop`.
+
 ## Layout Primitives (Stack, Row)
 
 Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
@@ -496,7 +583,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)           |
 
@@ -592,7 +679,7 @@ The WhileUI token contract is strict for cross-app reuse. Define these in **ever
 - Required core tokens: `background`, `foreground`, `card`, `card-foreground`, `popover`, `popover-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted`, `muted-foreground`, `accent`, `accent-foreground`, `destructive`, `destructive-foreground`, `border`, `input`, `ring`
 - Optional status tokens: `success`, `success-foreground`, `warning`, `warning-foreground`, `info`, `info-foreground`
 - Optional effect tokens: `overlay`, `overlay-strong`, `surface-elevated`, `surface-border`, `surface-highlight`, `surface-translucent`, `surface-translucent-border`, `state-hover`, `state-pressed`, `state-disabled`
-- Optional interaction/motion tokens: `--ui-press-opacity`, `--ui-press-opacity-strong`, `--ui-disabled-opacity`, `--ui-disabled-opacity-soft`, `--ui-disabled-opacity-subtle`, `--ui-inactive-opacity`, `--ui-motion-fast`, `--ui-motion-normal`, `--ui-motion-slow`, `--ui-motion-spring-damping`, `--ui-motion-spring-stiffness`, `--ui-motion-spring-mass`, `--ui-drawer-open-duration`, `--ui-drawer-close-duration`, `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-tint-alpha-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
+- Optional visual tokens, generated from a preset: `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-tint-alpha-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
 - Optional scale tokens: spacing (`--spacing`, `--spacing-*`), typography (`--text-*`, `--leading-*`, `--tracking-*`), radius (`--radius-*`), elevation (`--shadow-*`)
 
 Minimal contract example:
@@ -710,53 +797,25 @@ const iconColors = useIconColors();
 
 Input, Textarea, NumericInput, SmartInput, Spinner, and LoadingScreen default to theme colors when you omit `placeholderTextColor` or `spinnerColor`.
 
-### Interaction + Motion Tokens
+### Interaction and motion
 
-WhileUI components also read optional `--ui-*` tokens for deeper control of press feedback, disabled states, and motion timing:
+Press opacity, disabled opacity, motion durations, the responsive spring, and the drawer
+open and close durations are package constants on `INTERACTION_TOKENS`. They are not CSS
+variables and they do not change with a preset. Delete any `--ui-press-*`,
+`--ui-disabled-*`, `--ui-inactive-opacity`, `--ui-motion-*`, or `--ui-drawer-open-duration`
+/ `--ui-drawer-close-duration` declarations from a theme: nothing reads them.
 
-```css
-@theme {
-  --ui-press-opacity: 0.72;
-  --ui-press-opacity-strong: 0.9;
-  --ui-disabled-opacity: 0.5;
-  --ui-disabled-opacity-soft: 0.6;
-  --ui-disabled-opacity-subtle: 0.4;
-  --ui-inactive-opacity: 0.5;
-  --ui-motion-fast: 160;
-  --ui-motion-normal: 220;
-  --ui-motion-slow: 300;
-  --ui-motion-spring-damping: 20;
-  --ui-motion-spring-stiffness: 260;
-  --ui-motion-spring-mass: 0.8;
-  --ui-drawer-open-duration: 300;
-  --ui-drawer-close-duration: 220;
-  --ui-blur-intensity-subtle: 18;
-  --ui-blur-intensity-medium: 22;
-  --ui-blur-intensity-strong: 28;
-  --ui-blur-saturation-pct: 185;
-  --ui-frosted-highlight-height: 0;
-  --ui-frosted-backdrop-blur-intensity: 14;
-  --ui-frosted-backdrop-blur-scale: 0.55;
-  --ui-frosted-android-tint-alpha-scale: 1.22;
-  --ui-frosted-android-experimental-blur: 1;
-  --ui-drawer-frosted-inset: 0;
-  --ui-drawer-frosted-radius: 28;
-  --ui-drawer-content-top-padding: 0;
-}
-```
-
-For custom components, use:
+For a custom control, read that table:
 
 ```tsx
 import { useInteractionTokens, withInteractivePressableStyle } from '@thewhileloop/whileui';
 ```
 
-Wrap the application in `MotionProvider` to coordinate system reduced motion, explicit
-preview overrides, and deterministic animation-free tests. The provider is optional:
-without it `useMotionPolicy` returns the token defaults with Reanimated following the
-system setting, and `--ui-motion-*` overrides are not read. `reduced` preserves
-non-spatial feedback while asking Reanimated to skip motion; `disabled` also resolves
-semantic durations to zero.
+Wrap the application in `MotionProvider` to coordinate system reduced motion, an explicit
+preview mode, and deterministic animation-free tests. The provider is optional. Without
+it `useMotionPolicy` reports the durations and spring from `INTERACTION_TOKENS`, and
+Reanimated follows the system setting. `reduced` preserves non-spatial feedback while asking Reanimated to skip motion;
+`disabled` also resolves semantic durations to zero.
 
 ```tsx
 import { MotionProvider, useMotionPolicy } from '@thewhileloop/whileui';
@@ -966,6 +1025,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
@@ -974,12 +1044,15 @@ import { Input } from '@thewhileloop/whileui';
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
 ```
 
-| Prop                 | Type                   | Default     | Description                                              |
-| -------------------- | ---------------------- | ----------- | -------------------------------------------------------- |
-| variant              | `'default' \| 'error'` | `'default'` | Input style variant                                      |
-| placeholder          | `string`               | —           | Placeholder text                                         |
-| placeholderTextColor | `string`               | —           | Hex for placeholder; defaults to theme `mutedForeground` |
-| editable             | `boolean`              | `true`      | Whether input is editable                                |
+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 |
+| placeholder          | `string`                          | —           | Placeholder text                                                      |
+| placeholderTextColor | `string`                          | —           | Hex for placeholder; defaults to theme `mutedForeground`              |
+| editable             | `boolean`                         | `true`      | Whether input is editable                                             |
 
 ## NumericInput
 
@@ -1054,6 +1127,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
@@ -1346,6 +1443,10 @@ 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.
+
 `SelectContent` supports optional frosted props:
 
 | Prop          | Type                                                               | Default       |
@@ -1704,9 +1805,34 @@ import { SmartInput, Button, ButtonText } from '@thewhileloop/whileui';
 />;
 ```
 
-## Chat
+## ChatConversation / Chat
+
+`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>;
+```
 
-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.
+`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';
@@ -1743,7 +1869,27 @@ const [value, setValue] = useState('');
 | `inputSafeArea`          | `boolean`            | SmartInput safe-area (default `true`)             |
 | `keyboardVerticalOffset` | `number`             | For header offset when keyboard opens             |
 
-## DatePickerModal / DatePickerInline / DateRangePickerModal
+`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.
+
+## 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.
 
@@ -1753,6 +1899,8 @@ Date selection blocks using react-native-calendars. Theme-aware via `useCalendar
 
 **DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.
 
+**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.
+
 ```tsx
 import {
   DatePickerModal,
@@ -1760,6 +1908,8 @@ import {
   DatePickerInline,
   DateRangePickerModal,
   DateRangePickerTrigger,
+  TimePickerModal,
+  TimePickerTrigger,
   type DateRange,
 } from '@thewhileloop/whileui';
 
@@ -1789,6 +1939,18 @@ const [range, setRange] = useState<DateRange | null>(null);
   onOpenChange={setRangeOpen}
   trigger={<DateRangePickerTrigger value={range} placeholder="Pick range" />}
 />;
+
+// Time (modal) — "HH:MM", 24-hour, whatever the wheels show
+const [time, setTime] = useState<string | null>(null);
+
+<TimePickerModal
+  value={time}
+  onValueChange={setTime}
+  open={timeOpen}
+  onOpenChange={setTimeOpen}
+  minuteStep={5}
+  trigger={<TimePickerTrigger value={time} placeholder="Pick a time" />}
+/>;
 ```
 
 | Prop                    | Type                                                               | Description                            |
@@ -1799,6 +1961,8 @@ const [range, setRange] = useState<DateRange | null>(null);
 | `trigger`               | `ReactNode`                                                        | Custom trigger (modal variants)        |
 | `minDate` / `maxDate`   | `string`                                                           | YYYY-MM-DD bounds                      |
 | `theme`                 | `CalendarTheme`                                                    | Override calendar colors               |
+| `hourCycle`             | `'h12' \| 'h23'`                                                   | Time picker wheels; defaults to locale |
+| `minuteStep`            | `number`                                                           | Minutes between options (default 1)    |
 | `frosted`               | `boolean`                                                          | Enable frosted surface for modal panel |
 | `blurIntensity`         | `number`                                                           | Override blur amount                   |
 | `blurTintToken`         | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | Tint token for frosted panel           |

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/datepicker/index.d.ts

@@ -2,3 +2,4 @@ export { DatePickerModal, DatePickerTrigger, formatDisplayDate, type DatePickerM
 export { DatePickerInline, type DatePickerInlineProps } from './datepicker-inline';
 export { DateRangePickerModal, DateRangePickerTrigger, formatRangeDisplay, type DateRangePickerModalProps, type DateRange, } from './date-range-picker-modal';
 export { useCalendarTheme, type CalendarTheme } from './use-calendar-theme';
+export { TimePickerModal, TimePickerTrigger, formatDisplayTime, parseTime, type TimePickerModalProps, type HourCycle, } from './time-picker-modal';

package/dist/blocks/datepicker/index.js

@@ -2,3 +2,4 @@ export { DatePickerModal, DatePickerTrigger, formatDisplayDate, } from './datepi
 export { DatePickerInline } from './datepicker-inline';
 export { DateRangePickerModal, DateRangePickerTrigger, formatRangeDisplay, } from './date-range-picker-modal';
 export { useCalendarTheme } from './use-calendar-theme';
+export { TimePickerModal, TimePickerTrigger, formatDisplayTime, parseTime, } from './time-picker-modal';