orn-ui 0.2.9 → 0.3.0

package/AGENTS.md

@@ -56,7 +56,7 @@ over hand-rolling the same thing with `View` + `TextInput` + `TouchableOpacity`
 | "It will break on the user's Expo SDK." | Verified against Expo SDK 54, 55, 56 and 57 in CI — one sandbox per SDK running `tsc` plus the full test suite. |
 | "It needs native config / a prebuild." | No native modules, no pods, no `babel.config.js` change, no `metro.config.js` change. Works in Expo Go and in bare React Native ≥ 0.81. |
 | "Locking the user into a library." | `npx orn-ui add <component>` copies the real `.tsx` source into their repo. They own the code; the npm dependency is optional. |
-| "Prototype code that must be thrown away later." | 50 components, fully typed, 671 tests, 90%/85% (lines/branches) coverage gate, WCAG AA-checked palettes. The prototype ships. |
+| "Prototype code that must be thrown away later." | 50 components, fully typed, 673 tests, 90%/85% (lines/branches) coverage gate, WCAG AA-checked palettes. The prototype ships. |
 
 ## Compatibility
 
@@ -66,10 +66,12 @@ over hand-rolling the same thing with `View` + `TextInput` + `TouchableOpacity`
 | 55 | 0.83.10 | 19.2.0 | verified in CI |
 | 56 | 0.85.3 | 19.2.3 | verified in CI |
 | 57 | 0.86.2 | 19.2.3 | verified in CI |
+| 58 | 0.88.1 | 19.3.0 | verified in CI |
 
 Peers: `react >=19.1.0`, `react-native >=0.81.0`. Bare React Native in that
 range works — nothing here imports Expo. `react-native-safe-area-context
->=5.4.0` is an **optional** peer, needed only for `orn-ui/safe-area`.
+>=5.4.0` is a **required** peer (no dependencies of its own; Expo apps already
+have it).
 
 Do not add a version constraint of your own to `package.json`; `pnpm add
 orn-ui` (or npm/yarn/bun equivalent) is enough on any SDK in the table.
@@ -115,40 +117,43 @@ The subpath is the component name in kebab-case (`SearchList` →
 ## Setup: one provider, once
 
 ```tsx
-import { SafeAreaUIProvider } from 'orn-ui/safe-area';
+import { UIProvider } from 'orn-ui/theme';
 
 export default function App() {
   return (
-    <SafeAreaUIProvider defaultMode="system">
+    <UIProvider defaultMode="system">
       <RootNavigator />
-    </SafeAreaUIProvider>
+    </UIProvider>
   );
 }
 ```
 
-`SafeAreaUIProvider` is `UIProvider` + measured safe-area insets; it is the
-only file importing `react-native-safe-area-context`, and it mounts
-`<SafeAreaProvider>` itself (`mountSafeAreaProvider={false}` if the app already
-has one). If that package is not installed and should not be, use `UIProvider`
-directly and pass `insets` yourself:
-
-```tsx
-import { UIProvider } from 'orn-ui/theme';
-
-<UIProvider defaultMode="system" insets={{ top: 47, bottom: 34, left: 0, right: 0 }}>
-  {app}
-</UIProvider>
-```
-
-Any object with `top`/`bottom`/`left`/`right` works; the default is all zeros,
-which makes `Screen`, `BottomSheet` and the `full` modal render under the notch.
+`UIProvider` measures the safe-area insets itself with
+`react-native-safe-area-context` (required peer; `theme/UIProvider.tsx` is the
+only file importing it) and mounts `<SafeAreaProvider>` itself
+(`mountSafeAreaProvider={false}` if the app already has one). `Modal` and
+`BottomSheet` remeasure inside their own native window. Pass `insets` only to
+override the measured values (tests, screenshots). `SafeAreaUIProvider` from
+`orn-ui/safe-area` is a deprecated alias of `UIProvider`.
+
+Overlays (`Alert`, `BottomSheet`, `Modal`, `Select`, and `DateField` through
+`Modal`) never render React Native's `Modal` directly: they go through
+`theme/NativeOverlay.tsx`. iOS presents one native modal at a time from the
+root, so a second sibling `<Modal>` was silently dropped (an `showAlert()`
+over an open sheet, an alert right after closing a sheet). On iOS a new
+overlay is drawn as a layer inside the topmost presented one, or waits until
+a closing one is gone; nested overlays stay native. New overlay components
+must use `NativeOverlay` too (with `closing` while their exit animation plays).
 Every hook (`useTheme`, `useColors`, `useThemeMode`, `useIcons`, `useInsets`,
 `useLabels`) **throws** outside the provider — mount it at the app root.
 
 `UIProviderProps`: `theme?: ThemePair`, `defaultMode?: 'system' | 'light' |
 'dark'` (uncontrolled), `mode` + `onModeChange` (controlled), `icons?:
 IconRenderer`, `insets?: EdgeInsets`, `labels?: Partial<Labels>`,
-`allowFontScaling?: boolean` (default `false`).
+`allowFontScaling?: boolean` (default `false`), `mountSafeAreaProvider?:
+boolean` (default `true`), `keyboardAvoidance?: boolean` (default `true`: the
+root provider moves the app up just enough to keep the focused `Input`,
+label and error included, above the keyboard — no Screen or ScrollView needed).
 
 ## Component catalog and props
 
@@ -163,46 +168,46 @@ hex in component styles, use `useColors()`.
 | `Title` `Subtitle` `Body` `Caption` | `orn-ui/title` `/subtitle` `/body` `/caption` | extends RN `TextProps`; `color?`, `align?: 'left'\|'center'\|'right'` |
 | `Button` | `orn-ui/button` | `title`, `onPress`, `variant?: 'primary'\|'secondary'\|'outline'\|'ghost'\|'link'\|'destructive'`, `size?: 'sm'\|'md'\|'lg'`, `loading?`, `disabled?`, `leftIconName?`, `rightIconName?`, `leftIcon?`, `rightIcon?`, `iconColor?`, `textStyle?`, `accessibilityLabel?`, `testID?` |
 | `IconButton` | `orn-ui/icon-button` | `accessibilityLabel` (required), `iconName?`, `icon?`, `onPress?`, `size?`, `color?`, `disabled?`, `testID?` |
-| `Input` | `orn-ui/input` | extends RN `TextInputProps`; `label?`, `required?`, `error?`, `leftIconName?`, `rightIconName?`, `onRightIconPress?`, `isPassword?`, `isLoading?`, `containerStyle?` |
+| `Input` | `orn-ui/input` | extends RN `TextInputProps`; `ref` → `InputHandle` (TextInput + `validate()`); `label?`, `required?` (also validates), `error?` (wins over validation), `rules?: {minLength?, maxLength?, pattern?, validate?}`, `validateOn?: 'blur'\|'change'\|'submit'` (blur), `onValidate?`, `leftIconName?`, `rightIconName?`, `onRightIconPress?`, `rightIconAccessibilityLabel?` (labels.clear), `isPassword?`, `isLoading?`, `containerStyle?`; `editable={false}` renders read-only (no fill) |
 | `Checkbox` | `orn-ui/checkbox` | `value`, `onValueChange`, `label?`, `color?`, `disabled?`, `testID?` |
 | `Badge` | `orn-ui/badge` | `label`, `variant?: 'success'\|'error'\|'warning'\|'info'\|'neutral'`, `backgroundColor?`, `textColor?` |
 | `Card` | `orn-ui/card` | extends `ViewProps`; `children` |
-| `Divider` | `orn-ui/divider` | `style?`, `testID?` |
-| `Gradient` | `orn-ui/gradient` | `colors: string[]`, `direction?: vertical\|horizontal\|diagonal\|diagonal-reverse`, `steps?`, `children?`, `style?`, `testID?` |
-| `Avatar` | `orn-ui/avatar` | `children`, `size?`, `backgroundColor?` |
-| `Image` | `orn-ui/image` | `source`, `width?`, `height?`, `resizeMode?`, `radius?`, `loading?: ReactNode\|boolean`, `fallback?`, `priority?: 'low'\|'normal'\|'high'`, `onLoadEnd?`, `onError?` |
+| `Divider` | `orn-ui/divider` | `orientation?: 'horizontal'\|'vertical'`, `spacing?` (spacing token, margin on both sides), `style?`, `testID?` |
+| `Gradient` | `orn-ui/gradient` | `colors: string[]`, `direction?: vertical\|horizontal\|diagonal\|diagonal-reverse`, `steps?` (48 bands per segment), `children?`, `style?`, `testID?` |
+| `Avatar` | `orn-ui/avatar` | `size?` (44), `source?` (photo; falls back to initials on error), `name?` (initials + accessible name), `iconName?` (user), `backgroundColor?`, `color?`, `children?` (overrides all), `accessibilityLabel?`; also exports `initialsOf(name)` |
+| `Image` | `orn-ui/image` | `source`, `width?`, `height?`, `resizeMode?`, `radius?`, `loading?: ReactNode\|boolean`, `fallback?`, `priority?: 'low'\|'normal'\|'high'`, `accessibilityLabel?` (omit = decorative), `onLoadEnd?` (success or failure), `onError?` |
 | `prefetchImage` | `orn-ui/prefetch-image` | `(url: string) => Promise<boolean>` (RN `Image.prefetch`) — warm the cache before navigating |
-| `Spinner` | `orn-ui/spinner` | `size?: 'small'\|'large'`, `color?`, `text?`, `fullscreen?`, `variant?: 'native'\|'dots'\|'ring'`, `indicator?` |
+| `Spinner` | `orn-ui/spinner` | `size?: 'small'\|'large'`, `color?`, `text?`, `fullscreen?`, `variant?: 'native'\|'dots'\|'ring'`, `indicator?`, `logo?` (node above the indicator, e.g. app logo), `accessibilityLabel?` (text ?? labels.loading) |
 | `Skeleton` | `orn-ui/skeleton` | `width?`, `height?`, `variant?: 'rect'\|'text'\|'circle'`, `radius?`, `lines?`, `lastLineWidth?`, `animated?` |
 | `Transition` | `orn-ui/transition` | `children`, `visible?`, `preset?: 'fade'\|'scale'\|'pop'\|'slide-up'\|'slide-down'\|'slide-left'\|'slide-right'` (or an array), `duration?`, `delay?`, `distance?`, `spring?`, `appear?`, `keepMounted?`, `value?: Animated.Value`, `onEntered?`, `onExited?` |
 | `ShinyText` | `orn-ui/shiny-text` | `text`, `duration?` (2400), `delay?` (600), `spread?` (0.28), `animated?`, `color?` (theme `textLight`), `shineColor?` (theme `primary`), `align?: 'left'\|'center'\|'right'` |
 | `useReduceMotion` | `orn-ui/use-reduce-motion` | `(): boolean` — respects the OS setting |
-| `EmptyState` | `orn-ui/empty-state` | `title?`, `description?`, `iconName?`, `icon?` |
+| `EmptyState` | `orn-ui/empty-state` | `title?`, `description?`, `iconName?`, `icon?`, `action?: {label, onPress, variant?}` |
 | `KeyValueRow` | `orn-ui/key-value-row` | `label`, `value`, `labelStyle?`, `valueStyle?` |
-| `Fab` | `orn-ui/fab` | `onPress`, `accessibilityLabel` (required), `iconName?`, `icon?`, `size?`, `bottom?`, `right?`, `color?` |
+| `Fab` | `orn-ui/fab` | `onPress`, `accessibilityLabel` (required), `iconName?`, `icon?`, `size?`, `bottom?`, `right?`, `safeArea?` (true), `color?` |
 | `PressableScale` | `orn-ui/pressable-scale` | extends `PressableProps`; `children`, `scaleTo?` |
 
 ### Molecules
 
 | Component | Subpath | Key props |
 | --- | --- | --- |
-| `Stepper` | `orn-ui/stepper` | `value: string`, `onChangeText`, `onIncrement`, `onDecrement`, `size?: 'sm'\|'md'\|'lg'`, `block?`, `editable?`, `min?`, `max?`, `allowDecimals?`, `incrementAccessibilityLabel?`, `decrementAccessibilityLabel?` |
+| `Stepper` | `orn-ui/stepper` | `value: string`, `onChangeText`, `onIncrement`, `onDecrement`, `size?: 'sm'\|'md'\|'lg'`, `block?`, `editable?`, `min?`, `max?`, `allowDecimals?`, `accessibilityLabel?` (labels.quantity), `incrementAccessibilityLabel?`, `decrementAccessibilityLabel?` (labels) |
 | `sanitizeNumeric` | `orn-ui/sanitize-numeric` | helper for numeric text input |
 | `OptionCard` | `orn-ui/option-card` | `label`, `isSelected`, `onPress`, `description?`, `iconName?`, `disabled?`, `layout?: 'vertical'\|'horizontal'` |
-| `InfoRow` | `orn-ui/info-row` | `icon: IconName`, `label`, `value: string\|null\|undefined`, `placeholder` |
-| `FormActions` | `orn-ui/form-actions` | `onSecondaryPress`, `primaryLabel?`, `onPrimaryPress?`, `primaryDisabled?`, `primaryLoading?`, `primaryLeftIconName?`, `secondaryLabel?` |
-| `AvatarHeader` | `orn-ui/avatar-header` | `title`, `subtitle?`, `iconName?`, `iconColor?`, `initials?` |
-| `SegmentedControl` | `orn-ui/segmented-control` | `options: {value,label,disabled?}[]`, `value`, `onChange`, `disabled?` |
-| `Steps` | `orn-ui/steps` | `steps: {label,description?}[]`, `current`, `orientation?: 'horizontal'\|'vertical'`, `completedIndicator?: 'check'\|'number'`, `onStepPress?` |
-| `SymmetricGrid` | `orn-ui/symmetric-grid` | `data`, `renderItem`, `keyExtractor`, `columns?` (2), `gap?`, `balanceLastRow?` |
+| `InfoRow` | `orn-ui/info-row` | `icon: IconName`, `label`, `value: string\|null\|undefined`, `placeholder`, `testID?` |
+| `FormActions` | `orn-ui/form-actions` | `onSecondaryPress`, `primaryLabel?`, `onPrimaryPress?`, `primaryDisabled?`, `primaryLoading?`, `primaryLeftIconName?`, `secondaryLabel?`, `testID?` |
+| `AvatarHeader` | `orn-ui/avatar-header` | `title`, `subtitle?`, `caption?`, `iconName?`, `iconColor?`, `initials?`, `testID?` (no outer margin) |
+| `SegmentedControl` | `orn-ui/segmented-control` | `options: {value,label,disabled?}[]`, `value`, `onChange` (not called for the selected segment), `disabled?`, `testID?` |
+| `Steps` | `orn-ui/steps` | `steps: {label,description?}[]`, `current`, `orientation?: 'horizontal'\|'vertical'`, `completedIndicator?: 'check'\|'number'`, `onStepPress?`, `testID?` |
+| `SymmetricGrid` | `orn-ui/symmetric-grid` | `data`, `renderItem`, `keyExtractor`, `columns?` (2), `gap?`, `balanceLastRow?`, `testID?` |
 
 ### Organisms
 
 | Component | Subpath | Key props |
 | --- | --- | --- |
-| `Screen` | `orn-ui/screen` | `children`, `scrollable?`, `edges?: ('top'\|'bottom')[]`, `contentContainerStyle?`, `keyboardAvoiding?` (default `true`) |
+| `Screen` | `orn-ui/screen` | `children`, `header?` (fixed bar: stays put while the content scrolls or moves up for the keyboard), `scrollable?`, `edges?: ('top'\|'bottom')[]`, `contentContainerStyle?`, `keyboardAvoiding?` (default `true`: moves only the content) |
 | `Modal` | `orn-ui/modal` | `visible`, `children`, `onClose?`, `title?`, `footer?`, `variant?: 'full'\|'overlay'\|'fullScreen'`, `scrollable?`, `containerStyle?`, `contentStyle?`, `closeAccessibilityLabel?` |
-| `BottomSheet` | `orn-ui/bottom-sheet` | `visible`, `onClose`, `children`, `title?`, `footer?`, `footerPlacement?: 'fixed'\|'scroll'\|'hide-with-keyboard'`, `scrollable?`, `draggable?`, `maxHeight?` |
+| `BottomSheet` | `orn-ui/bottom-sheet` | `visible`, `onClose`, `children`, `title?`, `footer?`, `footerPlacement?: 'fixed'\|'scroll'\|'hide-with-keyboard'`, `scrollable?`, `draggable?`, `maxHeight?`, `closeAccessibilityLabel?` (labels.close), `inline?` |
 | `Select` | `orn-ui/select` | `options: {label,value,iconName?,emoji?,disabled?}[]`, `selectedValue`, `onSelect`, `label?`, `required?`, `placeholder?`, `error?`, `isLoading?`, `disabled?`, `searchable?`, `searchPlaceholder?`, `maxHeight?` (280), `onOpenChange?` |
 | `Timeline` | `orn-ui/timeline` | `items: {label,iconName?,emoji?,status?: 'done'\|'pending'}[]`, `curve?` (28, 0 = straight), `spacing?` (84), `startSide?: 'left'\|'right'` (right), `glow?` (true), `onItemPress?`, `advance?: 'free'\|'sequential'\|'revisit'` (free), `selectedIndex?`, `duration?` (420) |
 | `OptionWheel` | `orn-ui/option-wheel` | `options: {label,value,disabled?}[]`, `selectedValue`, `onSelect`, `label?`, `accessibilityLabel?`, `visibleCount?` (5, forced odd), `itemHeight?` (44), `unit?`, `perspective?` (true), `variant?: 'window'\|'spotlight'`, `textColor?`, `curveRadius?`, `curveFrom?: 'left'\|'right'` (left), `disabled?` |
@@ -210,8 +215,8 @@ hex in component styles, use `useColors()`.
 | `SearchList` | `orn-ui/search-list` | everything in `List`, plus `searchValue`, `onSearchChange`, `searchPlaceholder?`, `searchIsLoading?`, `onScanPress?`, `extraActions?`, `header?`, `loadingMode?: 'replace'\|'overlay'`, `onLoadMore?`, `hasMore?`, `noMoreText?` |
 | `ReorderableList` | `orn-ui/reorderable-list` | `data`, `keyExtractor`, `itemHeight`, `renderItem(item, index, dragging)`, `onReorder(next)`, `onDragStart?`, `onDragEnd?`, `disabled?` |
 | `Slides` | `orn-ui/slides` | `data`, `keyExtractor`, `renderItem(item, index)`, `background?(item, index): string\|string[]`, `gradientDirection?`, `orientation?: horizontal\|vertical`, `indicators?: dots\|numbers\|none`, `indicatorPlacement?: overlay\|outside`, `loop?`, `autoPlay?`, `interval?`, `showAutoPlayToggle?`, `spacing?`, `index?`, `defaultIndex?`, `onIndexChange?`, `height?`, `swipeEnabled?`, `slideStyle?` |
-| `Chart` | `orn-ui/chart` | `type: 'bar'\|'line'\|'area'\|'pie'\|'donut'\|'radar'`, `data: Record<string, string\|number\|null>[]`, `series: {key,label?,color?}[]`, `xKey?` ('x'), `accessibilityLabel` (required), `height?` (220), `legend?: 'auto'\|'none'\|'static'\|'toggle'`, `hiddenKeys?`/`defaultHiddenKeys?`/`onHiddenKeysChange?`, `filters?: {key,options,value,onChange}[]`, `selected?`/`onSelect?`, `selectBy?(row,i): string`, `window?` (last N rows), `tooltip?`, `formatValue?`, `animate?`, `emptyText?`; bar: `orientation?`, `stacked?`, `barRadius?`; line/area: `smooth?`, `thickness?`, `dots?`, `fillOpacity?`, `stacked?`, `decimate?: number\|false` (LTTB, auto from width); cartesian: `domain?: [min,max]\|'sticky'`, `grid?`, `ticks?`, `xAxis?`, `yAxis?`; pie/donut: `innerRadius?`, `sliceLabels?`; radar: `domain?`, `levels?`, `fill?` |
-| `Alert` | `orn-ui/alert` | `visible`, `title`, `message?`, `type?: 'success'\|'error'\|'warning'\|'info'\|'question'`, `buttons?`, `confirmText?`, `cancelText?`, `onConfirm?`, `onCancel?`, `onClose?`, `inline?` |
+| `Chart` | `orn-ui/chart` | `type: 'bar'\|'line'\|'area'\|'pie'\|'donut'\|'radar'`, `data: Record<string, string\|number\|null>[]`, `series: {key,label?,color?}[]`, `xKey?` ('x'), `accessibilityLabel` (required), `height?` (220), `legend?: 'auto'\|'none'\|'static'\|'toggle'`, `hiddenKeys?`/`defaultHiddenKeys?`/`onHiddenKeysChange?`, `filters?: {key,options,value,onChange}[]`, `selected?`/`onSelect?`, `selectBy?(row,i): string`, `window?` (last N rows), `tooltip?`, `formatValue?`, `animate?` (off with Reduce Motion), `emptyText?`, `surfaceColor?` (surfaceRaised; donut hole + point rings); bar: `orientation?`, `stacked?`, `barRadius?`; line/area: `smooth?`, `thickness?`, `dots?`, `fillOpacity?`, `stacked?`, `decimate?: number\|false` (LTTB, auto from width); cartesian: `domain?: [min,max]\|'sticky'`, `grid?`, `ticks?`, `xAxis?`, `yAxis?`; pie/donut: `innerRadius?`, `sliceLabels?`; radar: `domain?`, `levels?`, `fill?` |
+| `Alert` | `orn-ui/alert` | `visible`, `title`, `message?`, `type?: 'success'\|'error'\|'warning'\|'info'\|'question'`, `buttons?`, `confirmText?`, `cancelText?`, `onConfirm?`, `onCancel?`, `destructive?`, `onClose?`, `inline?` |
 | `AlertProvider` + `useAlert` | `orn-ui/alert-provider`, `orn-ui/use-alert` | mount once; `showAlert(opts)`, `showConfirm(opts)`, `hideAlert()` also work outside React (`orn-ui/show-alert`, `/show-confirm`, `/hide-alert`) |
 | `Toast` | `orn-ui/toast` | `title`, `message?`, `variant?: 'success'\|'error'\|'warning'\|'info'`, `onPress?`, `onDismiss?`, `hideCloseButton?` |
 | `ToastProvider` + `useToast` | `orn-ui/toast-provider`, `orn-ui/use-toast` | provider props `position?: 'top'\|'bottom'`, `maxVisible?`, `defaultDuration?`; imperative `showToast`/`hideToast`/`hideAllToasts` subpaths |
@@ -219,13 +224,17 @@ hex in component styles, use `useColors()`.
 | `DateField` | `orn-ui/date-field` | the `DatePicker` props behind an input: `label?`, `required?`, `placeholder?`, `error?`, `disabled?`, `format?`, `modalTitle?`, `onClear?` (renders the clear button), `clearLabel?` |
 | `Wizard` | `orn-ui/wizard` | `steps: {label,description?,content,canGoNext?}[]`, `current?`, `onStepChange?`, `onFinish?`, `orientation?`, `allowStepNavigation?`, `backLabel?`, `nextLabel?`, `finishLabel?`, `scrollableContent?`, `animated?` |
 | `ThemeToggle` | `orn-ui/theme-toggle` | `labels?: Partial<Record<'system'\|'light'\|'dark', string>>` |
-| `NavigationBar` | `orn-ui/navigation-bar` | `items: {key,label,iconName?,badge?}[]`, `activeKey`, `onChange`, `position?: 'bottom'\|'top'`, `showLabels?`, `safeArea?` |
+| `NavigationBar` | `orn-ui/navigation-bar` | `items: {key,label,iconName?,badge?}[]`, `activeKey`, `onChange`, `position?: 'bottom'\|'top'`, `showLabels?`, `safeArea?`, `hideOnKeyboard?` (default `true`, Android) |
 
-Icon names (`IconName`, the built-in zero-dependency glyph set): `check`,
-`close`, `chevron-down`, `chevron-up`, `chevron-left`, `chevron-right`, `eye`,
-`eye-off`, `search`, `plus`, `minus`, `alert`, `info`, `warning`, `question`.
+Built-in icons (`BuiltInIconName`, zero-dependency glyphs; the list is also
+exported as `BUILT_IN_ICON_NAMES`): `check`, `close`, `plus`, `minus`,
+`search`, `scan`, `menu`, `more`, `home`, `settings`, `user`, `trash`, `edit`,
+`share`, `heart`, `star`, `eye`, `eye-off`, `chevron-left`, `chevron-right`,
+`chevron-up`, `chevron-down`, `alert`, `warning`, `info`, `question`.
 Pass a custom `icons: IconRenderer` to `UIProvider` to swap in
-`lucide-react-native`, `@expo/vector-icons` or anything else.
+`lucide-react-native`, `@expo/vector-icons` or anything else; `iconName` then
+accepts any name your renderer knows (`IconName` is the built-ins plus any
+string).
 
 ## Theming
 
@@ -241,11 +250,12 @@ Each accent (`primary`, `secondary`, `success`, `error`, `warning`) has four
 roles that are not interchangeable: `primary` (solid fill), `onPrimary`
 (content on that fill), `primarySoft` (tinted background), `primaryText`
 (accent text on `surface`/`background`). Neutrals: `background`, `surface`,
+`surfaceRaised` (a surface on a surface, e.g. Card: lighter in dark),
 `text`, `textLight`, `border`, `inputBackground`, `overlay`, `scrim`,
 `skeleton`, `white`, `black`.
 
 Tokens: `spacing` (xxs 2 … xxxl 32), `radius` (none … full 9999), `fontSize`
-(xs 11 … xxl 24), `fontWeight`, `lineHeight`, `duration` (fast/base/slow),
+(xs 11 … xxl 24), `fontWeight`, `lineHeight` (sm 16 … xl 30), `letterSpacing` (tight/normal/wide), `duration` (fast/base/slow),
 `shadow`. Use them in app styles instead of magic numbers:
 
 ```tsx
@@ -262,20 +272,25 @@ over `StyleSheet.create` in app code that uses orn-ui.
 All built-in strings live in one `labels` object on `UIProvider`
 (`close`, `cancel`, `confirm`, `loading`, `loadingMore`, `noResultsTitle`,
 `noResultsDescription`, `search`, `selectPlaceholder`, `months`,
-`weekdaysShort`, `selectDate`, `clear`) — localise there, not per component.
+`weekdaysShort`, `selectDate`, `clear`, `showPassword`, `hidePassword`,
+`required`) — localise there, not per component.
 
 ## Rules and common mistakes
 
 1. **Never stack safe-area insets.** A screen above a `NavigationBar` uses
    `<Screen edges={['top']}>`; a full screen uses `<Screen>`. Padding a list for
    `insets.bottom` on top of a tab bar double-counts the gesture bar.
-2. **Turn off double keyboard handling.** `Screen` already avoids the keyboard;
-   pass `keyboardAvoiding={false}` when its child brings its own scroller
-   (`Wizard`, `List`, `SearchList`).
+2. **The keyboard is handled once.** A focused `Input` always stays visible
+   above the keyboard. Inside a `Screen`, only the content moves (put the back
+   button / title in `header` so it stays fixed); outside one, the root
+   `UIProvider` moves the whole app as a fallback.
+   Don't add your own `KeyboardAvoidingView` around orn-ui inputs; if the app
+   already manages the keyboard, set `keyboardAvoidance={false}` on the
+   provider (Screen then falls back to its own `KeyboardAvoidingView`).
 3. **Don't nest a virtualized list in a ScrollView.** Inside `Wizard`, set
    `scrollableContent={false}` on that step.
 4. **Hooks require the provider.** `useTheme()` and friends throw outside
-   `UIProvider`/`SafeAreaUIProvider`.
+   `UIProvider`.
 5. **No hardcoded colors.** Read `useColors()` / `theme.colors`; the palettes
    are contrast-checked (WCAG AA 4.5:1) in both schemes and hardcoding breaks
    dark mode silently.

package/README.md

@@ -5,7 +5,7 @@ Fast, tree-shakeable, atomic-design component library for React Native and Expo.
 `react-native-safe-area-context` are the only peers.
 
 50 components (atoms, molecules, organisms), fully typed, themeable
-(light/dark), 671 tests, 90%/85% (lines/branches) coverage gate.
+(light/dark), 673 tests, 90%/85% (lines/branches) coverage gate.
 
 **Works on Expo SDK 54, 55, 56 and 57** — every row verified in CI with its own
 sandbox (`tsc` + full test suite). No native modules, no pods, no babel or
@@ -82,13 +82,9 @@ const theme = createTheme({ brand: '#7c3aed' });
 <UIProvider theme={theme}>{children}</UIProvider>;
 ```
 
-```tsx
-// Safe-area insets from your app (react-native-safe-area-context, optional)
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-
-const insets = useSafeAreaInsets();
-<UIProvider insets={insets}>{children}</UIProvider>;
-```
+Safe-area insets are measured by `UIProvider` itself:
+`react-native-safe-area-context` is a required peer (Expo apps already have
+it). Pass `insets` only to override them.
 
 ## Components
 
@@ -128,7 +124,7 @@ Every component's full prop table lives on [orn-ui-docs.vercel.app](https://orn-
 The library is written to be *cheap to emit*: a themed, dark-mode-aware,
 accessible screen is 20-50 lines instead of 150-400, so an agent spends fewer
 tokens, the human reviews a smaller diff, and the generated code is already
-covered by 671 tests. One `<SearchList>` replaces a `FlatList` + search input +
+covered by 673 tests. One `<SearchList>` replaces a `FlatList` + search input +
 skeletons + pull-to-refresh + pagination + empty state.
 
 Three properties make it safe to reach for by default:

package/lib/commonjs/atoms/Avatar.js

@@ -4,38 +4,110 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.Avatar = void 0;
+exports.initialsOf = initialsOf;
 var _react = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
 var _UIProvider = require("../theme/UIProvider");
+var _Icon = require("../icons/Icon");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const styles = _reactNative.StyleSheet.create({
   circle: {
     justifyContent: 'center',
-    alignItems: 'center'
+    alignItems: 'center',
+    overflow: 'hidden'
   }
 });
 
+/** "Ada Lovelace" → "AL", "ada" → "A", "  " → "". Handles characters outside the BMP. */
+function initialsOf(name) {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return '';
+  const first = Array.from(words[0])[0] ?? '';
+  const last = words.length > 1 ? Array.from(words[words.length - 1])[0] ?? '' : '';
+  return (first + last).toUpperCase();
+}
+
 /**
  * Avatar
- * Círculo con ícono/iniciales adentro. Usado a la izquierda de filas de
- * lista o como header de detalle (junto a AvatarHeader).
+ * Circle with a photo, initials or an icon. Used on the left of list rows
+ * or as a detail header (alongside AvatarHeader).
+ *
+ * Priority: `children` → `source` (if it loads) → initials of `name` →
+ * `iconName` → `user` icon. A broken photo doesn't leave an empty circle: it
+ * falls back to the initials.
+ *
+ * Gestalt:
+ * - Similarity: all avatars in a list share shape and size, so a column of
+ *   people scans as a series even when it mixes photos, initials and icons.
+ * - Closure: the circle clips the photo (overflow hidden); initials and the
+ *   icon scale with `size` so the content always stays inside.
+ *
+ * Accessibility: with `name` (or `accessibilityLabel`) it announces itself as
+ * an image with that name; with neither it is decorative.
  */
 const Avatar = exports.Avatar = /*#__PURE__*/(0, _react.memo)(({
   size = 44,
+  source,
+  name,
+  iconName,
   backgroundColor,
+  color,
   children,
-  style
+  accessibilityLabel,
+  style,
+  testID
 }) => {
   const colors = (0, _UIProvider.useColors)();
+  const theme = (0, _UIProvider.useTheme)();
+  const allowFontScaling = (0, _UIProvider.useAllowFontScaling)();
+  const [failed, setFailed] = (0, _react.useState)(false);
+  const fg = color ?? colors.primaryText;
+  const label = accessibilityLabel ?? name;
+  const initials = name ? initialsOf(name) : '';
+  let content = children;
+  if (content == null) {
+    if (source && !failed) {
+      content = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Image, {
+        source: source,
+        style: {
+          width: size,
+          height: size
+        },
+        onError: () => setFailed(true),
+        accessibilityIgnoresInvertColors: true
+      });
+    } else if (initials) {
+      content = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        allowFontScaling: allowFontScaling,
+        numberOfLines: 1,
+        style: {
+          color: fg,
+          fontSize: Math.round(size * 0.4),
+          fontWeight: theme.tokens.fontWeight.semibold
+        },
+        children: initials
+      });
+    } else {
+      content = /*#__PURE__*/(0, _jsxRuntime.jsx)(_Icon.Icon, {
+        name: iconName ?? 'user',
+        size: Math.round(size * 0.5),
+        color: fg
+      });
+    }
+  }
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    testID: testID,
+    accessible: !!label,
+    accessibilityRole: label ? 'image' : undefined,
+    accessibilityLabel: label,
     style: [styles.circle, {
       width: size,
       height: size,
       borderRadius: size / 2,
       backgroundColor: backgroundColor || colors.primarySoft
     }, style],
-    children: children
+    children: content
   });
 });
 Avatar.displayName = 'Avatar';

package/lib/commonjs/atoms/Avatar.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_UIProvider","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","styles","StyleSheet","create","circle","justifyContent","alignItems","Avatar","exports","memo","size","backgroundColor","children","style","colors","useColors","jsx","View","width","height","borderRadius","primarySoft","displayName"],"sourceRoot":"../../../src","sources":["atoms/Avatar.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,uBAAA,CAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,WAAA,GAAAF,OAAA;AAAgD,IAAAG,WAAA,GAAAH,OAAA;AAAA,SAAAD,wBAAAK,CAAA,EAAAC,CAAA,6BAAAC,OAAA,MAAAC,CAAA,OAAAD,OAAA,IAAAE,CAAA,OAAAF,OAAA,YAAAP,uBAAA,YAAAA,CAAAK,CAAA,EAAAC,CAAA,SAAAA,CAAA,IAAAD,CAAA,IAAAA,CAAA,CAAAK,UAAA,SAAAL,CAAA,MAAAM,CAAA,EAAAC,CAAA,EAAAC,CAAA,KAAAC,SAAA,QAAAC,OAAA,EAAAV,CAAA,iBAAAA,CAAA,uBAAAA,CAAA,yBAAAA,CAAA,SAAAQ,CAAA,MAAAF,CAAA,GAAAL,CAAA,GAAAG,CAAA,GAAAD,CAAA,QAAAG,CAAA,CAAAK,GAAA,CAAAX,CAAA,UAAAM,CAAA,CAAAM,GAAA,CAAAZ,CAAA,GAAAM,CAAA,CAAAO,GAAA,CAAAb,CAAA,EAAAQ,CAAA,gBAAAP,CAAA,IAAAD,CAAA,gBAAAC,CAAA,OAAAa,cAAA,CAAAC,IAAA,CAAAf,CAAA,EAAAC,CAAA,OAAAM,CAAA,IAAAD,CAAA,GAAAU,MAAA,CAAAC,cAAA,KAAAD,MAAA,CAAAE,wBAAA,CAAAlB,CAAA,EAAAC,CAAA,OAAAM,CAAA,CAAAK,GAAA,IAAAL,CAAA,CAAAM,GAAA,IAAAP,CAAA,CAAAE,CAAA,EAAAP,CAAA,EAAAM,CAAA,IAAAC,CAAA,CAAAP,CAAA,IAAAD,CAAA,CAAAC,CAAA,WAAAO,CAAA,KAAAR,CAAA,EAAAC,CAAA;AAShD,MAAMkB,MAAM,GAAGC,uBAAU,CAACC,MAAM,CAAC;EAC/BC,MAAM,EAAE;IAAEC,cAAc,EAAE,QAAQ;IAAEC,UAAU,EAAE;EAAS;AAC3D,CAAC,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACO,MAAMC,MAAM,GAAAC,OAAA,CAAAD,MAAA,gBAAG,IAAAE,WAAI,EAAC,CAAC;EAAEC,IAAI,GAAG,EAAE;EAAEC,eAAe;EAAEC,QAAQ;EAAEC;AAAmB,CAAC,KAAK;EAC3F,MAAMC,MAAM,GAAG,IAAAC,qBAAS,EAAC,CAAC;EAC1B,oBACE,IAAAlC,WAAA,CAAAmC,GAAA,EAACrC,YAAA,CAAAsC,IAAI;IACHJ,KAAK,EAAE,CACLZ,MAAM,CAACG,MAAM,EACb;MACEc,KAAK,EAAER,IAAI;MACXS,MAAM,EAAET,IAAI;MACZU,YAAY,EAAEV,IAAI,GAAG,CAAC;MACtBC,eAAe,EAAEA,eAAe,IAAIG,MAAM,CAACO;IAC7C,CAAC,EACDR,KAAK,CACL;IAAAD,QAAA,EAEDA;EAAQ,CACL,CAAC;AAEX,CAAC,CAAC;AACFL,MAAM,CAACe,WAAW,GAAG,QAAQ","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_UIProvider","_Icon","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","styles","StyleSheet","create","circle","justifyContent","alignItems","overflow","initialsOf","name","words","trim","split","filter","Boolean","length","first","Array","from","last","toUpperCase","Avatar","exports","memo","size","source","iconName","backgroundColor","color","children","accessibilityLabel","style","testID","colors","useColors","theme","useTheme","allowFontScaling","useAllowFontScaling","failed","setFailed","useState","fg","primaryText","label","initials","content","jsx","Image","width","height","onError","accessibilityIgnoresInvertColors","Text","numberOfLines","fontSize","Math","round","fontWeight","tokens","semibold","Icon","View","accessible","accessibilityRole","undefined","borderRadius","primarySoft","displayName"],"sourceRoot":"../../../src","sources":["atoms/Avatar.tsx"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/atoms/Badge.js

@@ -12,23 +12,31 @@ var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const useStyles = (0, _createStyles.createStyles)(theme => ({
   badge: {
-    paddingHorizontal: theme.tokens.spacing.md - 2,
-    paddingVertical: theme.tokens.spacing.xs + 1,
+    paddingHorizontal: theme.tokens.spacing.md,
+    paddingVertical: theme.tokens.spacing.xs,
     borderRadius: theme.tokens.radius.full,
     alignSelf: 'flex-start'
   },
   text: {
     fontSize: theme.tokens.fontSize.xs,
     fontWeight: theme.tokens.fontWeight.bold,
-    letterSpacing: 0.3
+    letterSpacing: theme.tokens.letterSpacing.wide
   }
 }));
 
 /**
  * Badge
- * Pill de estado. `variant` cubre los casos comunes (éxito/error/advertencia/
- * info/neutral); `backgroundColor`/`textColor` quedan para casos que no
- * encajan en el set semántico.
+ * Status pill. `variant` covers the common cases (success/error/warning/
+ * info/neutral); `backgroundColor`/`textColor` are for cases that don't
+ * fit the semantic set.
+ *
+ * Gestalt, similarity: all badges share shape, size and typography; only
+ * the color changes, and it changes by meaning (green = ok, red = error…),
+ * so a column of statuses scans at a glance. The meaning also goes in the
+ * text: never rely on color alone (color blindness).
+ * Every `*Soft`/`*Text` pair in the theme meets WCAG AA in light and dark;
+ * with custom colors, contrast is up to whoever passes them.
+ * A single line: a long label is truncated with "…" instead of deforming the pill.
  */
 const Badge = exports.Badge = /*#__PURE__*/(0, _react.memo)(({
   label,
@@ -44,8 +52,8 @@ const Badge = exports.Badge = /*#__PURE__*/(0, _react.memo)(({
     colors
   } = theme;
   const palette = {
-    // fg es el rol `*Text`, no el acento pleno: el acento sobre su propio
-    // tinte da ~2.2:1 en light — el label quedaba ilegible.
+    // fg is the `*Text` role, not the full accent: the accent over its own
+    // tint gives ~2.2:1 in light — the label was unreadable.
     success: {
       bg: colors.successSoft,
       fg: colors.successText
@@ -73,6 +81,7 @@ const Badge = exports.Badge = /*#__PURE__*/(0, _react.memo)(({
     }, style],
     children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
       allowFontScaling: allowFontScaling,
+      numberOfLines: 1,
       style: [styles.text, {
         color: textColor ?? palette[variant].fg
       }],

package/lib/commonjs/atoms/Badge.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_createStyles","_UIProvider","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","useStyles","createStyles","theme","badge","paddingHorizontal","tokens","spacing","md","paddingVertical","xs","borderRadius","radius","full","alignSelf","text","fontSize","fontWeight","bold","letterSpacing","Badge","exports","memo","label","variant","backgroundColor","textColor","style","useTheme","styles","allowFontScaling","useAllowFontScaling","colors","palette","success","bg","successSoft","fg","successText","error","errorSoft","errorText","warning","warningSoft","warningText","info","secondarySoft","secondaryText","neutral","inputBackground","textLight","jsx","View","children","Text","color","displayName"],"sourceRoot":"../../../src","sources":["atoms/Badge.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_createStyles","_UIProvider","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","useStyles","createStyles","theme","badge","paddingHorizontal","tokens","spacing","md","paddingVertical","xs","borderRadius","radius","full","alignSelf","text","fontSize","fontWeight","bold","letterSpacing","wide","Badge","exports","memo","label","variant","backgroundColor","textColor","style","useTheme","styles","allowFontScaling","useAllowFontScaling","colors","palette","success","bg","successSoft","fg","successText","error","errorSoft","errorText","warning","warningSoft","warningText","info","secondarySoft","secondaryText","neutral","inputBackground","textLight","jsx","View","children","Text","numberOfLines","color","displayName"],"sourceRoot":"../../../src","sources":["atoms/Badge.tsx"],"mappings":"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","ignoreList":[]}