@indra-inter/neobrutalism-components 0.1.0

package/README.md

@@ -0,0 +1,1330 @@
+# Neobrutalism Components
+
+A token-driven neobrutalism component library for React Native iOS and Android.
+It provides reusable foundation, form, selection, feedback, and overlay
+components with light and dark themes.
+
+> This package is currently used as a local package. The npm command below is
+> the intended installation flow after the package has been published.
+
+## Installation
+
+Install the native peer dependencies with Expo:
+
+```bash
+npx expo install react-native-safe-area-context react-native-screens react-native-svg
+```
+
+During local development, add the package from its sibling directory:
+
+```bash
+pnpm add ../neobrutalism-components-rn
+```
+
+After publishing to npm:
+
+```bash
+pnpm add neobrutalism-components
+```
+
+## NativeWind and React Native styles
+
+NativeWind v4 is a required peer dependency. Configure it in the consuming
+application, then import components from the same package entry point. Neo's
+token-driven `StyleSheet` values remain the default; `className` and the
+existing React Native style props are optional overrides that can be combined.
+The initial NativeWind-enabled components are `Radio` and `Button`; additional
+components will expose named class slots as their public styling APIs are added.
+
+```tsx
+import { Button, Radio } from 'neobrutalism-components';
+
+<Radio
+  className="min-h-14 items-center px-2 py-2"
+  label="English"
+  selected
+  style={{ opacity: 1 }}
+/>
+
+<Button
+  className="bg-sky-500"
+  containerClassName="self-end"
+  containerStyle={{ marginTop: 12 }}>
+  Continue
+</Button>
+```
+
+`className` styles the component surface. Components with a separate outer
+wrapper expose a named class slot—for example, `Button.containerClassName`
+maps to its existing `containerStyle` wrapper.
+
+## Example app
+
+The repository includes a private Expo Router example application in
+[`example/`](./example). It demonstrates the package in Chats, Calls, Discover,
+and Me screens, while the external `company-ui-test` project remains the focused
+regression consumer. The example is excluded from the npm tarball.
+
+```bash
+# repository root
+pnpm build
+pnpm --dir example install
+pnpm --dir example start
+```
+
+See [`example/README.md`](./example/README.md) for the local workflow and
+validation commands.
+
+## Setup
+
+Wrap the application once. `SafeAreaProvider` supplies insets used by toasts,
+dialogs, and bottom sheets. `DialogProvider` provides the portal host for
+dialogs, bottom sheets, selects, and menus.
+
+```tsx
+import { useState, type PropsWithChildren } from 'react';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import {
+  DialogProvider,
+  ThemeProvider,
+  ToastProvider,
+  type ThemeMode,
+} from 'neobrutalism-components';
+
+export function AppProviders({ children }: PropsWithChildren) {
+  const [mode] = useState<ThemeMode>('light');
+
+  return (
+    <SafeAreaProvider>
+      <ThemeProvider mode={mode}>
+        <DialogProvider>
+          <ToastProvider>{children}</ToastProvider>
+        </DialogProvider>
+      </ThemeProvider>
+    </SafeAreaProvider>
+  );
+}
+```
+
+## Theming
+
+`ThemeProvider` supports `light` and `dark` modes. Components react to a mode
+change automatically.
+
+```tsx
+import { useState } from 'react';
+import { Button, ThemeProvider, type ThemeMode } from 'neobrutalism-components';
+
+export function ThemeExample() {
+  const [mode, setMode] = useState<ThemeMode>('light');
+
+  return (
+    <ThemeProvider mode={mode}>
+      <Button onPress={() => setMode(mode === 'light' ? 'dark' : 'light')}>
+        Switch theme
+      </Button>
+    </ThemeProvider>
+  );
+}
+```
+
+Use `useTheme()` inside a component when custom app content needs the same
+tokens:
+
+```tsx
+import { Text, View } from 'react-native';
+import { useTheme } from 'neobrutalism-components';
+
+export function ThemedPanel() {
+  const theme = useTheme();
+
+  return (
+    <View style={{ backgroundColor: theme.colors.surface, padding: theme.spacing.md }}>
+      <Text style={{ color: theme.colors.foreground }}>Custom content</Text>
+    </View>
+  );
+}
+```
+
+`createTheme`, `theme`, `designTokens`, and `defaultDesignTokenModes` are also
+exported when an application needs to inspect theme data outside a component.
+
+### Figma token workflow
+
+Figma exports are versioned in [`tokens/figma/`](./tokens/figma). Regenerate
+the runtime TypeScript tokens and the NativeWind-compatible CSS variables after
+updating those files:
+
+```bash
+pnpm generate:design-tokens
+pnpm test:design-tokens
+```
+
+The generated CSS is published as `neobrutalism-components/tokens.css`. A
+NativeWind application can import it once, then preserve its existing semantic
+variables by aliasing them to the generated `--neo-*` variables:
+
+```css
+@import 'neobrutalism-components/tokens.css';
+
+@layer base {
+  :root,
+  .dark:root {
+    --background: var(--neo-background);
+    --primary: var(--neo-primary);
+    --color-success-100: var(--neo-success-100);
+  }
+}
+```
+
+This keeps `className` utilities such as `bg-primary` and `bg-success-100`
+working while their values follow the package's light or dark Figma mode.
+
+## Components
+
+| Group | Components |
+| --- | --- |
+| Foundation | `Button`, `IconButton`, `Badge`, `Card`, `Avatar` |
+| Form, selection, and navigation | `Input`, `TextArea`, `PasswordInput`, `UrlInput`, `PhoneInput`, `CurrencyInput`, `OtpInput`, `Checkbox`, `Radio`, `Switch`, `Calendar`, `AppBar`, `BottomNavigation`, `Tabs`, `Accordion`, `Dropdown`, `DropdownMenu`, `ListItem`, `ChatListItem`, `CallItem` |
+| Feedback | `Toast`, `ToastProvider`, `useToast`, `Progress`, `Skeleton` |
+| Overlays | `Dialog`, `ConfirmDialog`, `BottomSheet` |
+
+### Button
+
+```tsx
+import { Text } from 'react-native';
+import { Button } from 'neobrutalism-components';
+
+<Button
+  accessibilityLabel="Continue"
+  leadingIcon={<Text>←</Text>}
+  onPress={handleContinue}
+  rounded="sharp"
+  trailingIcon={<Text>→</Text>}
+  variant="primary">
+  Continue
+</Button>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `variant` | `primary`, `secondary`, `ghost`, `outline`, `destructive`, `warning`, `success`, `info`, `neutral`, or `noShadow`. |
+| `size` | `sm`, `md` (default), or `lg`. |
+| `radius` | Overrides the theme border radius. |
+| `rounded` | `rounded` (default) uses the theme radius; `sharp` sets the surface radius to `0`. An explicit `radius` takes precedence. |
+| `labelStyle` | Text-style override for the label, including a custom `fontSize`. |
+| `leadingIcon` / `trailingIcon` | React nodes rendered alongside the button label. |
+| `containerClassName` / `containerStyle` | NativeWind or React Native styles for the outer shadow container. |
+| `className` / `style` | NativeWind or React Native styles for the pressable surface. |
+
+Disabled buttons preserve their visual structure and reduce opacity. Press feedback is
+package-managed. On web, hover uses the Figma hover treatment: primary becomes
+`primaryHover`, ghost uses the accent surface, and shadowed variants extend their
+hard shadow to twice the normal offset. Native platforms do not apply hover state.
+
+### IconButton
+
+`IconButton` is a square action surface for call controls, compact toolbars, and
+other icon-first actions. The application supplies the icon and behavior.
+
+```tsx
+import { MicOff, PhoneOff } from 'lucide-react-native';
+import { IconButton } from 'neobrutalism-components';
+
+<IconButton
+  accessibilityLabel="Mute microphone"
+  icon={<MicOff size={26} />}
+  label="Mute"
+  onPress={toggleMute}
+/>
+
+<IconButton
+  accessibilityLabel="End call"
+  icon={<PhoneOff size={26} />}
+  label="End call"
+  onPress={endCall}
+  variant="destructive"
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `icon` / `accessibilityLabel` | Required visual and accessible description. |
+| `label` | Optional copy displayed below the square icon surface. |
+| `variant` | `default`, `primary`, or `destructive`. |
+| `size` | Side length of the icon surface; defaults to `60`. |
+| `rounded` / `radius` | `rounded` uses the theme radius, `sharp` uses `0`; an explicit `radius` takes precedence. |
+| `shadow` / `shadowColor` | Hard shadow is enabled by default. Disable it or override its color when needed. |
+
+### ListItem
+
+`ListItem` provides a settings or menu row; collection rendering and backend
+data mapping remain in the consuming application.
+
+```tsx
+import { useState } from 'react';
+import { Text } from 'react-native';
+import { Avatar, ListItem, Switch } from 'neobrutalism-components';
+
+const [notificationsEnabled, setNotificationsEnabled] = useState(true);
+
+<ListItem
+  description="Manage alerts and reminders"
+  leading={<Text>⚙</Text>}
+  title="Notifications"
+  trailing={
+    <Switch
+      onValueChange={setNotificationsEnabled}
+      value={notificationsEnabled}
+    />
+  }
+/>
+
+<ListItem
+  divider={false}
+  onPress={openProfile}
+  title="Profile"
+  trailingAction={{
+    accessibilityLabel: 'Edit profile',
+    icon={<Text>›</Text>},
+    onPress: openEditProfile,
+  }}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `title` / `description` | Required primary label and optional supporting label. |
+| `leading` / `leadingStyle` | Optional icon, avatar, or custom content. The slot follows its content size by default; use `leadingStyle` only for alignment or explicit constraints. |
+| `trailing` / `trailingStyle` | Optional consumer-owned content, for example a `Switch`, `Badge`, or chevron. Its slot also follows content size and can be styled independently. |
+| `gap` | Horizontal space between leading, labels, and trailing. Defaults to `theme.spacing.sm`. |
+| `trailingAction` | Optional built-in icon action with a separate accessible press target. It is not rendered when `trailing` is supplied. |
+| `onPress` / `disabled` | Makes the row pressable and controls its disabled state. |
+| `divider` | Defaults to `true`; set to `false` for the final item in a section. |
+| Style props | `className` maps to the row and `containerClassName` maps to its full-width wrapper. React Native overrides remain available through `containerStyle`, `style`, `titleStyle`, and `descriptionStyle`. |
+
+Use the same primitive for the Contact Item pattern:
+
+```tsx
+<ListItem
+  description="ID 99812645"
+  divider={false}
+  leading={<Avatar initials="AK" size="lg" />}
+  style={{ minHeight: 70, paddingVertical: 12 }}
+  title="Ariana Kim"
+/>
+```
+
+### Divider
+
+`Divider` provides a theme-aware horizontal separator for consumer-owned
+sections. It has no shadow or border of its own, and uses `theme.border.color`
+at one pixel by default.
+
+```tsx
+import { Divider } from 'neobrutalism-components';
+
+<Divider />
+<Divider inset="md" />
+<Divider thickness={2} className="opacity-60" />
+```
+
+| Key prop | Description |
+| --- | --- |
+| `inset` | Horizontal inset: `none` (default), `sm`, `md`, or `lg`. |
+| `thickness` | Divider height in pixels; defaults to `1`. |
+| `className` / `style` | Optional NativeWind and React Native style overrides. |
+
+### ChatListItem
+
+`ChatListItem` provides the chat-list layout: contact content, a timestamp,
+message preview, and an unread counter. Data mapping, navigation, avatar choice,
+and selection state stay in the app.
+
+```tsx
+import { Avatar, ChatListItem } from 'neobrutalism-components';
+
+<ChatListItem
+  leading={<Avatar initials="AK" size="md" />}
+  message="See you shortly"
+  messageNumberOfLines={2}
+  onLongPress={startConversationSelection}
+  onPress={openConversation}
+  state="unread"
+  timestamp="10:11"
+  title="Ariana Kim"
+  unreadBadgeProps={{ radius: 8, shadowColor: '#01ABFF' }}
+  unreadCount={2}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `state` | `default`, `unread`, or `request`; `unread` displays `unreadCount`. |
+| `selectable` / `selected` / `onSelectionChange` | Opt into the Figma selection checkbox while keeping selected state controlled by the application. |
+| `leading` / `leadingStyle` | Optional avatar or custom 40px leading content, with a style override. |
+| `title`, `message`, `timestamp` | Required consumer-owned chat content. |
+| `titleNumberOfLines`, `messageNumberOfLines`, `timestampNumberOfLines` | Per-field truncation limits. The default title limit is `1` (`2` for `request`), while message and timestamp default to `1`. |
+| `unreadBadgeProps` | Optional `Badge` props for the unread counter, such as `radius`, `rounded`, `shadow`, and `shadowColor`. |
+| `divider`, `onPress`, `onLongPress`, `disabled` | Row behavior and section composition. `onLongPress` is useful for consumer-owned multiselect flows. |
+
+### CallItem
+
+`CallItem` is a call-history row. It controls only the status color; the app
+provides its avatar, phone/video icon, copy, and interaction.
+
+```tsx
+import { Phone } from 'lucide-react-native';
+import { Avatar, CallItem } from 'neobrutalism-components';
+
+<CallItem
+  detail="Incoming · 5:23"
+  leading={<Avatar initials="AK" size="lg" />}
+  onPress={openCallDetails}
+  title="Ariana Kim"
+  trailing={<Phone size={24} />}
+  type="incoming"
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `type` | `incoming`, `outgoing`, `missed`, or `video`; controls the detail color. |
+| `leading` / `leadingStyle` | Optional avatar or custom 48px leading content. |
+| `trailing` | Optional phone, video, or other consumer-owned trailing content. |
+| `title` / `detail` | Required call copy supplied by the application. |
+
+### Badge
+
+```tsx
+import { Badge } from 'neobrutalism-components';
+
+<Badge size="md" type="success">Published</Badge>
+
+<Badge className="min-h-8 px-2" shadow={false} size="md" type="primary">
+  Category
+</Badge>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `type` | `default`, `primary`, `info`, `error`, `warning`, or `success`. |
+| `size` | `sm` or `md`. |
+| `radius` / `rounded` | `radius` has priority; otherwise `rounded` is `rounded` (default) or `sharp`. |
+| `shadow` / `shadowColor` | Show or hide the hard shadow, and optionally override its color. |
+| `className` | NativeWind classes mapped to the Badge visual style surface. |
+| `leadingIcon` | Optional icon before the badge label. |
+
+### Progress
+
+`Progress` represents a determinate value supplied by the consuming
+application or backend.
+
+```tsx
+import { Progress } from 'neobrutalism-components';
+
+<Progress value={75} />
+
+<Progress type="circular" value={75} />
+
+<Progress
+  accessibilityLabel="Upload progress"
+  max={240}
+  value={160}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `value` / `max` | Required determinate value and optional maximum (`100` by default). Values are clamped to the valid range. |
+| `type` | `bar` (default) or `circular`. |
+| `showLabel` | Defaults to `false` for bars and `true` for circular indicators. |
+| `size` / `barHeight` | Circular diameter (default `80`) or bar height (default `15`). |
+| `containerStyle` / `style` | Styles for the shadow wrapper or visible track/surface. Use `containerStyle={{ width: 240 }}` to constrain a bar. |
+| `trackStyle` / `indicatorStyle` / `labelStyle` | Style slots for the track, bar fill, and circular label. `indicatorStyle` applies to bars; circular arcs stay theme-driven. |
+
+The component is determinate only. The circular arc is drawn dynamically using
+`react-native-svg`, so it reflects any normalized value rather than a static
+75% asset.
+
+### Skeleton
+
+`Skeleton` provides Figma-matched loading placeholders for chat content, lists,
+and text blocks. It uses a lightweight native opacity pulse and requires no
+additional animation or gradient dependency.
+
+```tsx
+import { Skeleton } from 'neobrutalism-components';
+
+<Skeleton type="chat" />
+
+<Skeleton rounded="rounded" type="list" />
+
+<Skeleton animated={false} shadow={false} type="textBlock" />
+```
+
+| Key prop | Description |
+| --- | --- |
+| `type` | `textBlock` (default), `list`, or `chat`. Each renders the corresponding Figma placeholder layout. |
+| `rounded` / `radius` | `sharp` is the default; `rounded` uses the theme radius. An explicit `radius` takes precedence. |
+| `shadow` / `shadowColor` / `shadowOffset` | Hard shadow is on by default. Override its color or right-and-bottom offset as needed. |
+| `animated` / `animationDuration` | Enables the native opacity pulse by default. Set `animated={false}` for static loading states. |
+| `style` | Styles the outer preset container, such as its width or placement. |
+
+The Figma placeholder uses a gradient. This implementation intentionally uses a
+theme-driven pulse instead, so consumers do not need an extra native gradient
+dependency.
+
+### Calendar
+
+`Calendar` is an inline, theme-aware calendar for single dates and date
+ranges. Every public value is an ISO calendar date (`YYYY-MM-DD`); it does not
+exchange JavaScript `Date` objects with the consuming application.
+
+```tsx
+import { useState } from 'react';
+import { Calendar, type CalendarRangeValue } from 'neobrutalism-components';
+
+const [date, setDate] = useState<string | undefined>('2026-08-31');
+const [range, setRange] = useState<CalendarRangeValue | undefined>({
+  startDate: '2026-08-04',
+  endDate: '2026-08-07',
+});
+
+<Calendar
+  disabledDates={['2026-09-01']}
+  onValueChange={setDate}
+  value={date}
+/>
+
+<Calendar
+  mode="range"
+  onValueChange={setRange}
+  value={range}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `mode` | `single` (default) or `range`. In range mode, the first press selects a start date and the second selects its end. |
+| `value` / `defaultValue` | Controlled or uncontrolled ISO date value. Use `CalendarRangeValue` (`{ startDate, endDate? }`) for `range` mode. |
+| `minDate` / `maxDate` / `disabledDates` | ISO date bounds and explicitly unavailable dates; blocked dates cannot be selected. |
+| `defaultVisibleMonth` / `onVisibleMonthChange` | Set the initial visible month and observe month navigation using `YYYY-MM-01`. |
+| `firstDayOfWeek` / `locale` | Start the week on Sunday (`0`, default) or Monday (`1`), and format the header/week labels for a locale. |
+| `radius` | A number or `{ topLeft, topRight, bottomRight, bottomLeft }`. Defaults to the theme base radius and is applied to both the calendar surface and its hard shadow. |
+| `selectedRadius` | Radius for a selected single date or selected range days. Defaults to the theme base radius. |
+| `navigationButtonRadius` | Radius for previous/next month buttons and their hard shadows. Defaults to the theme base radius. |
+| `containerStyle` / `style` | Style the shadow wrapper or visible 300px calendar surface. |
+
+In range mode, the start and end dates use the secondary/black treatment, while
+the dates between them use the primary blue treatment. Disabled and outside
+month dates use the muted surface.
+
+### Accordion
+
+`Accordion` manages which sections are expanded. Item content remains owned by
+the consuming application.
+
+```tsx
+import { Text } from 'react-native';
+import { Accordion } from 'neobrutalism-components';
+
+<Accordion
+  defaultValue="overview"
+  items={[
+    {
+      content: <Text>Content supplied by the app.</Text>,
+      title: 'Product overview',
+      value: 'overview',
+    },
+    {
+      content: <Text>Feature details supplied by the app.</Text>,
+      title: 'Key features',
+      value: 'features',
+    },
+  ]}
+  shadowVariant="primary"
+/>
+```
+
+Use `type="multiple"` when several sections may remain open:
+
+```tsx
+<Accordion
+  defaultValue={['overview', 'features']}
+  items={items}
+  onValueChange={setExpandedValues}
+  type="multiple"
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `items` | `AccordionItem[]` with `value`, `title`, `content`, and optional `disabled`, `leading`, and `trailing`. |
+| `type` | `single` (default) opens one section, or `multiple` keeps any number open. |
+| `value` / `defaultValue` / `onValueChange` | Controlled or uncontrolled expanded state. Single mode uses a string or `null`; multiple mode uses a string array. |
+| `collapsible` | Defaults to `true`; set `false` to keep the expanded item open in single mode. |
+| `shadowVariant` | `default`, `primary`, `secondary`, `destructive`, `warning`, `success`, or `info`; it applies to expanded sections only. |
+| `shadowColor` | Direct hard-shadow override; takes precedence over `shadowVariant`. |
+| Style props | `containerStyle`, `style`, `headerStyle`, `contentStyle`, and `titleStyle`. |
+
+Expanded headers use the current theme's `primaryHover` color. The chevron,
+border, hard shadow, and disabled state are package-managed.
+
+### Input
+
+```tsx
+import { useState } from 'react';
+import { Text } from 'react-native';
+import { Input } from 'neobrutalism-components';
+
+const [email, setEmail] = useState('');
+
+<Input
+  error={email.length === 0 ? 'Email is required.' : undefined}
+  helperText="We will only use this for account updates."
+  label="Email"
+  leadingIcon={<Text>@</Text>}
+  onChangeText={setEmail}
+  placeholder="you@company.com"
+  trailingIcon={<Text>✓</Text>}
+  value={email}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `label` | Text shown above the field. |
+| `helperText` | Supporting copy shown below the field when no error is present. |
+| `variant` | `default` (shadowed), `filled` (solid and shadowless), or `dashed` (editable dashed and shadowless). |
+| `error` | Error message; it uses a destructive solid border without a shadow. |
+| `readOnly` | Shows a non-editable, read-only field. |
+| `editable={false}` | Shows a disabled dashed field without a shadow. |
+| `leadingIcon` / `trailingIcon` | React nodes placed inside the field. |
+| `leadingAddon` / `trailingAddon` | Full-height field segments; use them for protocol, currency, or other labeled addons. Their `*Style` counterparts style the segment. |
+| `fieldStyle` | Style slot for the visible input field, for example a custom height or radius. |
+| `changeShadowOnFocus` | **iOS only.** Defaults to `false`, so focus changes only the border. Set to `true` to use the primary color for the hard shadow while focused. Android always keeps the hard shadow static to prevent native focus loss. |
+| Text input props | Native `TextInputProps`, including `value`, `defaultValue`, `editable`, and `onChangeText`. |
+
+### TextArea
+
+`TextArea` uses the same validation, label, helper, icon, read-only, disabled,
+and style props as `Input`, but renders a native multiline editor. It is 80px
+high by default and aligns text at the top.
+
+```tsx
+import { useState } from 'react';
+import { TextArea } from 'neobrutalism-components';
+
+export function BioField() {
+  const [bio, setBio] = useState('');
+
+  return (
+    <TextArea
+      helperText="Visible on your public profile."
+      height={120}
+      label="About you"
+      onChangeText={setBio}
+      placeholder="Tell us about yourself"
+      value={bio}
+    />
+  );
+}
+```
+
+| Key prop | Description |
+| --- | --- |
+| `height` | Visible field height; defaults to `80`. |
+| `numberOfLines` | Native multiline line count; defaults to `3`. |
+| `fieldStyle` / `style` | Style slots for the field surface and native text editor. |
+
+Native text areas do not implement the web-only drag resize handle shown in
+some Figma previews. Use `height` or `fieldStyle` to select the appropriate
+fixed height for the screen.
+
+### PasswordInput
+
+`PasswordInput` is an `Input` with a Figma-matched trailing `Show` / `Hide`
+surface. Visibility can be controlled by the app or managed internally.
+
+```tsx
+import { useState } from 'react';
+import { PasswordInput } from 'neobrutalism-components';
+
+const [password, setPassword] = useState('');
+
+<PasswordInput
+  helperText="Use the Show button to reveal the value."
+  label="Password"
+  onChangeText={setPassword}
+  onVisibilityChange={(visible) => analytics.track('password_visibility', { visible })}
+  value={password}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `visible` / `defaultVisible` | Controlled or uncontrolled visibility state; the password is masked by default. |
+| `onVisibilityChange` | Called with the next visibility state after tapping Show or Hide. |
+| `showLabel` / `hideLabel` | Labels for the built-in trailing visibility control. Defaults to `Show` and `Hide`. |
+| `showVisibilityToggle` | Set `false` to omit the built-in control. |
+| `trailingIcon` | Replaces the built-in Show/Hide control with custom content. |
+
+### UrlInput
+
+`UrlInput` supplies native URL typing defaults and can show a static protocol
+segment without requiring the consuming app to compose it manually.
+
+```tsx
+import { UrlInput } from 'neobrutalism-components';
+
+<UrlInput
+  label="Website"
+  onChangeText={setWebsite}
+  protocol="https://"
+  value={website}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `protocol` | Protocol label; defaults to `https://`. |
+| `showProtocol` | Set `false` to render a plain URL input. |
+| `leadingAddon` | Replaces the default protocol content. |
+| Native defaults | `keyboardType="url"`, `autoCapitalize="none"`, `autoCorrect={false}`, and `autoComplete="url"`. |
+
+### PhoneInput
+
+`PhoneInput` provides a country-code segment and phone-native text input
+defaults. The app owns country selection and phone-number validation.
+
+```tsx
+import { PhoneInput } from 'neobrutalism-components';
+
+<PhoneInput
+  country={{ dialCode: '+62', isoCode: 'ID' }}
+  label="Phone"
+  onChangeText={setPhone}
+  onCountryPress={openCountryPicker}
+  value={phone}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `country` | `{ isoCode, dialCode }`; defaults to `{ isoCode: 'US', dialCode: '+1' }`. |
+| `onCountryPress` | Makes the country segment interactive; use it to open a picker, dialog, or bottom sheet in the app. |
+| `countryAccessibilityLabel` | Accessible label for the country selection control. |
+| Native defaults | `keyboardType="phone-pad"`, `autoComplete="tel"`, and `textContentType="telephoneNumber"`. |
+
+### CurrencyInput
+
+`CurrencyInput` is a right-aligned numeric field with Figma-matched currency
+segments. Values are intentionally unformatted so the consuming app can apply
+its own locale, decimal, and submission rules.
+
+```tsx
+import { CurrencyInput } from 'neobrutalism-components';
+
+<CurrencyInput
+  currencyCode="IDR"
+  label="Amount"
+  onChangeText={setAmount}
+  symbol="Rp"
+  value={amount}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `symbol` | Leading currency symbol; defaults to `$`. |
+| `currencyCode` | Trailing code; defaults to `USD`. |
+| `showSymbol` / `showCurrencyCode` | Set either to `false` to omit its segment. |
+| Native defaults | `keyboardType="decimal-pad"`, placeholder `0.00`, and right-aligned value text. |
+
+### OtpInput
+
+`OtpInput` renders a six-cell, masked verification code field by default. It
+uses `react-native-confirmation-code-field` internally, preserving SMS-code
+paste behavior on iOS and Android.
+
+```tsx
+import { useState } from 'react';
+import { OtpInput } from 'neobrutalism-components';
+
+const [code, setCode] = useState('');
+
+<OtpInput
+  label="Verification code"
+  onChangeText={setCode}
+  onComplete={verifyCode}
+  value={code}
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `value` / `defaultValue` / `onChangeText` | Controlled or uncontrolled OTP state. |
+| `cellCount` | Number of cells; defaults to `6`. |
+| `onComplete` | Called once the code fills every cell. |
+| `mask` / `maskSymbol` | Masking is enabled by default and uses `•`; set `mask={false}` to show entered characters. |
+| `error` / `helperText` / `label` | Input copy and validation state. Error cells use the destructive border. |
+| `cellStyle` / `containerStyle` / `labelStyle` | Style slots for individual cells, the component container, and label. |
+| `changeShadowOnFocus` | **iOS only.** Defaults to `false`, so focus changes only the active-cell border. Set to `true` to use the primary color for the focused cell shadow. Android keeps cell shadows static to preserve native input focus. |
+| Native defaults | `keyboardType="number-pad"`, `textContentType="oneTimeCode"`, and platform SMS OTP autocomplete. |
+
+### Card
+
+`Card` is a layout container. Its content belongs to the consuming app.
+
+```tsx
+import { Text } from 'react-native';
+import {
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from 'neobrutalism-components';
+
+<Card
+  backgroundColor="#FFFFFF"
+  radius={{ topLeft: 16, topRight: 16, bottomLeft: 0, bottomRight: 0 }}
+  shadowVariant="primary">
+  <CardHeader>
+    <CardTitle>Project update</CardTitle>
+    <CardAction><Text>New</Text></CardAction>
+  </CardHeader>
+  <CardContent>
+    <CardDescription>Content is supplied by the application.</CardDescription>
+  </CardContent>
+  <CardFooter>
+    <Button variant="outline">View details</Button>
+  </CardFooter>
+</Card>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `backgroundColor` | Overrides the theme surface color. |
+| `radius` | A number or corner object with `topLeft`, `topRight`, `bottomRight`, and `bottomLeft`. |
+| `shadowVariant` | `default`, `primary`, `secondary`, `destructive`, `warning`, `success`, or `info`. |
+| `shadowColor` | Direct hard-shadow override; takes precedence over `shadowVariant`. |
+| `contentStyle` | Overrides the default content layout, for example `{{ padding: 0 }}` for full-bleed list rows. |
+| `containerStyle` / `style` | Styles for the shadow wrapper or card surface. |
+| `containerClassName` / `className` / `contentClassName` | NativeWind equivalents for `containerStyle`, `style`, and `contentStyle`; `contentClassName` is applied last. |
+
+### Avatar
+
+```tsx
+import { Avatar } from 'neobrutalism-components';
+
+<Avatar initials="AK" size="md" />
+<Avatar size="lg" source={{ uri: profileUri }} variant="image" />
+<Avatar showAdd size="lg" variant="icon" />
+```
+
+| Key prop | Description |
+| --- | --- |
+| `variant` | `initial` (default), `icon`, or `image`. |
+| `size` | `xs`, `sm`, `md`, `lg`, or `xl`. |
+| `initials` | Fallback copy for the `initial` variant. |
+| `source` | Native `ImageSourcePropType` for the `image` variant. |
+| `showAdd` | Shows the add indicator for `md`, `lg`, and `xl` avatars. |
+| `rounded` | `rounded` (default) uses the theme radius; `sharp` makes the avatar square. |
+| `shadow` / `shadowColor` | Show or hide the hard shadow, and optionally override its color. |
+
+### AppBar
+
+`AppBar` supplies the screen-header surface; navigation and every interactive
+slot remain owned by the consuming application. Keep the application wrapped
+with `SafeAreaProvider` as shown in [Setup](#setup).
+
+```tsx
+import { Text } from 'react-native';
+import { AppBar, Avatar, Checkbox, Tabs } from 'neobrutalism-components';
+
+<AppBar>
+  <AppBar.Content
+    avatar={<Avatar initials="SJ" size="sm" />}
+    leading={<Text onPress={goBack}>←</Text>}
+    subtitle="Online now"
+    title="Sarah Jenkins"
+    trailing={<Text onPress={openActions}>⋮</Text>}
+  />
+  <AppBar.Bottom>
+    <Tabs items={conversationTabs} />
+  </AppBar.Bottom>
+</AppBar>
+```
+
+Set `safeArea={false}` only when the parent already applies the top safe-area
+inset or when the bar intentionally overlays screen content. Use
+`safeAreaOffset` when a specific screen needs to fine-tune the safe-area gap;
+negative values are clamped at zero:
+
+```tsx
+<AppBar backgroundColor="#25A9EB" safeArea={false}>
+  <AppBar.Content title="Select items" trailing={<Text>2 selected</Text>} />
+</AppBar>
+```
+
+Use `variant="select"` for a bulk-selection header. The selection count stays in
+the flexible title slot, while the select-all control stays pinned to the right:
+
+```tsx
+<AppBar>
+  <AppBar.Content
+    leading={<Text onPress={exitSelection}>←</Text>}
+    title={`${selectedIds.size} selected`}
+    trailing={
+      <Checkbox
+        checked={selectedIds.size === items.length}
+        label="Select all"
+        labelPosition="left"
+        onValueChange={setAllSelected}
+        style={{ width: 106 }}
+      />
+    }
+    variant="select"
+  />
+</AppBar>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `safeArea` | Defaults to `true`; applies the top device inset through `SafeAreaProvider`. |
+| `safeAreaOffset` | Adds to the top inset when `safeArea` is enabled. Defaults to `0`; the final inset never becomes negative. |
+| `backgroundColor` | Overrides the default primary app-bar surface. |
+| `variant` | `default` (default) or `select`. `select` matches the compact bottom padding of Figma's selection header. |
+| `leading` / `avatar` / `trailing` | Consumer-owned React-node slots in `AppBar.Content`. Supply accessible pressable controls for actions. |
+| `title` / `subtitle` | String or number values receive theme text styling and truncate safely to one line; custom React nodes remain unchanged. |
+| `AppBar.Bottom` | Optional full-width, application-owned content such as `Tabs`, a selection toolbar, or a balance summary. It replaces the root AppBar's bottom border; padding, dividers, and its inner layout remain consumer-owned. It is not a bottom-tab navigator. |
+| Style props | `containerStyle` and `style` on `AppBar`; `containerStyle`, `titleStyle`, and `subtitleStyle` on `AppBar.Content`; `style` on `AppBar.Bottom`. |
+
+### Checkbox, Radio, and Switch
+
+These controls are controlled by their value props and callbacks.
+
+```tsx
+import { useState } from 'react';
+import { Checkbox, Radio, Switch } from 'neobrutalism-components';
+
+const [accepted, setAccepted] = useState(false);
+const [plan, setPlan] = useState<'standard' | 'express'>('standard');
+const [notifications, setNotifications] = useState(false);
+
+<Checkbox
+  checked={accepted}
+  description="Required before continuing."
+  label="Accept terms"
+  onValueChange={setAccepted}
+/>
+
+<Radio
+  label="Standard delivery"
+  onPress={() => setPlan('standard')}
+  selected={plan === 'standard'}
+/>
+
+<Switch
+  label="Notifications"
+  onValueChange={setNotifications}
+  value={notifications}
+/>
+```
+
+| Component | Key props |
+| --- | --- |
+| `Checkbox` | `checked`, `onValueChange`, `indeterminate`, `error`, `radius`, `label`, `description`, `labelPosition`, `disabled`. |
+| `Radio` | `selected`, native `onPress`, `label`, `description`, `labelPosition`, `disabled`, `className`, `style`. |
+| `Switch` | `value`, `onValueChange`, `label`, `description`, `labelPosition`, `disabled`. |
+
+`labelPosition` is `right` by default and also accepts `left`.
+
+### Tabs
+
+`Tabs` is a value selector; it does not render a tab panel. Keep the selected
+screen content in the consuming application.
+
+```tsx
+import { useState } from 'react';
+import { Text } from 'react-native';
+import { Badge, Tabs, type TabItem } from 'neobrutalism-components';
+
+const items: readonly TabItem[] = [
+  { label: 'Overview', value: 'overview' },
+  {
+    label: 'Activity',
+    leading: <Text>•</Text>,
+    trailing: <Badge size="sm">3</Badge>,
+    value: 'activity',
+  },
+  { disabled: true, label: 'Settings', value: 'settings' },
+];
+
+export function ProfileTabs() {
+  const [tab, setTab] = useState('overview');
+
+  return (
+    <>
+      <Tabs
+        border="bottom"
+        contentContainerStyle={{ gap: 8, paddingHorizontal: 12 }}
+        items={items}
+        onValueChange={setTab}
+        style={{ borderBottomWidth: 3 }}
+        value={tab}
+        variant="primary"
+      />
+      {tab === 'overview' && <Overview />}
+      {tab === 'activity' && <Activity />}
+    </>
+  );
+}
+```
+
+| Key prop | Description |
+| --- | --- |
+| `items` | `TabItem[]` with `value`, `label`, optional `disabled`, `leading`, and `trailing`. |
+| `value` / `onValueChange` | Controlled selected value and callback. |
+| `defaultValue` | Initial value for uncontrolled usage. Without a default, the first enabled item is selected. |
+| `layout` | `scroll` (default) for a horizontally scrollable row, or `equal` for a small fixed set of equal-width tabs. |
+| `variant` | Selected-item appearance: `primary` (default), `secondary`, `destructive`, `warning`, `success`, `info`, or `neutral`. |
+| `border` | Outer rail border: `all` (default), `bottom`, or `none`. Use `style` to override its native border width or color. |
+| `rounded` | Outer rail shape: `sharp`, `rounded` (default), or `pill`. This does not change tab-item shape. |
+| `itemRounded` | `sharp` (default, matching Figma), `rounded`, or `pill`; sets the shape of every tab trigger independently from `rounded`. |
+| `itemRadius` | Direct tab-trigger radius override. It takes precedence over `itemRounded`. |
+| `shadow` | Renders the Neo hard shadow for the outer rail. Defaults to `false`. |
+| Style slots | `containerStyle` for the shadow wrapper, `style` for the rail, `contentContainerStyle` for list padding and gap, `itemStyle` and `selectedItemStyle` for triggers, plus `labelStyle` and `selectedLabelStyle` for labels. |
+| `accessibilityLabel` | Accessible label for the tab list; defaults to `Tabs`. |
+
+Each trigger exposes the native `tab` role with selected and disabled state.
+
+### BottomNavigation
+
+`BottomNavigation` renders the visual bottom-navigation surface only. It does
+not know about Expo Router or any other navigation library: keep route state
+and navigation calls in the consuming application.
+
+```tsx
+import { useState } from 'react';
+import { Text } from 'react-native';
+import { BottomNavigation } from 'neobrutalism-components';
+
+export function AppNavigation() {
+  const [tab, setTab] = useState('chats');
+
+  return (
+    <BottomNavigation
+      items={[
+        {
+          activeIcon: <Text style={{ color: '#01ABFF' }}>●</Text>,
+          icon: <Text>○</Text>,
+          label: 'Chats',
+          value: 'chats',
+        },
+        { icon: <Text>○</Text>, label: 'Calls', value: 'calls' },
+      ]}
+      onValueChange={setTab}
+      radius={12}
+      shadowVariant="primary"
+      value={tab}
+    />
+  );
+}
+```
+
+| Key prop | Description |
+| --- | --- |
+| `items` | A non-empty list of `{ value, label, icon, activeIcon?, disabled?, accessibilityLabel? }`. `activeIcon` is rendered for the selected item when supplied. |
+| `value` / `onValueChange` | Controlled selected value and callback. Call the app router from `onValueChange` when a tab represents a route. |
+| `safeArea` | Defaults to `true` and adds the bottom device inset. Pass `false` only when a parent navigator already owns that inset or for an inline preview. |
+| `radius` | Radius of the bordered navigation surface and hard shadow. Defaults to the theme border radius. |
+| `indicatorRadius` | Radius for the selected tab's bottom indicator. Defaults to `0` for the square Figma treatment. |
+| `shadow` | Enables the hard shadow; defaults to `true`. Use `false` for a flat navigation surface. |
+| `shadowVariant` | `default`, `primary`, `secondary`, `destructive`, `warning`, `success`, or `info`. It defaults to `primary` to match the Figma navigation shadow. |
+| `shadowColor` | Direct hard-shadow override. It takes precedence over `shadowVariant`. |
+| `containerStyle` / `style` / `contentStyle` | Style the outer wrapper, safe-area surface, or bordered navigation row. |
+
+Each item exposes the native `tab` role with selected and disabled state. Use
+`BottomNavigation` as a custom tab-bar view in the main project rather than
+rendering it alongside another navigator's own tab bar.
+
+### Dropdown
+
+Use `Dropdown` for value selection. `single` is the default; use
+`searchable` for local filtering and `multi-select` for checkbox selection.
+
+```tsx
+import { useState } from 'react';
+import { Dropdown } from 'neobrutalism-components';
+
+const [team, setTeam] = useState<string>();
+
+<Dropdown
+  onValueChange={setTeam}
+  options={[
+    { label: 'Design', value: 'design' },
+    { label: 'Engineering', value: 'engineering' },
+    { disabled: true, label: 'Sales (Full)', value: 'sales' },
+  ]}
+  placeholder="Select a team"
+  type="single"
+  value={team}
+/>
+```
+
+`Dropdown` can also normalize data returned from an API. Keep backend models in
+the application and provide mapper callbacks instead of reshaping every
+response into UI data first.
+
+```tsx
+import { Avatar, Dropdown } from 'neobrutalism-components';
+
+type Team = {
+  avatarUri?: string;
+  department?: { name: string };
+  id: string;
+  initials: string;
+  isFull: boolean;
+  name: string;
+};
+
+declare const teams: Team[];
+
+<Dropdown
+  getOptionDisabled={(team: Team) => team.isFull}
+  getOptionGroup={(team: Team) => team.department?.name}
+  getOptionLabel={(team: Team) => team.name}
+  getOptionSearchText={(team: Team) => `${team.name} ${team.department?.name ?? ''}`}
+  getOptionValue={(team: Team) => team.id}
+  items={teams}
+  renderLeading={(team: Team) => (
+    <Avatar
+      initials={team.initials}
+      size="xs"
+      source={team.avatarUri ? { uri: team.avatarUri } : undefined}
+      variant={team.avatarUri ? 'image' : 'initial'}
+    />
+  )}
+  showSelectedLeading
+  type="searchable"
+/>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `type` | `single`, `searchable`, or `multi-select`. |
+| `options` | Normalized `DropdownOption[]` with `label`, `value`, optional `group`, `disabled`, and `leading`. |
+| `items` | Raw application or backend data. Use it with `getOptionValue` and `getOptionLabel`. |
+| `getOptionGroup` / `getOptionDisabled` | Optional group label and disabled-state mappers for `items`. |
+| `getOptionSearchText` | Optional additional searchable text for `single` and `searchable` dropdowns. |
+| `renderLeading` | Renders an icon or avatar for raw `items`. |
+| `showSelectedLeading` | Shows the selected leading node in `single` and `searchable` triggers. |
+| `renderOption` / `renderValue` | Escape hatches for custom rows or trigger values. |
+| `value` / `defaultValue` | A string for `single` and `searchable`; a string array for `multi-select`. |
+| `badgeRadius` / `checkboxRadius` | Multi-select tag and checkbox radius overrides. |
+
+For multi-select, use a string array:
+
+```tsx
+const [teamIds, setTeamIds] = useState<readonly string[]>([]);
+
+<Dropdown
+  onValueChange={setTeamIds}
+  options={teamOptions}
+  type="multi-select"
+  value={teamIds}
+/>
+```
+
+### DropdownMenu
+
+`DropdownMenu` is an action menu, not a value-select control.
+
+```tsx
+import { Button, DropdownMenu } from 'neobrutalism-components';
+
+<DropdownMenu
+  align="end"
+  items={[
+    { label: 'Edit', onPress: editProject },
+    { destructive: true, label: 'Delete', onPress: deleteProject },
+    { disabled: true, label: 'Share' },
+  ]}
+  shadowVariant="primary">
+  <Button variant="outline">Actions</Button>
+</DropdownMenu>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `items` | Menu rows with `label`, optional `onPress`, `disabled`, and `destructive`. |
+| `variant` | `default` for vertical actions or `emoji` for horizontal quick reactions. |
+| `align` | Trigger alignment: `start`, `center`, or `end`. Defaults to `start`. |
+| `side` / `sideOffset` | Menu side (`top` or `bottom`) and gap from its trigger. Defaults to `bottom` and `6`. |
+| `shadow` | Enables the neobrutalist shadow. Defaults to `true`. |
+| `shadowVariant` | Shadow color token: `default`, `primary`, `secondary`, `destructive`, `warning`, `success`, or `info`. |
+| `shadowColor` | Explicit shadow color. Takes precedence over `shadowVariant`. |
+| `shadowOffset` | Right-and-bottom shadow thickness. Defaults to the theme shadow offset. |
+| `children` | One trigger element, usually a `Button`. |
+
+### Toast
+
+Use `useToast` inside `ToastProvider` for application notifications.
+
+```tsx
+import { Button, useToast } from 'neobrutalism-components';
+
+export function SaveButton() {
+  const { show } = useToast();
+
+  return (
+    <Button
+      onPress={() =>
+        show({
+          description: 'Your changes have been saved successfully.',
+          title: 'Success',
+          type: 'success',
+        })
+      }>
+      Save changes
+    </Button>
+  );
+}
+```
+
+| Key prop or option | Description |
+| --- | --- |
+| `ToastProvider position` | `top` (default) or `bottom`. |
+| `ToastProvider offset` | Optional viewport offset; safe-area insets are used by default. |
+| `show({ title, description, type })` | Adds a toast of type `success`, `error`, `info`, or `note`. |
+| `duration` | Milliseconds before dismissal; use `null` to keep it open. |
+| `action` | Optional `{ label, onPress }` action. |
+
+`Toast` is also exported for controlled rendering with `open` and
+`onOpenChange`.
+
+```tsx
+import { Toast } from 'neobrutalism-components';
+
+<Toast
+  description="Your changes have been saved successfully."
+  onOpenChange={setToastOpen}
+  open={toastOpen}
+  title="Success"
+  type="success"
+/>
+```
+
+### Dialog and ConfirmDialog
+
+`Dialog` is composable. `ConfirmDialog` provides a focused confirmation flow
+with default or custom actions.
+
+```tsx
+import { useState } from 'react';
+import {
+  Button,
+  Dialog,
+  DialogBody,
+  DialogFooter,
+  DialogHeader,
+} from 'neobrutalism-components';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button onPress={() => setOpen(true)}>Edit profile</Button>
+  <Dialog onOpenChange={setOpen} open={open}>
+    <DialogHeader title="Edit profile" titleNumberOfLines={2} />
+    <DialogBody>{/* Application-owned form content */}</DialogBody>
+    <DialogFooter>
+      <Button onPress={() => setOpen(false)} variant="ghost">Cancel</Button>
+      <Button onPress={saveProfile}>Save</Button>
+    </DialogFooter>
+  </Dialog>
+</>
+```
+
+```tsx
+import { ConfirmDialog } from 'neobrutalism-components';
+
+<ConfirmDialog
+  confirmLabel="Delete"
+  description="This action cannot be undone."
+  onConfirm={deleteProject}
+  onOpenChange={setDeleteOpen}
+  open={deleteOpen}
+  title="Delete project"
+/>
+```
+
+| Component | Key props |
+| --- | --- |
+| `Dialog` | Controlled `open` and `onOpenChange`; compose with `DialogHeader`, `DialogBody`, and `DialogFooter`. |
+| `DialogHeader` | `title`, optional `closeLabel`, and `titleNumberOfLines` (default `1`). |
+| `ConfirmDialog` | `title`, `description`, controlled `open`, `onOpenChange`, `onConfirm`, optional `onCancel`, labels, `icon`, and custom `actions`. |
+
+### BottomSheet
+
+`BottomSheet` uses the dialog portal and anchors to the screen bottom. It
+handles keyboard movement; use `keyboardVerticalOffset` only for a persistent
+screen header that also needs to be cleared.
+
+```tsx
+import { useState } from 'react';
+import { Button, BottomSheet, BottomSheetBody, BottomSheetFooter, BottomSheetHeader } from 'neobrutalism-components';
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button onPress={() => setOpen(true)}>Edit profile</Button>
+  <BottomSheet
+    animation="slide"
+    animationDuration={220}
+    onOpenChange={setOpen}
+    open={open}
+    radius={16}>
+    <BottomSheetHeader title="Update profile" />
+    <BottomSheetBody>{/* Application-owned form content */}</BottomSheetBody>
+    <BottomSheetFooter>
+      <Button onPress={() => setOpen(false)} variant="ghost">Cancel</Button>
+      <Button onPress={saveProfile} variant="warning">Save changes</Button>
+    </BottomSheetFooter>
+  </BottomSheet>
+</>
+```
+
+| Key prop | Description |
+| --- | --- |
+| `open` / `onOpenChange` | Controlled visibility. Tapping the backdrop invokes `onOpenChange(false)`. |
+| `animation` | `slide` (default) or `none`. |
+| `animationDuration` | Open and close duration in milliseconds; defaults to `220`. |
+| `radius` | Overrides both top corner radii. |
+| `shadow` | Shows the platform surface shadow. Defaults to `true`; use `false` for a flat sheet. |
+| `bottomPadding` | Overrides the safe-area spacing below the sheet content. |
+| `keyboardVerticalOffset` | Header offset for keyboard positioning; defaults to `0`. |
+
+## Local Development and Publishing
+
+The package currently resolves directly to `src/index.ts` and has
+`"private": true` in `package.json`; this is deliberate for local iteration.
+
+Before publishing to npm, add an intentional release configuration that:
+
+1. builds JavaScript output rather than shipping TypeScript source only;
+2. emits `.d.ts` declaration files and points `types`/`exports` to them;
+3. removes `private`, chooses a version, and verifies the npm tarball; and
+4. documents the supported React Native and Expo ranges for that release.
+
+Until then, consume the package through the local file dependency and run the
+package typecheck after API changes:
+
+```bash
+pnpm run typecheck
+```