@mrmeg/expo-ui 0.1.1 → 0.1.2

package/README.md

@@ -19,9 +19,11 @@ 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. `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
 
@@ -29,7 +31,9 @@ developer or CI configuration, not in this repository.
 import { Button, StyledText } 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";
 ```
@@ -105,33 +109,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 `PortalHost` once before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, or `Tooltip`. Mount `Notification` once near the root and trigger it 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,6 +208,43 @@ 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`.
@@ -211,7 +307,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 +363,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -50,10 +50,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"
@@ -94,11 +102,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"