pixelize-native-library 1.0.6

package/lib/module/theme/MODULE.md

@@ -0,0 +1,87 @@
+# theme
+
+The runtime theme layer: the provider that resolves a (brand, mode) into concrete values, and the
+hooks components read. It sits on top of three siblings — `tokens/` (the copy-paste zone),
+`tokens/roles/` (`roleColors`), and `platform/` (native-only rendering).
+
+**`provider/` is NOT the copy-paste zone.** It imports from `react`, `react-native` (via `platform/`),
+and holds React state — none of which may appear in `tokens/`. It mirrors web's `Theme/provider/`
+in *shape and export names* (`PixelizeProvider`, `useThemeMode`), not byte-for-byte.
+
+## Public surface (`pixelize-native-library/theme`)
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `PixelizeProvider` | component | Wrap the app root once. |
+| `useTheme()` | hook | Full resolved `Theme` (colours + scale + rendered elevation/fonts). |
+| `useThemeColors()` | hook | `RoleColors` — resolved value strings. **The RN escape hatch.** |
+| `useThemeMode()` | hook | `{ mode, resolvedMode, setMode, brand, setBrand }` for a switcher. |
+| `createAsyncStorageAdapter(AsyncStorage)` | fn | Wrap the app's AsyncStorage into the storage adapter. |
+| `themeNames`, `DEFAULT_THEME` | data | Brand catalogue for a picker (9 brands — roster + how to add one: `tokens/MODULE.md`). |
+| `Theme`, `ThemeMode`, `ThemeModeValue`, `PixelizeProviderProps`, `RoleColors`, `ThemeName`, `ColorScheme`, `ColorModeStorageAdapter` | types | Annotation. |
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { PixelizeProvider, createAsyncStorageAdapter } from 'pixelize-native-library/theme';
+
+<PixelizeProvider brand="zinc" mode="system" storage={createAsyncStorageAdapter(AsyncStorage)}>
+  <App />
+</PixelizeProvider>;
+```
+
+## Props
+
+- `brand?` — INITIAL brand; a persisted user choice wins over it. Default `zinc`. Still tracks a
+  changing prop value the same as before **until** `setBrand` is called once — after that the
+  provider owns it, matching `mode`'s "explicit choice wins" rule (kept for the pre-existing
+  fully-controlled-prop call sites; new code should prefer `setBrand`).
+- `mode?` — INITIAL mode; a persisted user choice wins over it. Default `system`.
+- `storage?` — persistence adapter; absent → in-memory + a dev warning (see below). Shared by both
+  `mode` and `brand`, under separate keys (`storageKey` / `brandStorageKey`).
+- `interLoaded?` — has the app registered Inter (`useFonts`)? Default `false` → system font, which
+  always renders. Pass `interLoaded={fontsLoaded}` so `theme.fontStyleForWeight` uses Inter faces.
+
+## Key behaviours
+
+### `system` is the default and reacts live
+`resolvedMode` derives from the OS via `platform/subscribeToSystemColorMode`, so a sunrise/sunset or
+`Appearance.setColorScheme()` flips a `system` app immediately. A pinned `light`/`dark` ignores it.
+
+### Persistence is optional, and degrades — never crashes
+AsyncStorage is an optional peer this library never imports; the consumer passes their instance to
+`createAsyncStorageAdapter`. With no adapter, mode and brand are each kept in a process-lifetime
+memory map (survives a remount, not a cold restart) and a one-time dev `console.warn` explains how
+to persist. The mount rehydrate is async and guarded per field (separate `userTouched` refs for
+mode and brand): a late read never clobbers a choice the user already made, because `setMode`/
+`setBrand` write on the action itself rather than in an effect.
+
+### `useThemeColors()` — the escape hatch that matters on RN
+Returns `RoleColors` as plain strings. `placeholderTextColor`, `android_ripple`, SVG `fill`, React
+Navigation chrome and the splash background accept no token object and no style prop — they need a
+resolved value. One source for every colour site is what deletes an app's `navColors.ts` and makes
+its whole icon/chrome surface adapt to dark mode.
+
+### Why two contexts
+`ThemeContext` (heavy resolved `Theme`) is split from `ThemeModeContext` (the small mode triple).
+Both provider values are memoised on their real inputs, so a mode flip recomputes the theme **once**
+and re-renders each consumer once, and an OS change while the mode is pinned re-renders **nobody**
+(both values stay reference-stable). A `useThemeMode()` reader is never invalidated by unrelated
+theme-object churn, nor a `useTheme()` reader by mode-control churn.
+
+### Elevation is rendered once
+Elevation tokens carry no colour-mode variation, so the five levels are rendered to RN shadow props
+at module load and shared by every theme (`theme.elevation.md`), not recomputed per brand/mode.
+Rendering is platform-specific (`ios` / `web` / `default` for Android) — see
+`src/theme/platform/MODULE.md` for the shape of each branch and why `web` needs its own case.
+
+## Known gaps
+- `useThemeMode()` exposes no `toggle`; a switcher does `setMode(resolvedMode === 'dark' ? 'light' : 'dark')`.
+
+**2026-07-18 — brand now persists, matching web.** Web's `PixelizeThemeProvider` always persisted
+both `mode` and `brand`; this provider only persisted `mode`, so a mobile brand switcher lost its
+choice on every cold restart. Added `setBrand`/`brand` to `useThemeMode()`'s return value and a
+second persisted-state slot (`brandStorageKey`, default `pixelize-native-library.brand`) alongside
+mode's — same adapter, separate key, so a plain-string storage slot never has to encode two values.
+Brand's existing fully-controlled-prop behavior (reactive to a changing `brand` prop, tested since
+before persistence existed) is preserved on top rather than replaced — see the `brand?` prop note
+above.

package/lib/module/theme/index.js

@@ -0,0 +1,15 @@
+"use strict";
+
+/**
+ * The `pixelize-native-library/theme` public surface — the provider, the three hooks, and the theme-side
+ * types a consumer annotates with. Design tokens themselves ship under `pixelize-native-library/tokens`;
+ * this subpath is intentionally the small, runtime-facing layer an app wires once at its root.
+ */
+
+export { PixelizeProvider, useTheme, useThemeColors, useThemeMode, createAsyncStorageAdapter } from "./provider/index.js";
+
+// Resolved-colour types, for annotating a value pulled from `useThemeColors()`.
+
+// The brand catalogue, for building a theme picker.
+export { themeNames, DEFAULT_THEME } from "./tokens/brands/index.js";
+//# sourceMappingURL=index.js.map

package/lib/module/theme/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["PixelizeProvider","useTheme","useThemeColors","useThemeMode","createAsyncStorageAdapter","themeNames","DEFAULT_THEME"],"sourceRoot":"../../../src","sources":["theme/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;;AAEA,SACEA,gBAAgB,EAChBC,QAAQ,EACRC,cAAc,EACdC,YAAY,EACZC,yBAAyB,QACpB,qBAAY;;AAUnB;;AAIA;AACA,SAASC,UAAU,EAAEC,aAAa,QAAQ,0BAAiB","ignoreList":[]}

package/lib/module/theme/platform/MODULE.md

@@ -0,0 +1,102 @@
+# theme/platform
+
+Native implementations of everything the theme needs that a token file cannot hold — units,
+shadows, font faces, and the system colour scheme.
+
+**Never copied.** Web's `Theme/platform/` mirror exports the **same names** over CSS/DOM, which is
+what makes the theme provider and module styles copy-pasteable between the repos. Renaming an
+export here without renaming it there silently breaks that contract — the two files never import
+each other, so nothing fails until a paste does.
+
+This is also the reason `tokens/` stays unitless: `hairline` and Inter's face names are runtime
+platform values, so the token says `1` / `600` and this layer resolves it.
+
+## Exports (`platform/index.ts`)
+
+| Export | Type | Notes |
+|---|---|---|
+| `rem(n)` | `number` | Identity — RN lengths are already DP. Web returns `n/16 + 'rem'`. |
+| `hairline` | `number` | `StyleSheet.hairlineWidth` — density-dependent, resolved at runtime. |
+| `elevation(token)` | `ElevationStyle` | `ElevationToken` → RN shadow style props. |
+| `interFontFamilies` | `Record<FontWeightValue, string>` | Weight value (`'400'`…`'700'`) → Inter face name. |
+| `systemFontFamily` | `string` | `System` (iOS) / `sans-serif` (Android). |
+| `fontStyleForWeight(weight, interLoaded?)` | `FontStyleForWeight` | Weight value → `{fontFamily}` or system fallback. |
+| `getSystemColorMode()` | `'light' \| 'dark'` | |
+| `subscribeToSystemColorMode(cb)` | `() => void` | Returns an unsubscribe fn. |
+
+Types: `ElevationStyle`, `FontWeightValue` (`= (typeof fontWeights)[keyof typeof fontWeights]`),
+`FontStyleForWeight`, `ColorMode`.
+
+## Key behaviours
+
+### Elevation uses the legacy shadow props, not `boxShadow`
+
+`boxShadow` is **New-Architecture-only**. Our peer range (RN >= 0.79) still allows
+`newArchEnabled=false`, where `boxShadow` renders **nothing**. The legacy props map straight to the
+platform APIs and are not deprecated, so they are the only both-arch path. Revisit only when the
+peer floor is new-arch-only — `boxShadow` is strictly more capable (it is the only way to get
+spread).
+
+Per-platform, deliberately — **three** explicit `Platform.select` branches (`ios`, `web`,
+`default` for Android). `web` must stay its own key: without one, `react-native-web` falls through
+to `default` (the Android shape), whose only meaningful field — `elevation` — RNW silently ignores
+(Android-only prop), so the shadow rendered as nothing at all. This shipped as a real bug once;
+`platform/__tests__/elevation.test.ts` now pins all three shapes so it can't silently regress.
+
+- **iOS** — `shadowColor` + `shadowOffset` + `shadowOpacity: 1` + `shadowRadius: blur / 2`.
+  - `blur / 2` because iOS renders a given `shadowRadius` heavier than the same CSS blur; an
+    unhalved radius reads darker and wider than the web token this mirrors.
+  - `shadowOpacity: 1` is not "fully opaque": iOS **multiplies** it by the colour's alpha, so `1`
+    lets `#rrggbbaa` carry translucency alone — one colour value, correct on both platforms. Also
+    note the prop **defaults to 0** (no shadow), so it must always be set.
+  - `shadowOffset` is always explicit because iOS defaults it to `(0, -3)`, not `(0, 0)`.
+- **Web** — same shape as iOS (`shadowColor` + `shadowOffset` + `shadowOpacity: 1` +
+  `shadowRadius`), but **unhalved**: the iOS halving corrects an iOS-only rendering quirk, and the
+  token's `blur` already IS the original web/CSS value (see `tokens/primitives/elevation.ts`'s doc
+  comment), so it passes straight through. `react-native-web`'s style preprocessor converts these
+  legacy shadow props into a real CSS `box-shadow` — confirmed empirically via
+  `react-native-web/dist/cjs/exports/StyleSheet/preprocess`.
+- **Android** — `elevation` + `shadowColor` only. Android ignores offset/opacity/radius, and tints
+  from `shadowColor` only on **API 28+** (below that the shadow is the platform default black).
+  A view also needs a **background colour** for `elevation` to cast anything.
+
+**`spread` is dropped.** Neither platform exposes it through style props (RN implements it by
+insetting a custom shadowPath). Keep mobile elevation tokens at `spread: 0` — a non-zero spread
+renders on web and not here.
+
+### Fonts are keyed by the weight value, and Inter is the app's job
+
+The map is keyed by the **weight value** (`'400'`…`'700'`), not the token name (`regular`/`medium`/
+`semibold`/`bold`). The value is what a copied web call passes (`fontStyleForWeight(fontWeights.semibold)`)
+and what RN's `fontWeight` fallback needs verbatim, so one input drives both the family lookup and the
+fallback. `FontWeightValue` is **derived from the token** (`(typeof fontWeights)[keyof typeof fontWeights]`),
+so adding a weight to `fontWeights` fails the `satisfies Record<FontWeightValue, string>` until a face is
+registered here — the map can never silently miss a weight.
+
+With Inter loaded, `fontStyleForWeight` returns **`fontFamily` only** — the face is already the
+target weight, and adding `fontWeight` makes Android synthesise a faux-bold on top of it. The
+system fallback inverts this: one family, so `fontWeight` carries the weight.
+
+`interLoaded` is passed in (from the theme provider) rather than detected — without expo-font there
+is no way to ask whether a family registered, and an unregistered family degrades inconsistently
+(silent fallback on Android, warnings on iOS).
+
+**Consumer requirement:** the app registers the faces itself; this library takes **no font
+dependency**. The `interFontFamilies` values are the exact keys expected:
+
+```ts
+useFonts({ 'Inter-Regular': require('…'), 'Inter-SemiBold': require('…') /* … */ });
+```
+
+### Colour scheme
+
+`Appearance.getColorScheme()` is nullable (`null` when the native Appearance module is unavailable)
+and on RN 0.85+ can also report `'unspecified'`. Since the peer floor (`>=0.79`) spans both, the
+getter and listener test `=== 'dark'` and floor everything else to `'light'`, mirroring web's
+matchMedia which only asks "is it dark?". Read it per render, never cache: it changes at
+sunrise/sunset and via `Appearance.setColorScheme()`.
+
+## Known gaps
+
+- `spread` unsupported (above).
+- Android shadow tint requires API 28+; below that colour is ignored by the platform.

package/lib/module/theme/platform/colorScheme.native.js

@@ -0,0 +1,24 @@
+"use strict";
+
+import { Appearance } from 'react-native';
+/**
+ * `Appearance.getColorScheme()` is nullable — `null` when the native Appearance module is
+ * unavailable — and on RN 0.85+ can also report `'unspecified'`. Our peer floor spans both, so
+ * anything that isn't explicitly `'dark'` floors to light, mirroring web's matchMedia which only
+ * ever asks "is it dark?". Read it per render, never cache: it changes at sunrise/sunset and on
+ * `Appearance.setColorScheme()`.
+ */
+export function getSystemColorMode() {
+  return Appearance.getColorScheme() === 'dark' ? 'dark' : 'light';
+}
+
+/** Returns an unsubscribe fn. */
+export function subscribeToSystemColorMode(callback) {
+  const subscription = Appearance.addChangeListener(({
+    colorScheme
+  }) => {
+    callback(colorScheme === 'dark' ? 'dark' : 'light');
+  });
+  return () => subscription.remove();
+}
+//# sourceMappingURL=colorScheme.native.js.map

package/lib/module/theme/platform/colorScheme.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Appearance","getSystemColorMode","getColorScheme","subscribeToSystemColorMode","callback","subscription","addChangeListener","colorScheme","remove"],"sourceRoot":"../../../../src","sources":["theme/platform/colorScheme.native.ts"],"mappings":";;AAAA,SAASA,UAAU,QAAQ,cAAc;AAIzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAAA,EAAc;EAC9C,OAAOD,UAAU,CAACE,cAAc,CAAC,CAAC,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO;AAClE;;AAEA;AACA,OAAO,SAASC,0BAA0BA,CACxCC,QAAmC,EACvB;EACZ,MAAMC,YAAY,GAAGL,UAAU,CAACM,iBAAiB,CAAC,CAAC;IAAEC;EAAY,CAAC,KAAK;IACrEH,QAAQ,CAACG,WAAW,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;EACrD,CAAC,CAAC;EACF,OAAO,MAAMF,YAAY,CAACG,MAAM,CAAC,CAAC;AACpC","ignoreList":[]}

package/lib/module/theme/platform/elevation.native.js

@@ -0,0 +1,75 @@
+"use strict";
+
+import { Platform } from 'react-native';
+
+/**
+ * The style props an elevation resolves to. A `Pick` rather than `ViewStyle` so a future RN
+ * shadow prop cannot silently widen what this function is allowed to emit.
+ */
+
+/**
+ * Resolve an elevation token to RN style props.
+ *
+ * Uses the legacy shadow props over `boxShadow` because `boxShadow` is New-Architecture-only, and
+ * our peer range (RN >= 0.79) still lets a consumer ship `newArchEnabled=false` — on which
+ * `boxShadow` renders nothing at all. The legacy props map straight to the platform APIs and are
+ * not deprecated, so they are the only path that works on both architectures. react-native-web's
+ * style preprocessor converts these same legacy props into a real CSS `box-shadow`, so the `web`
+ * branch below rides that conversion rather than emitting `boxShadow` itself.
+ *
+ * An elevation token is a STACK of layers (web needs both an ambient and a contact shadow per
+ * step), but legacy RN shadow props can only express one. This renders `layers[0]` — the dominant
+ * layer — and drops the rest. That is an honest limit of the legacy path, not a token compromise:
+ * a future `boxShadow`-only resolver (new-arch-only consumers) can render every layer.
+ *
+ * `layer.spread` is dropped — neither legacy platform API exposes it (RN implements it by
+ * insetting a custom shadowPath). The ramp's `md`/`lg` carry a negative spread to tighten the
+ * shadow on web, so those two steps read marginally wider here. Accepted: honouring it would mean
+ * hand-drawing a shadow layer per view.
+ *
+ * Returns one of three shapes: `ios`, `android` (RN's `default` branch — Android reads the numeric
+ * `elevation` prop and ignores offset/opacity/radius), and `web`. `web` MUST stay its own explicit
+ * key: without it, react-native-web falls through to `default` (the Android shape), whose only
+ * meaningful field — `elevation` — react-native-web silently ignores (it is Android-only), so the
+ * shadow renders as nothing at all.
+ */
+export function elevation(token) {
+  const layer = token.layers[0];
+  return Platform.select({
+    ios: {
+      shadowColor: layer.color,
+      // Always explicit: iOS defaults shadowOffset to (0, -3), not (0, 0).
+      shadowOffset: {
+        width: layer.x,
+        height: layer.y
+      },
+      // iOS multiplies shadowOpacity by the colour's own alpha, so 1 lets #rrggbbaa carry the
+      // translucency by itself — and keeps one colour value correct on both platforms.
+      shadowOpacity: 1,
+      // Halved because iOS renders a given shadowRadius heavier than the same CSS blur, so an
+      // unhalved radius reads darker and wider than the web token this mirrors.
+      shadowRadius: layer.blur / 2
+    },
+    // Same legacy shadow-prop shape as iOS, but WITHOUT the halving above: that halving corrects
+    // for iOS rendering a given shadowRadius heavier than the same CSS blur, which is an iOS
+    // quirk, not a web one. The token's `blur` already IS the original web/CSS value (see
+    // `elevation.ts`'s doc comment), so it passes straight through as `shadowRadius` and
+    // react-native-web's preprocessor turns the whole set into a real CSS `box-shadow`.
+    web: {
+      shadowColor: layer.color,
+      shadowOffset: {
+        width: layer.x,
+        height: layer.y
+      },
+      shadowOpacity: 1,
+      shadowRadius: layer.blur
+    },
+    // Android draws the shadow from `elevation` alone; it ignores offset/opacity/radius and tints
+    // with shadowColor only on API 28+. Below that the shadow is the platform's default black.
+    default: {
+      shadowColor: layer.color,
+      elevation: token.android
+    }
+  });
+}
+//# sourceMappingURL=elevation.native.js.map

package/lib/module/theme/platform/elevation.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Platform","elevation","token","layer","layers","select","ios","shadowColor","color","shadowOffset","width","x","height","y","shadowOpacity","shadowRadius","blur","web","default","android"],"sourceRoot":"../../../../src","sources":["theme/platform/elevation.native.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;;AAIvC;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,SAASA,CAACC,KAAqB,EAAkB;EAC/D,MAAMC,KAAK,GAAGD,KAAK,CAACE,MAAM,CAAC,CAAC,CAAC;EAC7B,OAAOJ,QAAQ,CAACK,MAAM,CAAiB;IACrCC,GAAG,EAAE;MACHC,WAAW,EAAEJ,KAAK,CAACK,KAAK;MACxB;MACAC,YAAY,EAAE;QAAEC,KAAK,EAAEP,KAAK,CAACQ,CAAC;QAAEC,MAAM,EAAET,KAAK,CAACU;MAAE,CAAC;MACjD;MACA;MACAC,aAAa,EAAE,CAAC;MAChB;MACA;MACAC,YAAY,EAAEZ,KAAK,CAACa,IAAI,GAAG;IAC7B,CAAC;IACD;IACA;IACA;IACA;IACA;IACAC,GAAG,EAAE;MACHV,WAAW,EAAEJ,KAAK,CAACK,KAAK;MACxBC,YAAY,EAAE;QAAEC,KAAK,EAAEP,KAAK,CAACQ,CAAC;QAAEC,MAAM,EAAET,KAAK,CAACU;MAAE,CAAC;MACjDC,aAAa,EAAE,CAAC;MAChBC,YAAY,EAAEZ,KAAK,CAACa;IACtB,CAAC;IACD;IACA;IACAE,OAAO,EAAE;MACPX,WAAW,EAAEJ,KAAK,CAACK,KAAK;MACxBP,SAAS,EAAEC,KAAK,CAACiB;IACnB;EACF,CAAC,CAAC;AACJ","ignoreList":[]}

package/lib/module/theme/platform/fonts.native.js

@@ -0,0 +1,58 @@
+"use strict";
+
+import { Platform } from 'react-native';
+
+/**
+ * The weight VALUES the `fontWeights` tokens resolve to ('400'…'700') — which is exactly RN's own
+ * `fontWeight` string domain. Derived from the token so adding a weight there fails the `satisfies`
+ * below until a matching face is registered here.
+ */
+
+/** The style a weight resolves to. Never both keys at once — see `fontStyleForWeight`. */
+
+/**
+ * Keyed by the weight VALUE, not the token name, because the value is what a copied web call passes
+ * (`fontStyleForWeight(fontWeights.semibold)`) and what the `fontWeight` fallback below needs
+ * verbatim — one input serves the family lookup and the fallback.
+ *
+ * The values are the family names the consumer app registers with expo-font. Loading Inter is the
+ * app's job; this library takes no font dependency:
+ *   useFonts({ 'Inter-Regular': require('…'), 'Inter-SemiBold': require('…'), … })
+ */
+export const interFontFamilies = {
+  '400': 'Inter-Regular',
+  '500': 'Inter-Medium',
+  '600': 'Inter-SemiBold',
+  '700': 'Inter-Bold'
+};
+
+/** The platform's own UI font, used when the app has not registered Inter. */
+export const systemFontFamily = Platform.select({
+  ios: 'System',
+  default: 'sans-serif'
+});
+
+/**
+ * Resolve a weight to a text style.
+ *
+ * With Inter loaded this returns `fontFamily` ONLY, deliberately omitting `fontWeight`: each Inter
+ * face already carries its weight, and pairing a weighted face with `fontWeight` makes Android
+ * synthesise a faux-bold on top of it. The system fallback is the reverse — one family, so the
+ * weight has to be carried by `fontWeight` (the token value is already the string RN expects).
+ *
+ * `interLoaded` is passed in from the theme provider, not detected: without expo-font there is no
+ * way to ask whether a family registered, and an unregistered family degrades inconsistently
+ * (silent fallback on Android, a warning on iOS).
+ */
+export function fontStyleForWeight(weight, interLoaded = true) {
+  if (!interLoaded) {
+    return {
+      fontFamily: systemFontFamily,
+      fontWeight: weight
+    };
+  }
+  return {
+    fontFamily: interFontFamilies[weight]
+  };
+}
+//# sourceMappingURL=fonts.native.js.map

package/lib/module/theme/platform/fonts.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Platform","interFontFamilies","systemFontFamily","select","ios","default","fontStyleForWeight","weight","interLoaded","fontFamily","fontWeight"],"sourceRoot":"../../../../src","sources":["theme/platform/fonts.native.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;;AAIvC;AACA;AACA;AACA;AACA;;AAGA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAG;EAC/B,KAAK,EAAE,eAAe;EACtB,KAAK,EAAE,cAAc;EACrB,KAAK,EAAE,gBAAgB;EACvB,KAAK,EAAE;AACT,CAAoD;;AAEpD;AACA,OAAO,MAAMC,gBAAwB,GAAGF,QAAQ,CAACG,MAAM,CAAC;EACtDC,GAAG,EAAE,QAAQ;EACbC,OAAO,EAAE;AACX,CAAC,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAChCC,MAAuB,EACvBC,WAAW,GAAG,IAAI,EACE;EACpB,IAAI,CAACA,WAAW,EAAE;IAChB,OAAO;MAAEC,UAAU,EAAEP,gBAAgB;MAAEQ,UAAU,EAAEH;IAAO,CAAC;EAC7D;EACA,OAAO;IAAEE,UAAU,EAAER,iBAAiB,CAACM,MAAM;EAAE,CAAC;AAClD","ignoreList":[]}

package/lib/module/theme/platform/index.js

@@ -0,0 +1,14 @@
+"use strict";
+
+/**
+ * The platform seam. Web's mirror exports these same names over CSS/DOM, which is what lets the
+ * theme provider and every module's styles be copy-pasted between the repos unchanged.
+ *
+ * Imports are `.native`-suffixed on purpose: this package ships native only, so there is no `.ts`
+ * sibling for a bundler to choose between and nothing to resolve implicitly.
+ */
+export { rem, hairline } from "./units.native.js";
+export { elevation } from "./elevation.native.js";
+export { interFontFamilies, systemFontFamily, fontStyleForWeight } from "./fonts.native.js";
+export { getSystemColorMode, subscribeToSystemColorMode } from "./colorScheme.native.js";
+//# sourceMappingURL=index.js.map

package/lib/module/theme/platform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["rem","hairline","elevation","interFontFamilies","systemFontFamily","fontStyleForWeight","getSystemColorMode","subscribeToSystemColorMode"],"sourceRoot":"../../../../src","sources":["theme/platform/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,GAAG,EAAEC,QAAQ,QAAQ,mBAAgB;AAC9C,SAASC,SAAS,QAAQ,uBAAoB;AAE9C,SAASC,iBAAiB,EAAEC,gBAAgB,EAAEC,kBAAkB,QAAQ,mBAAgB;AAExF,SAASC,kBAAkB,EAAEC,0BAA0B,QAAQ,yBAAsB","ignoreList":[]}

package/lib/module/theme/platform/units.native.js

@@ -0,0 +1,18 @@
+"use strict";
+
+import { StyleSheet } from 'react-native';
+
+/**
+ * Identity on native: RN lengths are already density-independent pixels.
+ * It exists so theme code copied from web — which calls `rem(space[4])` — compiles unchanged
+ * here, where the web mirror returns `n / 16 + 'rem'`.
+ */
+export const rem = n => n;
+
+/**
+ * The thinnest crisp line on this device, resolved at runtime from screen density.
+ * This is why `borderWidths` tokens stay plain numbers: a density-dependent value cannot live in
+ * the copy-paste zone, so the token says `1` and a border that wants a hairline reaches for this.
+ */
+export const hairline = StyleSheet.hairlineWidth;
+//# sourceMappingURL=units.native.js.map

package/lib/module/theme/platform/units.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["StyleSheet","rem","n","hairline","hairlineWidth"],"sourceRoot":"../../../../src","sources":["theme/platform/units.native.ts"],"mappings":";;AAAA,SAASA,UAAU,QAAQ,cAAc;;AAEzC;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,GAAG,GAAIC,CAAS,IAAaA,CAAC;;AAE3C;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,QAAgB,GAAGH,UAAU,CAACI,aAAa","ignoreList":[]}

package/lib/module/theme/provider/PixelizeProvider.js

@@ -0,0 +1,149 @@
+"use strict";
+
+import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, palettes, roleColors, DEFAULT_THEME } from "../tokens/index.js";
+import { elevation as renderElevation, fontStyleForWeight, getSystemColorMode, subscribeToSystemColorMode } from "../platform/index.js";
+import { DEFAULT_BRAND_STORAGE_NAMESPACE, DEFAULT_STORAGE_NAMESPACE, isThemeMode, isThemeName, memoryStorageAdapter } from "./colorModeStorage.js";
+
+// A local declaration of RN's build-time global, so this file typechecks without depending on the
+// react-native ambient types being loaded. In a module scope it shadows nothing; RN replaces it.
+
+/**
+ * The fully resolved theme for one (brand, resolvedMode): role colours resolved to plain strings,
+ * the unitless numeric scale, and the platform-rendered pieces a token cannot hold (RN shadow props,
+ * a font-style resolver). This is what `useTheme()` returns; component modules read it, never the
+ * raw palette directly.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+const DEFAULT_MODE = 'system';
+
+// Elevation carries no colour-mode variation at the token layer, so every theme shares one rendered
+// map instead of recomputing five shadow styles per brand/mode.
+const RENDERED_ELEVATION = {
+  none: renderElevation(elevationTokens.none),
+  sm: renderElevation(elevationTokens.sm),
+  base: renderElevation(elevationTokens.base),
+  md: renderElevation(elevationTokens.md),
+  lg: renderElevation(elevationTokens.lg)
+};
+function buildTheme(brand, mode, interLoaded) {
+  const palette = palettes[brand][mode];
+  return {
+    brand,
+    mode,
+    colors: roleColors(palette),
+    palette,
+    space,
+    radii,
+    fontSizes,
+    fontWeights,
+    lineHeights,
+    letterSpacings,
+    borderWidths,
+    breakpoints,
+    zIndices,
+    elevation: RENDERED_ELEVATION,
+    fontStyleForWeight: weight => fontStyleForWeight(weight, interLoaded)
+  };
+}
+
+/**
+ * Two contexts, on purpose. `ThemeContext` holds the heavy resolved `Theme`; `ThemeModeContext` holds
+ * the small mode-control triple. Both provider values are memoised on their true inputs, so:
+ *  - a mode flip recomputes the theme exactly ONCE and re-renders each consumer once, and
+ *  - an OS colour change while the mode is pinned (`resolvedMode` unchanged) keeps BOTH values
+ *    reference-stable, so it re-renders nobody.
+ * Splitting also means a `useThemeMode()` reader isn't invalidated by unrelated theme-object churn
+ * and vice versa.
+ */
+export const ThemeContext = /*#__PURE__*/createContext(undefined);
+export const ThemeModeContext = /*#__PURE__*/createContext(undefined);
+export function PixelizeProvider({
+  children,
+  brand: brandProp = DEFAULT_THEME,
+  mode = DEFAULT_MODE,
+  storage: storageProp,
+  storageKey = DEFAULT_STORAGE_NAMESPACE,
+  brandStorageKey = DEFAULT_BRAND_STORAGE_NAMESPACE,
+  interLoaded = false
+}) {
+  const storage = storageProp ?? memoryStorageAdapter;
+  const [modeState, setModeState] = useState(mode);
+  const [brandState, setBrandState] = useState(brandProp);
+  // Read the real OS value immediately — native has no hydration step to stay deterministic for.
+  const [systemMode, setSystemMode] = useState(getSystemColorMode);
+
+  // Once the user has chosen, a late async rehydrate must not clobber that fresh choice. Brand
+  // gets its own ref: touching one must never block the other's rehydrate.
+  const userTouched = useRef(false);
+  const userTouchedBrand = useRef(false);
+  useEffect(() => subscribeToSystemColorMode(setSystemMode), []);
+
+  // `mode` is intentionally initial-only (a controlled screen drives it through `setMode`, never
+  // by re-passing a prop), but `brand` already shipped as a fully-controlled prop before this
+  // provider owned any brand state — existing call sites (this repo's own example app included)
+  // re-render with a new `brand` value and expect the theme to follow. This keeps that contract
+  // alive on top of the new persisted/`setBrand` state: an unrelenting `brandProp` still drives
+  // `brandState`, but the moment `setBrand` is called even once, the provider is considered the
+  // owner and further `brandProp` changes are ignored — the same "explicit choice wins" rule
+  // `storage` rehydration already follows below.
+  useEffect(() => {
+    if (userTouchedBrand.current) return;
+    setBrandState(brandProp);
+  }, [brandProp]);
+  useEffect(() => {
+    if (storageProp) return;
+    if (typeof __DEV__ !== 'undefined' && !__DEV__) return;
+    console.warn('[pixelize-native-library] <PixelizeProvider> has no `storage` adapter, so the theme choice is ' + 'kept in memory and lost on app restart. Pass ' + 'storage={createAsyncStorageAdapter(AsyncStorage)} to persist it.');
+  }, [storageProp]);
+  useEffect(() => {
+    let cancelled = false;
+    Promise.resolve(storage.getItem(storageKey)).then(raw => {
+      if (cancelled || userTouched.current) return;
+      if (isThemeMode(raw)) setModeState(raw);
+    }).catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, storageKey]);
+  useEffect(() => {
+    let cancelled = false;
+    Promise.resolve(storage.getItem(brandStorageKey)).then(raw => {
+      if (cancelled || userTouchedBrand.current) return;
+      if (isThemeName(raw)) setBrandState(raw);
+    }).catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, brandStorageKey]);
+
+  // Write on the explicit action, not in an effect: it only ever persists a real user choice, so a
+  // mount default can't be written over the stored value before the rehydrate above has applied it.
+  const setMode = useCallback(next => {
+    userTouched.current = true;
+    setModeState(next);
+    Promise.resolve(storage.setItem(storageKey, next)).catch(() => {});
+  }, [storage, storageKey]);
+  const setBrand = useCallback(next => {
+    userTouchedBrand.current = true;
+    setBrandState(next);
+    Promise.resolve(storage.setItem(brandStorageKey, next)).catch(() => {});
+  }, [storage, brandStorageKey]);
+  const resolvedMode = modeState === 'system' ? systemMode : modeState;
+  const theme = useMemo(() => buildTheme(brandState, resolvedMode, interLoaded), [brandState, resolvedMode, interLoaded]);
+  const modeValue = useMemo(() => ({
+    mode: modeState,
+    resolvedMode,
+    setMode,
+    brand: brandState,
+    setBrand
+  }), [modeState, resolvedMode, setMode, brandState, setBrand]);
+  return /*#__PURE__*/_jsx(ThemeContext.Provider, {
+    value: theme,
+    children: /*#__PURE__*/_jsx(ThemeModeContext.Provider, {
+      value: modeValue,
+      children: children
+    })
+  });
+}
+//# sourceMappingURL=PixelizeProvider.js.map

package/lib/module/theme/provider/PixelizeProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createContext","useCallback","useEffect","useMemo","useRef","useState","space","radii","fontSizes","fontWeights","lineHeights","letterSpacings","borderWidths","breakpoints","zIndices","elevation","elevationTokens","palettes","roleColors","DEFAULT_THEME","renderElevation","fontStyleForWeight","getSystemColorMode","subscribeToSystemColorMode","DEFAULT_BRAND_STORAGE_NAMESPACE","DEFAULT_STORAGE_NAMESPACE","isThemeMode","isThemeName","memoryStorageAdapter","jsx","_jsx","DEFAULT_MODE","RENDERED_ELEVATION","none","sm","base","md","lg","buildTheme","brand","mode","interLoaded","palette","colors","weight","ThemeContext","undefined","ThemeModeContext","PixelizeProvider","children","brandProp","storage","storageProp","storageKey","brandStorageKey","modeState","setModeState","brandState","setBrandState","systemMode","setSystemMode","userTouched","userTouchedBrand","current","__DEV__","console","warn","cancelled","Promise","resolve","getItem","then","raw","catch","setMode","next","setItem","setBrand","resolvedMode","theme","modeValue","Provider","value"],"sourceRoot":"../../../../src","sources":["theme/provider/PixelizeProvider.tsx"],"mappings":";;AAAA,SAASA,aAAa,EAAEC,WAAW,EAAEC,SAAS,EAAEC,OAAO,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,OAAO;AAGxF,SACEC,KAAK,EACLC,KAAK,EACLC,SAAS,EACTC,WAAW,EACXC,WAAW,EACXC,cAAc,EACdC,YAAY,EACZC,WAAW,EACXC,QAAQ,EACRC,SAAS,IAAIC,eAAe,EAC5BC,QAAQ,EACRC,UAAU,EACVC,aAAa,QACR,oBAAW;AASlB,SACEJ,SAAS,IAAIK,eAAe,EAC5BC,kBAAkB,EAClBC,kBAAkB,EAClBC,0BAA0B,QACrB,sBAAa;AAGpB,SACEC,+BAA+B,EAC/BC,yBAAyB,EACzBC,WAAW,EACXC,WAAW,EACXC,oBAAoB,QACf,uBAAoB;;AAG3B;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AALA,SAAAC,GAAA,IAAAC,IAAA;AAkEA,MAAMC,YAAuB,GAAG,QAAQ;;AAExC;AACA;AACA,MAAMC,kBAA0D,GAAG;EACjEC,IAAI,EAAEb,eAAe,CAACJ,eAAe,CAACiB,IAAI,CAAC;EAC3CC,EAAE,EAAEd,eAAe,CAACJ,eAAe,CAACkB,EAAE,CAAC;EACvCC,IAAI,EAAEf,eAAe,CAACJ,eAAe,CAACmB,IAAI,CAAC;EAC3CC,EAAE,EAAEhB,eAAe,CAACJ,eAAe,CAACoB,EAAE,CAAC;EACvCC,EAAE,EAAEjB,eAAe,CAACJ,eAAe,CAACqB,EAAE;AACxC,CAAC;AAED,SAASC,UAAUA,CAACC,KAAgB,EAAEC,IAAiB,EAAEC,WAAoB,EAAS;EACpF,MAAMC,OAAO,GAAGzB,QAAQ,CAACsB,KAAK,CAAC,CAACC,IAAI,CAAC;EACrC,OAAO;IACLD,KAAK;IACLC,IAAI;IACJG,MAAM,EAAEzB,UAAU,CAACwB,OAAO,CAAC;IAC3BA,OAAO;IACPpC,KAAK;IACLC,KAAK;IACLC,SAAS;IACTC,WAAW;IACXC,WAAW;IACXC,cAAc;IACdC,YAAY;IACZC,WAAW;IACXC,QAAQ;IACRC,SAAS,EAAEiB,kBAAkB;IAC7BX,kBAAkB,EAAGuB,MAAM,IAAKvB,kBAAkB,CAACuB,MAAM,EAAEH,WAAW;EACxE,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMI,YAAY,gBAAG7C,aAAa,CAAoB8C,SAAS,CAAC;AACvE,OAAO,MAAMC,gBAAgB,gBAAG/C,aAAa,CAA6B8C,SAAS,CAAC;AAEpF,OAAO,SAASE,gBAAgBA,CAAC;EAC/BC,QAAQ;EACRV,KAAK,EAAEW,SAAS,GAAG/B,aAAa;EAChCqB,IAAI,GAAGT,YAAY;EACnBoB,OAAO,EAAEC,WAAW;EACpBC,UAAU,GAAG5B,yBAAyB;EACtC6B,eAAe,GAAG9B,+BAA+B;EACjDiB,WAAW,GAAG;AACO,CAAC,EAAE;EACxB,MAAMU,OAAO,GAAGC,WAAW,IAAIxB,oBAAoB;EAEnD,MAAM,CAAC2B,SAAS,EAAEC,YAAY,CAAC,GAAGnD,QAAQ,CAAYmC,IAAI,CAAC;EAC3D,MAAM,CAACiB,UAAU,EAAEC,aAAa,CAAC,GAAGrD,QAAQ,CAAY6C,SAAS,CAAC;EAClE;EACA,MAAM,CAACS,UAAU,EAAEC,aAAa,CAAC,GAAGvD,QAAQ,CAAciB,kBAAkB,CAAC;;EAE7E;EACA;EACA,MAAMuC,WAAW,GAAGzD,MAAM,CAAC,KAAK,CAAC;EACjC,MAAM0D,gBAAgB,GAAG1D,MAAM,CAAC,KAAK,CAAC;EAEtCF,SAAS,CAAC,MAAMqB,0BAA0B,CAACqC,aAAa,CAAC,EAAE,EAAE,CAAC;;EAE9D;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA1D,SAAS,CAAC,MAAM;IACd,IAAI4D,gBAAgB,CAACC,OAAO,EAAE;IAC9BL,aAAa,CAACR,SAAS,CAAC;EAC1B,CAAC,EAAE,CAACA,SAAS,CAAC,CAAC;EAEfhD,SAAS,CAAC,MAAM;IACd,IAAIkD,WAAW,EAAE;IACjB,IAAI,OAAOY,OAAO,KAAK,WAAW,IAAI,CAACA,OAAO,EAAE;IAChDC,OAAO,CAACC,IAAI,CACV,gGAAgG,GAC9F,+CAA+C,GAC/C,kEACJ,CAAC;EACH,CAAC,EAAE,CAACd,WAAW,CAAC,CAAC;EAEjBlD,SAAS,CAAC,MAAM;IACd,IAAIiE,SAAS,GAAG,KAAK;IACrBC,OAAO,CAACC,OAAO,CAAClB,OAAO,CAACmB,OAAO,CAACjB,UAAU,CAAC,CAAC,CACzCkB,IAAI,CAAEC,GAAG,IAAK;MACb,IAAIL,SAAS,IAAIN,WAAW,CAACE,OAAO,EAAE;MACtC,IAAIrC,WAAW,CAAC8C,GAAG,CAAC,EAAEhB,YAAY,CAACgB,GAAG,CAAC;IACzC,CAAC,CAAC,CACDC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAClB,OAAO,MAAM;MACXN,SAAS,GAAG,IAAI;IAClB,CAAC;EACH,CAAC,EAAE,CAAChB,OAAO,EAAEE,UAAU,CAAC,CAAC;EAEzBnD,SAAS,CAAC,MAAM;IACd,IAAIiE,SAAS,GAAG,KAAK;IACrBC,OAAO,CAACC,OAAO,CAAClB,OAAO,CAACmB,OAAO,CAAChB,eAAe,CAAC,CAAC,CAC9CiB,IAAI,CAAEC,GAAG,IAAK;MACb,IAAIL,SAAS,IAAIL,gBAAgB,CAACC,OAAO,EAAE;MAC3C,IAAIpC,WAAW,CAAC6C,GAAG,CAAC,EAAEd,aAAa,CAACc,GAAG,CAAC;IAC1C,CAAC,CAAC,CACDC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAClB,OAAO,MAAM;MACXN,SAAS,GAAG,IAAI;IAClB,CAAC;EACH,CAAC,EAAE,CAAChB,OAAO,EAAEG,eAAe,CAAC,CAAC;;EAE9B;EACA;EACA,MAAMoB,OAAO,GAAGzE,WAAW,CACxB0E,IAAe,IAAK;IACnBd,WAAW,CAACE,OAAO,GAAG,IAAI;IAC1BP,YAAY,CAACmB,IAAI,CAAC;IAClBP,OAAO,CAACC,OAAO,CAAClB,OAAO,CAACyB,OAAO,CAACvB,UAAU,EAAEsB,IAAI,CAAC,CAAC,CAACF,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;EACpE,CAAC,EACD,CAACtB,OAAO,EAAEE,UAAU,CACtB,CAAC;EAED,MAAMwB,QAAQ,GAAG5E,WAAW,CACzB0E,IAAe,IAAK;IACnBb,gBAAgB,CAACC,OAAO,GAAG,IAAI;IAC/BL,aAAa,CAACiB,IAAI,CAAC;IACnBP,OAAO,CAACC,OAAO,CAAClB,OAAO,CAACyB,OAAO,CAACtB,eAAe,EAAEqB,IAAI,CAAC,CAAC,CAACF,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;EACzE,CAAC,EACD,CAACtB,OAAO,EAAEG,eAAe,CAC3B,CAAC;EAED,MAAMwB,YAAyB,GAAGvB,SAAS,KAAK,QAAQ,GAAGI,UAAU,GAAGJ,SAAS;EAEjF,MAAMwB,KAAK,GAAG5E,OAAO,CACnB,MAAMmC,UAAU,CAACmB,UAAU,EAAEqB,YAAY,EAAErC,WAAW,CAAC,EACvD,CAACgB,UAAU,EAAEqB,YAAY,EAAErC,WAAW,CACxC,CAAC;EAED,MAAMuC,SAAS,GAAG7E,OAAO,CACvB,OAAO;IAAEqC,IAAI,EAAEe,SAAS;IAAEuB,YAAY;IAAEJ,OAAO;IAAEnC,KAAK,EAAEkB,UAAU;IAAEoB;EAAS,CAAC,CAAC,EAC/E,CAACtB,SAAS,EAAEuB,YAAY,EAAEJ,OAAO,EAAEjB,UAAU,EAAEoB,QAAQ,CACzD,CAAC;EAED,oBACE/C,IAAA,CAACe,YAAY,CAACoC,QAAQ;IAACC,KAAK,EAAEH,KAAM;IAAA9B,QAAA,eAClCnB,IAAA,CAACiB,gBAAgB,CAACkC,QAAQ;MAACC,KAAK,EAAEF,SAAU;MAAA/B,QAAA,EAAEA;IAAQ,CAA4B;EAAC,CAC9D,CAAC;AAE5B","ignoreList":[]}