@mrmeg/expo-ui 0.27.1 → 0.28.0

package/dist/state/themeStore.js

@@ -38,6 +38,10 @@ export const useThemeStore = create((set) => ({
     fontOverrides: {},
     // And again for shape: package geometry until a host app calls `setShape`.
     shapeOverrides: {},
+    serifPreset: "georgia",
+    setSerifPreset: (preset) => {
+        set({ serifPreset: preset ?? "georgia" });
+    },
     setColors: (overrides) => {
         set({ colorOverrides: overrides ?? {} });
     },
@@ -89,15 +93,15 @@ export const useThemeStore = create((set) => ({
         set({ hasLoadedTheme: true });
     }
 }));
-let stopSystemThemeListener = null;
+// The OS color-scheme listener is shared: one subscription however many
+// callers hold it, removed when the last holder releases. Each
+// `startSystemThemeListener()` call takes a hold and gets its own release.
+let systemThemeSubscription = null;
+let systemThemeHolds = 0;
 export function syncSystemTheme() {
     useThemeStore.getState().setSystemTheme(getSystemTheme());
 }
-export function startSystemThemeListener() {
-    if (stopSystemThemeListener) {
-        return stopSystemThemeListener;
-    }
-    syncSystemTheme();
+function subscribeToSystemTheme() {
     if (Platform.OS === "web" && typeof window !== "undefined" && typeof window.matchMedia === "function") {
         const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
         const onChange = () => {
@@ -105,48 +109,71 @@ export function startSystemThemeListener() {
         };
         if (typeof mediaQuery.addEventListener === "function") {
             mediaQuery.addEventListener("change", onChange);
-            stopSystemThemeListener = () => {
-                mediaQuery.removeEventListener("change", onChange);
-                stopSystemThemeListener = null;
-            };
-        }
-        else {
-            mediaQuery.addListener(onChange);
-            stopSystemThemeListener = () => {
-                mediaQuery.removeListener(onChange);
-                stopSystemThemeListener = null;
-            };
+            return { remove: () => mediaQuery.removeEventListener("change", onChange) };
         }
-        return stopSystemThemeListener;
+        mediaQuery.addListener(onChange);
+        return { remove: () => mediaQuery.removeListener(onChange) };
     }
-    const subscription = Appearance.addChangeListener(({ colorScheme }) => {
+    return Appearance.addChangeListener(({ colorScheme }) => {
         useThemeStore.getState().setSystemTheme(colorScheme === "dark" ? "dark" : "light");
     });
-    stopSystemThemeListener = () => {
-        subscription.remove();
-        stopSystemThemeListener = null;
+}
+/**
+ * Keep `systemTheme` following the OS color scheme (`prefers-color-scheme` on
+ * web, `Appearance` on native). The first holder reads the current scheme and
+ * attaches the one listener; later calls share it.
+ *
+ * Returns this caller's release: once every holder has released, the
+ * listener is removed. Calling a release again is a no-op, so an effect
+ * cleanup that runs twice can't drop another caller's hold. On native the
+ * package holds the listener for the app's lifetime (see the module-load
+ * init below), so an app's release never stops OS tracking there.
+ */
+export function startSystemThemeListener() {
+    systemThemeHolds += 1;
+    if (systemThemeHolds === 1) {
+        syncSystemTheme();
+        systemThemeSubscription = subscribeToSystemTheme();
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        systemThemeHolds -= 1;
+        if (systemThemeHolds === 0) {
+            systemThemeSubscription?.remove();
+            systemThemeSubscription = null;
+        }
     };
-    return stopSystemThemeListener;
 }
-// Single entry point for host apps to populate the store from the
-// environment (persisted preference + OS color scheme listener). Safe to
-// call multiple times — `startSystemThemeListener` is idempotent — and
-// returns the unsubscribe so it can be used directly inside `useEffect`.
-//
-// The listener starts BEFORE `loadTheme()` on purpose: reading the real OS
-// scheme first means a `system` user resolves straight from the boot-default
-// "light" to their actual scheme in one commit.
+/**
+ * Single entry point for host apps to populate the store from the
+ * environment: the OS color-scheme listener plus the persisted preference.
+ *
+ * Web apps call it once, from a top-level `useEffect` (never during render or
+ * at module scope — see below), and return its result as the cleanup:
+ * `useEffect(() => syncThemeFromEnvironment(), [])`. Safe to call more than
+ * once (StrictMode's double effects, two roots): every call shares the one
+ * OS listener, re-reads the persisted preference, and returns its own
+ * cleanup, which releases only that call's hold on the listener.
+ *
+ * The listener starts BEFORE `loadTheme()` on purpose: reading the real OS
+ * scheme first means a `system` user resolves straight from the boot-default
+ * "light" to their actual scheme in one commit.
+ */
 export function syncThemeFromEnvironment() {
-    const stop = startSystemThemeListener();
+    const release = startSystemThemeListener();
     useThemeStore.getState().loadTheme();
-    return stop;
+    return release;
 }
 // Native can read persistence at module load, so keep the historical
-// auto-init behavior there. On web the host app must call
-// `syncThemeFromEnvironment()` from a top-level `useEffect`: web bundles are
-// also evaluated in Node when `expo export` renders the HTML shell, where
-// `window`/`localStorage` don't exist, and reading them during the browser's
-// first render would disagree with the markup being hydrated.
+// auto-init behavior there, with a hold on the OS listener that is never
+// released. On web the host app must call `syncThemeFromEnvironment()` from a
+// top-level `useEffect`: web bundles are also evaluated in Node when
+// `expo export` renders the HTML shell, where `window`/`localStorage` don't
+// exist, and reading them during the browser's first render would disagree
+// with the markup being hydrated.
 if (Platform.OS !== "web") {
     useThemeStore.getState().loadTheme();
     startSystemThemeListener();

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.1",
+  "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"
   }
 }