@mrmeg/expo-ui 0.27.0 → 0.28.0

package/llms-full.md

@@ -90,6 +90,52 @@ When the saved theme preference is `system`, the package theme store owns OS
 color-scheme sync, including web `prefers-color-scheme`. Apps must not add their
 own `Appearance` or `matchMedia` listeners for package components.
 
+## Screen Layout
+
+Screens are flat. On a 390 pt phone each nested inset comes out of the content:
+rows boxed in a bordered group inside a padded screen start 33 pt from each edge
+(16 + 1 + 16) with 324 pt left for them; the same rows in an `ItemGroup` start
+16 pt in with 358 pt.
+
+- One horizontal inset per screen: `spacing.screenPadding` (16). Either a
+  container pads or its children do, never both. `Item` rows and `ItemGroup`
+  titles and footers carry the 16 themselves, so a scroll view of groups gets
+  no horizontal padding; text, forms, and buttons between them pad their own
+  wrapper.
+- No boxes as layout: no bordered, shadowed, or tinted rounded panel (or `Card`)
+  around a section, a form, or a group of rows. Separate sections with a header,
+  `spacing.sectionSpacing` (24), or a hairline (`Separator`).
+- Lists and settings are `ItemGroup` + `Item`: full-width rows and touch
+  targets, hairlines inset under the title, no card per row, no border around
+  the group. Rows are direct children; the group separates them.
+- Forms: fields span the column, grouped under section headers, not cards.
+- Primary content (photos, video, maps, QR codes, charts) sizes to the column
+  width, never a fixed size floating in whitespace.
+- Wide screens cap and centre the column (`width: "100%", maxWidth: 640,
+  alignSelf: "center"` on the scroll content; 960 for dense grids) instead of
+  boxing it.
+- `Card` is for one item in a collection (feed entry, grid tile, carousel slide)
+  or a single tappable object; `StatCard` likewise (a scrolling metrics rail, a
+  tappable metric). Never nest them.
+- Dialog, sheet, and popover chrome keep their surfaces.
+
+```tsx
+<ScrollView contentContainerStyle={{ width: "100%", maxWidth: 640, alignSelf: "center", paddingVertical: spacing.md, gap: spacing.sectionSpacing }}>
+  <ItemGroup title="Account" footer="Signed in as jane@example.com">
+    <Item onPress={openProfile}>
+      <ItemMedia icon="user" />
+      <ItemContent><ItemTitle>Edit profile</ItemTitle></ItemContent>
+      <ItemActions><Icon name="chevron-right" size={18} color="mutedForeground" /></ItemActions>
+    </Item>
+    <Item>
+      <ItemMedia icon="bell" />
+      <ItemContent><ItemTitle>Notifications</ItemTitle></ItemContent>
+      <ItemActions><Switch checked={enabled} onCheckedChange={setEnabled} /></ItemActions>
+    </Item>
+  </ItemGroup>
+</ScrollView>
+```
+
 ## Component Catalog
 
 Every component is exported from `@mrmeg/expo-ui/components`, and from
@@ -105,7 +151,7 @@ before creating a new app-local primitive.
 | `Badge` | Short status labels | Prefer over custom pill views. |
 | `BottomSheet` | Mobile-first modal sheets | Requires root `UIProvider`. Native sheet via `@expo/ui`; `swipeEnabled`, `avoidKeyboard`, `dismissKeyboardOnDrag` are accepted but ignored (the iOS sheet presentation and Android Material3 keep content above the keyboard; never nest a `KeyboardAvoidingView` in a sheet). |
 | `Button` | Commands and CTAs | Use `preset`, not `variant`; heights are 28/32/40. |
-| `Card` | Individual framed content groups | Do not wrap whole page sections in cards. |
+| `Card` | One item in a collection (feed entry, grid tile, carousel slide) or a single tappable object | Not a layout box: never around a section, form, or row group; never nested. Parts pad `spacing.cardPadding`. |
 | `Carousel` | Small known set of horizontally snapping slides | Renders every child (no virtualization); fractional `itemWidth` measures the viewport until first layout. |
 | `Checkbox` | Boolean selection in forms or lists | Prefer over custom checkmark controls. |
 | `Collapsible` | One-off disclosure | Use for advanced settings or helper sections. |
@@ -118,6 +164,7 @@ before creating a new app-local primitive.
 | `Icon` | Lucide or custom icons with theme tokens | `color` takes a theme color name; pass `decorative` to hide from a11y. |
 | `InputOTP` | Verification code entry | Prefer over manually managed text input groups. |
 | `Item` | List / settings rows | Applies the row density tokens and a 44px native hit area (40px on web). |
+| `ItemGroup` | A titled group of full-width `Item` rows | Props: `title`, `description`, `footer`, `style`, `testID`. Draws inset hairlines between rows; no border, fill, or horizontal padding, so the parent must not pad either. |
 | `KeyboardAvoidingView` | Native keyboard-aware roots, composer footers, form-heavy subtrees | `UIProvider` already mounts one root; use directly only for custom subtrees. |
 | `Label` | Accessible form labels | Two distinct ids: `nativeID` is the label's, `htmlFor` is the input's `nativeID`. Never reuse one id for both. |
 | `MaxWidthContainer` | Centered responsive width | Use for web and tablet constrained layouts. |
@@ -131,7 +178,7 @@ before creating a new app-local primitive.
 | `Separator` | Horizontal or vertical dividers | Prefer over border-only spacer views. |
 | `Skeleton` | Loading placeholders | Use stable dimensions to avoid layout shift. |
 | `Slider` | Numeric value selection | Backed by `@expo/ui`; prefer over custom pan gesture tracks. |
-| `StatCard` | Metric tile | Props: `label`, `value`, `unit`, `change` (`{ value, direction }`), `icon`, `onPress`. |
+| `StatCard` | Metric tile in a collection, or one tappable metric | Props: `label`, `value`, `unit`, `change` (`{ value, direction }`), `icon`, `onPress`. A Card, so the same rule applies. |
 | `StatusBar` | Theme-aware native status bar | Usually mounted through `UIProvider`. |
 | `StyledText` | Theme-aware typography | Prefer semantic aliases over raw `Text`. |
 | `Switch` | Binary settings | Prefer over custom toggles for on/off state. |
@@ -156,9 +203,10 @@ option sets.
 `Dialog` blocking decisions · `Popover` contextual controls · `Tooltip` short
 explanations · `DropdownMenu` action lists.
 
-`Card` individual repeated or framed items, never a wrapper around full page
-sections · `EmptyState` no-data or recoverable errors · `Skeleton` loading
-content with stable layout · `Progress` real or indeterminate progress.
+`ItemGroup` + `Item` lists and settings · `Card` one item in a collection or one
+tappable object, never a wrapper around a section, form, or row group, never
+nested · `EmptyState` no-data or recoverable errors · `Skeleton` loading content
+with stable layout · `Progress` real or indeterminate progress.
 
 ## Notifications
 
@@ -196,6 +244,6 @@ selectors and tests. Use `notify` for imperative triggers in app code.
 ## Validation
 
 Changing package code or shipped docs? Run the gates from the monorepo root:
-`ui:typecheck`, `ui:test`, `ui:build`, `ui:pack`, `ui:consumer-smoke`
-(`bun run <gate>`). Docs-only changes need at least `ui:pack`, which proves the
-new docs land in the npm tarball.
+`typecheck`, `test`, `build`, `pack`, `consumer-smoke` (`bun run pkg ui <gate>`).
+Docs-only changes need at least `bun run pkg ui pack`, which proves the new docs
+land in the npm tarball.

package/llms.txt

@@ -30,7 +30,16 @@ gestures and keyboard avoidance; swipeEnabled, avoidKeyboard, and
 dismissKeyboardOnDrag are accepted but ignored. On iOS the sheet presentation
 lifts or shrinks the hosted content so Footer and Body end at the keyboard's
 top (device-verified); Android avoidance is Material3's. Do not nest a
-KeyboardAvoidingView inside a sheet.
+KeyboardAvoidingView inside a sheet. Open the next modal from the sheet's
+onDismissed callback (fires once the sheet is fully gone), not from
+onOpenChange(false).
+
+Screens are flat: one 16 pt horizontal inset (spacing.screenPadding), either
+on the container or on its children, never both. Lists and settings are
+ItemGroup + Item (full-width rows, inset hairlines), never rows inside a
+bordered, shadowed, or tinted panel. Card is for one item in a collection or one
+tappable object; never nest Cards. Media and charts fill the column width; wide
+screens cap and centre the column. LLM_USAGE.md "Screen Layout" has the rules.
 
 Use useTheme(), useStyles(), semantic tokens, StyledText, and package controls.
 Do not add app-local Appearance or matchMedia listeners for theme sync. On web

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -29,6 +29,10 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./src/state/themeStore.ts",
+    "./dist/state/themeStore.js"
+  ],
   "files": [
     "dist",
     "package.json",
@@ -40,42 +44,105 @@
   ],
   "exports": {
     ".": {
+      "@mrmeg/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./components": {
+      "@mrmeg/source": "./src/components/index.ts",
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./components/bottomSheetDismiss": {
+      "@mrmeg/source": "./src/components/bottomSheetDismiss.ts",
+      "types": "./dist/components/bottomSheetDismiss.d.ts",
+      "default": "./dist/components/bottomSheetDismiss.js"
+    },
+    "./components/bottomSheetHostSupport": {
+      "@mrmeg/source": "./src/components/bottomSheetHostSupport.ts",
+      "types": "./dist/components/bottomSheetHostSupport.d.ts",
+      "default": "./dist/components/bottomSheetHostSupport.js"
+    },
+    "./components/iconRegistry.generated": {
+      "@mrmeg/source": "./src/components/iconRegistry.generated.ts",
+      "types": "./dist/components/iconRegistry.generated.d.ts",
+      "default": "./dist/components/iconRegistry.generated.js"
+    },
+    "./components/index": {
+      "@mrmeg/source": "./src/components/index.ts",
       "types": "./dist/components/index.d.ts",
       "default": "./dist/components/index.js"
     },
+    "./components/keyboardController": {
+      "@mrmeg/source": {
+        "react-native": "./src/components/keyboardController.native.ts",
+        "default": "./src/components/keyboardController.ts"
+      },
+      "types": "./dist/components/keyboardController.d.ts",
+      "default": "./dist/components/keyboardController.js"
+    },
+    "./components/keyboardDismiss": {
+      "@mrmeg/source": "./src/components/keyboardDismiss.ts",
+      "types": "./dist/components/keyboardDismiss.d.ts",
+      "default": "./dist/components/keyboardDismiss.js"
+    },
+    "./components/keyboardFocusRegistry": {
+      "@mrmeg/source": "./src/components/keyboardFocusRegistry.ts",
+      "types": "./dist/components/keyboardFocusRegistry.d.ts",
+      "default": "./dist/components/keyboardFocusRegistry.js"
+    },
+    "./components/StyledText.context": {
+      "@mrmeg/source": "./src/components/StyledText.context.ts",
+      "types": "./dist/components/StyledText.context.d.ts",
+      "default": "./dist/components/StyledText.context.js"
+    },
     "./components/*": {
+      "@mrmeg/source": "./src/components/*.tsx",
       "types": "./dist/components/*.d.ts",
       "default": "./dist/components/*.js"
     },
     "./constants": {
+      "@mrmeg/source": "./src/constants/index.ts",
       "types": "./dist/constants/index.d.ts",
       "default": "./dist/constants/index.js"
     },
     "./constants/*": {
+      "@mrmeg/source": "./src/constants/*.ts",
       "types": "./dist/constants/*.d.ts",
       "default": "./dist/constants/*.js"
     },
     "./hooks": {
+      "@mrmeg/source": "./src/hooks/index.ts",
       "types": "./dist/hooks/index.d.ts",
       "default": "./dist/hooks/index.js"
     },
+    "./hooks/useReduceMotion": {
+      "@mrmeg/source": "./src/hooks/useReduceMotion.tsx",
+      "types": "./dist/hooks/useReduceMotion.d.ts",
+      "default": "./dist/hooks/useReduceMotion.js"
+    },
     "./hooks/*": {
+      "@mrmeg/source": "./src/hooks/*.ts",
       "types": "./dist/hooks/*.d.ts",
       "default": "./dist/hooks/*.js"
     },
     "./state": {
+      "@mrmeg/source": "./src/state/index.ts",
       "types": "./dist/state/index.d.ts",
       "default": "./dist/state/index.js"
     },
+    "./state/themeColorScope": {
+      "@mrmeg/source": "./src/state/themeColorScope.tsx",
+      "types": "./dist/state/themeColorScope.d.ts",
+      "default": "./dist/state/themeColorScope.js"
+    },
     "./state/*": {
+      "@mrmeg/source": "./src/state/*.ts",
       "types": "./dist/state/*.d.ts",
       "default": "./dist/state/*.js"
     },
     "./lib": {
+      "@mrmeg/source": "./src/lib/index.ts",
       "types": "./dist/lib/index.d.ts",
       "default": "./dist/lib/index.js"
     },
@@ -129,7 +196,7 @@
     "zustand": ">=5.0.0 <6.0.0"
   },
   "devDependencies": {
-    "@types/react": "~19.2.18",
+    "@types/react": "~19.3.0",
     "typescript": "~6.0.3"
   }
 }