@mrmeg/expo-ui 0.1.1 → 0.1.3

package/LLM_USAGE.md

@@ -0,0 +1,202 @@
+# @mrmeg/expo-ui LLM Usage Guide
+
+This file ships in the npm package. In a consumer repo, read it from
+`node_modules/@mrmeg/expo-ui/LLM_USAGE.md` before building app UI.
+
+## First Rule
+
+Do not recreate primitives that this package already provides. Import from
+`@mrmeg/expo-ui` and compose the exported components in the app.
+
+## Stable Import Paths
+
+```tsx
+import { Button, StyledText, UIProvider } from "@mrmeg/expo-ui/components";
+import { Button as ButtonDirect } from "@mrmeg/expo-ui/components/Button";
+import { colors, spacing, typography } from "@mrmeg/expo-ui/constants";
+import { useResources, useTheme } from "@mrmeg/expo-ui/hooks";
+import { globalUIStore, useThemeStore } from "@mrmeg/expo-ui/state";
+import { hapticLight } from "@mrmeg/expo-ui/lib";
+```
+
+The root barrel also exports the public surface:
+
+```tsx
+import { Button, UIProvider, colors, useTheme } from "@mrmeg/expo-ui";
+```
+
+Use only exported package paths: root, `components`, `components/*`,
+`constants`, `constants/*`, `hooks`, `hooks/*`, `state`, and `lib`. Do not
+import from `@mrmeg/expo-ui/dist/*` or from a source checkout path.
+
+## Required App Setup
+
+Call `useResources()` once near the Expo app root. Mount `UIProvider` once
+near the root when the app uses package feedback or overlay components.
+`UIProvider` owns the package `Notification`, `StatusBar`, and default
+`@rn-primitives` portal host.
+
+```tsx
+import { ThemeProvider } from "@react-navigation/native";
+import { UIProvider } from "@mrmeg/expo-ui/components";
+import { colors } from "@mrmeg/expo-ui/constants";
+import { useResources, useTheme } from "@mrmeg/expo-ui/hooks";
+
+export function RootLayout() {
+  const { scheme } = useTheme();
+  const { loaded } = useResources();
+
+  if (!loaded) return null;
+
+  return (
+    <ThemeProvider
+      value={{
+        dark: colors[scheme ?? "light"].dark,
+        colors: colors[scheme ?? "light"].navigation,
+        fonts: colors[scheme ?? "light"].fonts,
+      }}
+    >
+      <UIProvider>
+        {/* App navigation goes here. */}
+      </UIProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+`UIProvider` mounts the default portal host required before using `Dialog`,
+`AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`,
+`SelectContent`, or `Tooltip`.
+
+## Theme And Text Rules
+
+- Use `useTheme()` and semantic tokens instead of hardcoded colors.
+- Use `StyledText` or its semantic aliases instead of raw `Text` for app UI.
+- Use `Button.preset`, not `variant`, for buttons.
+- Use `globalUIStore` plus root-mounted `UIProvider` for transient global feedback.
+- Keep app monitoring, auth, API, and domain behavior outside this package.
+
+Useful theme tokens include:
+
+```tsx
+theme.colors.background;
+theme.colors.foreground;
+theme.colors.card;
+theme.colors.border;
+theme.colors.primary;
+theme.colors.secondary;
+theme.colors.accent;
+theme.colors.mutedForeground;
+theme.colors.destructive;
+theme.colors.success;
+theme.colors.warning;
+```
+
+Token intent:
+
+- `primary`: neutral action color
+- `secondary`: neutral secondary surface
+- `accent`: teal highlight color
+
+## Component Use-Case Index
+
+Use this table before creating a new app-local primitive.
+
+| Component | Use For | Prefer It Instead Of | Common Example Use Cases |
+|-----------|---------|----------------------|--------------------------|
+| `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections |
+| `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs |
+| `AnimatedView` | Entrance and visibility animation | Hand-rolled Reanimated wrappers | Staggered list rows, revealed panels, animated empty states |
+| `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
+| `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, quick edit forms |
+| `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs |
+| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries |
+| `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters |
+| `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text |
+| `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user |
+| `DismissKeyboard` | Tap-away keyboard dismissal | Screen-level keyboard handling | Forms, search screens, sign-in screens |
+| `Drawer` | Side panels and drawer navigation | Custom sliding panels | Filter drawer, app navigation drawer, inspector panel |
+| `DropdownMenu` | Menus and command lists | Homemade popover menus | Row actions, account menu, sort menu |
+| `EmptyState` | No-data or recoverable error regions | One-off empty placeholders | Empty inbox, no search results, failed list load |
+| `ErrorBoundary` | React render error fallback | Unhandled screen crashes | Route-level fallback, feature boundary |
+| `Icon` | Feather or custom icons with theme tokens | Raw vector icons with hardcoded colors | Button accessories, empty-state icons, menu icons |
+| `InputOTP` | Verification code entry | Multiple manually managed text inputs | Email codes, SMS codes, MFA, invite codes |
+| `Label` | Accessible form labels | Plain styled text labels | Required labels, disabled labels, field group labels |
+| `MaxWidthContainer` | Centered responsive width | Per-screen max-width wrappers | Web pages, tablet layouts, settings forms |
+| `Notification` | Global toast surface | Screen-local toast state | Saved/error/sync notifications, bottom-position alerts |
+| `Popover` | Anchored contextual content | Custom anchored views | Inline help, quick previews, contextual controls |
+| `Progress` | Determinate or indeterminate progress | Layout-shifting spinners for progress regions | Upload progress, onboarding completion |
+| `RadioGroup`, `RadioGroupItem` | Mutually exclusive choices | Custom radio rows | Plan interval, visibility choice, survey answer |
+| `Select` | Option menus | Custom dropdowns | Country picker, category selector, status selector |
+| `Separator` | Horizontal or vertical dividers | Border-only spacer views | Menu dividers, section dividers, card dividers |
+| `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard` | Loading placeholders | Blank space or generic spinners | List loading, profile card loading, dashboard placeholders |
+| `Slider` | Numeric value selection | Custom pan gesture track | Volume, percentage, rating, threshold settings |
+| `StatusBar` | Theme-aware native status bar | Per-screen status-bar duplication | Root layout status styling |
+| `StyledText` and text aliases | Theme-aware typography | Raw `Text` with hardcoded styles | Titles, headings, labels, body copy, captions |
+| `Switch` | Binary settings | Custom toggle switches | Enable notifications, privacy setting, feature toggles |
+| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | In-page tabbed views | Custom segmented/tab controls | Profile sections, report views, settings categories |
+| `TextInput` | Text entry | Raw `TextInput` with repeated label/error code | Email/password, search, numeric input, multiline notes |
+| `Toggle`, `ToggleIcon` | Pressed/unpressed control | Button with local selected styling | Favorite, mute, bold/italic, view mode button |
+| `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupIcon` | Single or multi toggle groups | Custom segmented controls | Alignment, formatting toolbar, filter chips |
+| `Tooltip` | Short hover/focus help | Persistent helper text or custom hover cards | Icon button labels, field hints, disabled action explanations |
+
+## Component Selection Rules
+
+- Use `Button` for commands, `Toggle` for one pressed state, `ToggleGroup` for related pressed states, and `Switch` for binary settings.
+- Use `RadioGroup` for small mutually exclusive choices and `Select` for longer option sets.
+- Use `Dialog` for blocking decisions, `Popover` for contextual controls, `Tooltip` for short explanations, and `DropdownMenu` for action lists.
+- Use `Card` for individual repeated or framed items, not as a wrapper around full page sections.
+- Use `EmptyState` for no-data or recoverable error regions.
+- Use `Skeleton` for loading content with stable layout.
+- Use `Progress` for real progress or indeterminate long-running work.
+
+## Minimal Examples
+
+```tsx
+import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@mrmeg/expo-ui/components";
+
+<Card variant="outline">
+  <CardHeader>
+    <CardTitle>Subscription</CardTitle>
+    <Badge variant="secondary">Active</Badge>
+  </CardHeader>
+  <CardContent>
+    <Button preset="default" fullWidth>
+      Manage billing
+    </Button>
+  </CardContent>
+</Card>
+```
+
+```tsx
+import { Button, Switch, TextInput } from "@mrmeg/expo-ui/components";
+
+<TextInput
+  label="Email"
+  placeholder="you@example.com"
+  autoCapitalize="none"
+  keyboardType="email-address"
+  errorText={emailError}
+/>
+
+<Switch checked={enabled} onCheckedChange={setEnabled} variant="ios" />
+
+<Button preset="default" size="lg" fullWidth loading={isSubmitting}>
+  Continue
+</Button>
+```
+
+```tsx
+import { EmptyState, Progress, SkeletonCard } from "@mrmeg/expo-ui/components";
+import { globalUIStore } from "@mrmeg/expo-ui/state";
+
+{isLoading ? <SkeletonCard /> : null}
+<Progress value={65} variant="accent" />
+<EmptyState icon="inbox" title="No messages" description="New messages will appear here." />
+
+globalUIStore.getState().show({
+  type: "success",
+  title: "Saved",
+  messages: ["Your changes were saved."],
+});
+```

package/README.md

@@ -8,6 +8,14 @@ package, not a generally supported open-source UI library. The package is
 published as `UNLICENSED`; use outside MrMeg projects requires explicit
 permission.
 
+## For LLMs And Coding Agents
+
+When this package is installed from npm, read
+`node_modules/@mrmeg/expo-ui/LLM_USAGE.md` before creating app-local UI
+primitives. That file is shipped in the npm package and gives the short
+component-selection rules, import paths, setup requirements, and examples that
+help agents choose existing package components instead of rebuilding them.
+
 ## Install
 
 Install from npm after publishing:
@@ -19,17 +27,22 @@ bun add @mrmeg/expo-ui
 Consumers must also install the peer dependencies listed in `package.json`.
 The tested baseline is Expo SDK 55 with React 19.2, React Native 0.83,
 React Native Web 0.21, Reanimated 4.2, Worklets 0.7, and
-`@rn-primitives/*` 1.4. Start consumer apps from the same Expo SDK family
-or update the package and peer ranges deliberately. Keep npm auth tokens in
-developer or CI configuration, not in this repository.
+`@rn-primitives/*` 1.4. `@rn-primitives/portal` is package-managed because
+`UIProvider` mounts the portal host used by package overlays. `i18next` and
+`react-i18next` are runtime peers because `StyledText` and `Notification`
+support translated text keys. Start consumer apps from the same Expo SDK
+family or update the package and peer ranges deliberately. Keep npm auth tokens
+in developer or CI configuration, not in this repository.
 
 ## Imports
 
 ```tsx
-import { Button, StyledText } from "@mrmeg/expo-ui/components";
+import { Button, StyledText, UIProvider } from "@mrmeg/expo-ui/components";
 import { Button as ButtonDirect } from "@mrmeg/expo-ui/components/Button";
 import { colors, spacing, typography } from "@mrmeg/expo-ui/constants";
+import { colors as colorsDirect } from "@mrmeg/expo-ui/constants/colors";
 import { useResources, useTheme } from "@mrmeg/expo-ui/hooks";
+import { useTheme as useThemeDirect } from "@mrmeg/expo-ui/hooks/useTheme";
 import { globalUIStore, useThemeStore } from "@mrmeg/expo-ui/state";
 import { hapticLight } from "@mrmeg/expo-ui/lib";
 ```
@@ -37,7 +50,7 @@ import { hapticLight } from "@mrmeg/expo-ui/lib";
 The root barrel also exports the public surface:
 
 ```tsx
-import { Button, colors, useTheme } from "@mrmeg/expo-ui";
+import { Button, UIProvider, colors, useTheme } from "@mrmeg/expo-ui";
 ```
 
 ## Theme System
@@ -105,33 +118,88 @@ Useful `StyledText` props:
 
 ## Component Guide
 
-All components are exported from `@mrmeg/expo-ui/components`; direct imports such as `@mrmeg/expo-ui/components/Button` are supported.
-
-Layout:
-
-- `AnimatedView` - Reanimated visibility/entrance wrapper.
-- `Card` - Framed content with `variant`: `default`, `outline`, `ghost`; includes `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`.
-- `MaxWidthContainer` - Centered responsive content width.
-- `Separator` - Theme-aware divider.
-- `DismissKeyboard` - Tap-away keyboard dismissal wrapper.
-
-Forms and actions:
-
-- `Button` - Commands with `preset`: `default` for primary neutral actions, `secondary` for neutral secondary actions, plus `outline`, `ghost`, `link`, and `destructive`; `size`: `sm`, `md`, `lg`; supports `loading`, `fullWidth`, accessories, and shadows.
-- `TextInput` - Inputs with `variant`: `outline`, `filled`, `underlined`; `size`: `sm`, `md`, `lg`; supports labels, helper/error text, clear/password affordances, and left/right elements.
-- `Checkbox`, `RadioGroup`, `Select`, `Switch`, `Toggle`, `ToggleGroup`, `InputOTP`, `Slider`, `Label` - Form controls built on package tokens and `@rn-primitives` where applicable.
-
-Feedback:
-
-- `Alert`, `Badge`, `Notification`, `Progress`, `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `EmptyState`, `StatusBar`.
-- Mount `Notification` once near the app root; trigger it with `globalUIStore`.
-
-Overlays and navigation:
-
-- `Dialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `Tooltip` require `PortalHost` near the app root.
-- `Tabs`, `Accordion`, and `Collapsible` cover in-page navigation and disclosure.
-
-Example:
+All components are exported from `@mrmeg/expo-ui/components`; direct imports such as `@mrmeg/expo-ui/components/Button` are supported. Use this table as the first stop before building a new primitive in a consumer app.
+
+### LLM Component Use-Case Index
+
+| Component | Use For | Prefer It Instead Of | Common Example Use Cases |
+|-----------|---------|----------------------|--------------------------|
+| `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections, dense detail pages |
+| `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs, simple blocking messages |
+| `AnimatedView` | Entrance and visibility animation | Hand-rolled Reanimated wrappers | Staggered list rows, revealed panels, animated empty states |
+| `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
+| `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, quick edit forms, contextual details |
+| `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs, icon-accessory buttons |
+| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries, dashboards |
+| `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters, notification opt-ins |
+| `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text, optional details |
+| `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user, blocking warnings |
+| `DismissKeyboard` | Tap-away keyboard dismissal | Screen-level keyboard handling | Forms, search screens, sign-in screens |
+| `Drawer` | Side panels and drawer navigation | Custom sliding panels | Filter drawer, app navigation drawer, inspector panel |
+| `DropdownMenu` | Menus and command lists | Homemade popover menus | Row actions, account menu, sort menu, checkbox/radio menu groups |
+| `EmptyState` | No-data or recoverable error regions | One-off empty placeholders | Empty inbox, no search results, missing permissions, failed list load |
+| `ErrorBoundary` | React render error fallback | Unhandled screen crashes | Route-level fallback, feature boundary, recoverable widget crashes |
+| `Icon` | Feather or custom icons with theme tokens | Raw vector icons with hardcoded colors | Button accessories, empty-state icons, menu icons, status glyphs |
+| `InputOTP` | Verification code entry | Multiple manually managed text inputs | Email codes, SMS codes, MFA, invite codes |
+| `Label` | Accessible form labels | Plain styled text labels | Required labels, disabled labels, field group labels |
+| `MaxWidthContainer` | Centered responsive width | Per-screen max-width wrappers | Web pages, tablet layouts, settings forms, auth panels |
+| `Notification` | Global toast surface | Screen-local toast state | Saved/error/sync notifications, loading toast, bottom-position alerts |
+| `Popover` | Anchored contextual content | Custom anchored views | Inline help, quick previews, contextual controls, small forms |
+| `Progress` | Determinate or indeterminate progress | Layout-shifting spinners for progress regions | Upload progress, onboarding completion, long-running task state |
+| `RadioGroup`, `RadioGroupItem` | Mutually exclusive choices | Custom radio rows | Plan interval, visibility choice, survey answer, preference setting |
+| `Select` | Option menus | Custom dropdowns | Country picker, category selector, status selector, compact form choice |
+| `Separator` | Horizontal or vertical dividers | Border-only spacer views | Menu dividers, section dividers, card dividers |
+| `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard` | Loading placeholders | Blank space or generic spinners | List loading, profile card loading, dashboard placeholders |
+| `Slider` | Numeric value selection | Custom pan gesture track | Volume, percentage, rating, threshold, range-like settings |
+| `StatusBar` | Theme-aware native status bar | Per-screen status-bar duplication | Root layout status styling, dark/light mode updates |
+| `StyledText` and text aliases | Theme-aware typography | Raw `Text` with hardcoded styles | Titles, headings, labels, body copy, captions, translated text |
+| `Switch` | Binary settings | Custom toggle switches | Enable notifications, privacy setting, feature toggles |
+| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | In-page tabbed views | Custom segmented/tab controls | Profile sections, report views, settings categories |
+| `TextInput` | Text entry | Raw `TextInput` with repeated label/error code | Email/password, search, numeric input, multiline notes |
+| `Toggle`, `ToggleIcon` | Pressed/unpressed control | Button with local selected styling | Favorite, mute, bold/italic, view mode button |
+| `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupIcon` | Single or multi toggle groups | Custom segmented controls | Alignment, formatting toolbar, filter chips, view mode switcher |
+| `Tooltip` | Short hover/focus help | Persistent helper text or custom hover cards | Icon button labels, field hints, disabled action explanations |
+
+### Compound Parts And Aliases
+
+Most compound components support both direct named imports and dot notation on the root component. Prefer the named exports when code completion or LLM context benefits from explicit names.
+
+| Root | Exported Parts |
+|------|----------------|
+| `Accordion` | `AccordionItem`, `AccordionTrigger`, `AccordionContent` |
+| `AlertDialog` | `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogAction`, `AlertDialogCancel` |
+| `BottomSheet` | `BottomSheetTrigger`, `BottomSheetContent`, `BottomSheetHandle`, `BottomSheetHeader`, `BottomSheetBody`, `BottomSheetFooter`, `BottomSheetClose` |
+| `Card` | `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` |
+| `Collapsible` | `CollapsibleTrigger`, `CollapsibleContent` |
+| `Dialog` | `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose` |
+| `Drawer` | `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerClose` |
+| `DropdownMenu` | `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuPortal`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent` |
+| `Popover` | `PopoverTrigger`, `PopoverContent`, `PopoverHeader`, `PopoverBody`, `PopoverFooter` |
+| `RadioGroup` | `RadioGroupItem` |
+| `Select` | `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator` |
+| `Skeleton` | `SkeletonText`, `SkeletonAvatar`, `SkeletonCard` |
+| `Tabs` | `TabsList`, `TabsTrigger`, `TabsContent` |
+| `Toggle` | `ToggleIcon` |
+| `ToggleGroup` | `ToggleGroupItem`, `ToggleGroupIcon` |
+| `Tooltip` | `TooltipTrigger`, `TooltipContent`, `TooltipBody` |
+
+Text aliases are exported for common semantic typography: `SerifText`, `SansSerifText`, `SerifBoldText`, `SansSerifBoldText`, `DisplayText`, `TitleText`, `HeadingText`, `SubheadingText`, `BodyText`, `CaptionText`, and `LabelText`. `TextClassContext` and `TextColorContext` are advanced context exports used by package controls to pass nested text styling.
+
+### Common Patterns
+
+Use `Button.preset`, not `variant`. `default` is the neutral primary action, `secondary` is a neutral secondary surface, `outline` is for lower-emphasis actions, `ghost` is for compact toolbars, `link` is for text-like commands, and `destructive` is for dangerous actions.
+
+Use `StyledText` or its aliases instead of raw `Text` whenever the text is part of app UI. Use `TextInput` for labeled fields because it already owns label, helper text, error text, clear buttons, password visibility, numeric filtering, and left/right elements.
+
+Mount `UIProvider` once near the root before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, or package notifications. Trigger transient feedback from `globalUIStore`.
+
+Use `Skeleton` components for loading content with stable dimensions, `EmptyState` for no-data/recoverable errors, `Alert` for blocking confirm/alert dialogs, and `Notification` for transient global feedback.
+
+Use `Toggle` for one pressed state, `ToggleGroup` for a related set of pressed states, `Switch` for binary settings, `RadioGroup` for small mutually exclusive choices, and `Select` for longer option sets.
+
+### Quick Examples
+
+Card, badge, and CTA:
 
 ```tsx
 import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@mrmeg/expo-ui/components";
@@ -149,12 +217,49 @@ import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@mrmeg/
 </Card>
 ```
 
+Form controls:
+
+```tsx
+import { Button, TextInput, Switch } from "@mrmeg/expo-ui/components";
+
+<TextInput
+  label="Email"
+  placeholder="you@example.com"
+  autoCapitalize="none"
+  keyboardType="email-address"
+  errorText={emailError}
+/>
+
+<Switch checked={enabled} onCheckedChange={setEnabled} variant="ios" />
+
+<Button preset="default" size="lg" fullWidth loading={isSubmitting}>
+  Continue
+</Button>
+```
+
+Feedback:
+
+```tsx
+import { EmptyState, Progress, SkeletonCard } from "@mrmeg/expo-ui/components";
+import { globalUIStore } from "@mrmeg/expo-ui/state";
+
+{isLoading ? <SkeletonCard /> : null}
+<Progress value={65} variant="accent" />
+<EmptyState icon="inbox" title="No messages" description="New messages will appear here." />
+
+globalUIStore.getState().show({
+  type: "success",
+  title: "Saved",
+  messages: ["Your changes were saved."],
+});
+```
+
 LLM rules:
 
 - Prefer `StyledText` semantic variants over raw `Text`.
 - Use `useTheme()` and semantic tokens instead of hardcoded colors.
 - Use `Button.preset`, not `variant`, for buttons.
-- Mount `PortalHost` before using overlays, menus, select content, popovers, or tooltips.
+- Mount `UIProvider` before using overlays, menus, select content, popovers, tooltips, or package notifications.
 - Import from package exports, not `packages/ui/src/*`.
 
 ## App Startup
@@ -165,8 +270,7 @@ Call `useResources()` once near the Expo app root before hiding the splash scree
 import { ThemeProvider } from "@react-navigation/native";
 import { colors } from "@mrmeg/expo-ui/constants";
 import { useResources, useTheme } from "@mrmeg/expo-ui/hooks";
-import { Notification, StatusBar } from "@mrmeg/expo-ui/components";
-import { PortalHost } from "@rn-primitives/portal";
+import { UIProvider } from "@mrmeg/expo-ui/components";
 
 export default function RootLayout() {
   const { scheme } = useTheme();
@@ -182,10 +286,9 @@ export default function RootLayout() {
         fonts: colors[scheme ?? "light"].fonts,
       }}
     >
-      {/* App navigation goes here. */}
-      <Notification />
-      <PortalHost />
-      <StatusBar />
+      <UIProvider>
+        {/* App navigation goes here. */}
+      </UIProvider>
     </ThemeProvider>
   );
 }
@@ -211,7 +314,50 @@ On native, the package uses platform sans-serif fallbacks. `useResources()` stil
 
 ## Package Checks
 
-Run these before publishing:
+For a one-command release from the repo root, use:
+
+```sh
+bun run ui:release -- --patch --publish
+```
+
+Replace `--patch` with `--minor`, `--major`, or an exact version such as `0.2.0`.
+The command updates `packages/ui/package.json` and `bun.lock`, runs all package
+gates, then publishes with `npm publish --access public` only when `--publish`
+is present. Without `--publish`, it performs the same version bump and gates as
+a dry run.
+
+The release command requires a clean working tree by default. Commit current
+changes first, or pass `--allow-dirty` when you intentionally want to release
+from uncommitted local changes.
+
+If npm login email is unavailable, publish through GitHub Actions trusted
+publishing instead:
+
+1. In npm package settings for `@mrmeg/expo-ui`, add a trusted publisher:
+   GitHub Actions, owner `mrmeg`, repository `expo-template`, workflow
+   filename `publish-ui.yml`.
+2. In GitHub Actions, run the `Publish UI Package` workflow with `version=patch`
+   and `ref=dev`.
+
+The workflow uses npm OIDC, not a checked-in token or local npm login. It bumps
+the package version, updates `bun.lock`, runs the package gates, lets npm CLI
+use the GitHub Actions OIDC environment, commits the version bump, and publishes
+from `packages/ui`.
+
+Keep `repository.url` in `package.json` as
+`git+https://github.com/mrmeg/expo-template.git`. npm trusted publishing checks
+that metadata during publish, and publish-time URL normalization can block OIDC
+auth.
+
+If npm trusted publishing is blocked by package settings, add an npm automation
+or granular publish token to GitHub Actions secrets as `NPM_TOKEN` and rerun the
+same workflow. The token is used only for the publish step.
+
+If the workflow fails after the version is already bumped, rerun it with the
+exact current package version, for example `version=0.1.2`. Exact-version reruns
+do not bump again.
+
+Manual package checks:
 
 ```sh
 bun run ui:typecheck
@@ -224,5 +370,6 @@ bun run ui:consumer-smoke
 `bun run ui:pack` runs a dry pack so the published file list and package size can be inspected before release.
 `bun run ui:consumer-smoke` installs the packed tarball into a clean fixture,
 checks the documented export-map files, type-checks all public package
-entrypoints, and verifies that `@mrmeg/expo-ui/constants` can be imported
-by plain Node ESM for token inspection.
+entrypoints, verifies that `@mrmeg/expo-ui/constants` can be imported by
+plain Node ESM for token inspection, and runs an Expo SDK 55 iOS export
+against the packed package without a custom Metro config.

package/dist/components/UIProvider.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+export interface UIProviderProps {
+    children: React.ReactNode;
+    /**
+     * Mount the package notification renderer for globalUIStore feedback.
+     *
+     * @default true
+     */
+    notification?: boolean;
+    /**
+     * Mount the default @rn-primitives portal host used by package overlays.
+     *
+     * @default true
+     */
+    portalHost?: boolean;
+    /**
+     * Mount the package status bar renderer.
+     *
+     * @default true
+     */
+    statusBar?: boolean;
+}
+export declare function UIProvider({ children, notification, portalHost, statusBar, }: UIProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/UIProvider.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { PortalHost } from "@rn-primitives/portal";
+import { Notification } from "./Notification.js";
+import { StatusBar } from "./StatusBar.js";
+export function UIProvider({ children, notification = true, portalHost = true, statusBar = true, }) {
+    return (_jsxs(_Fragment, { children: [children, notification ? _jsx(Notification, {}) : null, portalHost ? _jsx(PortalHost, {}) : null, statusBar ? _jsx(StatusBar, {}) : null] }));
+}

package/dist/components/index.d.ts

@@ -33,3 +33,4 @@ export * from "./TextInput";
 export * from "./Toggle";
 export * from "./ToggleGroup";
 export * from "./Tooltip";
+export * from "./UIProvider";

package/dist/components/index.js

@@ -33,3 +33,4 @@ export * from "./TextInput.js";
 export * from "./Toggle.js";
 export * from "./ToggleGroup.js";
 export * from "./Tooltip.js";
+export * from "./UIProvider.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -31,7 +31,8 @@
   "files": [
     "dist",
     "package.json",
-    "README.md"
+    "README.md",
+    "LLM_USAGE.md"
   ],
   "exports": {
     ".": {
@@ -50,10 +51,18 @@
       "types": "./dist/constants/index.d.ts",
       "default": "./dist/constants/index.js"
     },
+    "./constants/*": {
+      "types": "./dist/constants/*.d.ts",
+      "default": "./dist/constants/*.js"
+    },
     "./hooks": {
       "types": "./dist/hooks/index.d.ts",
       "default": "./dist/hooks/index.js"
     },
+    "./hooks/*": {
+      "types": "./dist/hooks/*.d.ts",
+      "default": "./dist/hooks/*.js"
+    },
     "./state": {
       "types": "./dist/state/index.d.ts",
       "default": "./dist/state/index.js"
@@ -69,6 +78,9 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/fix-ui-package-esm.mjs",
     "publish:dry-run": "bun pm pack --dry-run"
   },
+  "dependencies": {
+    "@rn-primitives/portal": "~1.4.0"
+  },
   "peerDependencies": {
     "@expo/vector-icons": ">=15.0.0 <16.0.0",
     "@react-native-async-storage/async-storage": ">=2.2.0 <2.3.0",
@@ -80,7 +92,6 @@
     "@rn-primitives/dropdown-menu": "~1.4.0",
     "@rn-primitives/label": "~1.4.0",
     "@rn-primitives/popover": "~1.4.0",
-    "@rn-primitives/portal": "~1.4.0",
     "@rn-primitives/radio-group": "~1.4.0",
     "@rn-primitives/select": "~1.4.0",
     "@rn-primitives/separator": "~1.4.0",
@@ -94,11 +105,14 @@
     "expo": "~55.0.0",
     "expo-font": "~55.0.0",
     "expo-haptics": "~55.0.0",
+    "i18next": ">=25.0.0 <27.0.0",
     "react": ">=19.2.0 <20.0.0",
+    "react-i18next": ">=15.0.0 <18.0.0",
     "react-native": ">=0.83.0 <0.84.0",
     "react-native-gesture-handler": "~2.30.0",
     "react-native-reanimated": "~4.2.0",
     "react-native-safe-area-context": "~5.6.0",
+    "react-native-screens": "~4.23.0",
     "react-native-web": ">=0.21.0 <0.22.0",
     "react-native-worklets": "~0.7.0",
     "zustand": ">=5.0.0 <6.0.0"