@rific/auto-paper 0.10.3 → 0.12.0

package/README.md

@@ -201,6 +201,26 @@ dispatch(themeActions.setColor('#e91e63'))
 dispatch(themeActions.setAppearance('dark'))
 ```
 
+The `App.tsx` example above hand-builds the `initialValue`/`onReady` prop pair inline. Once you also need `onChange` wired back to `dispatch`, reach for `useThemeBridgeProps` instead of re-deriving that same three-field object by hand: it takes your already-resolved `settings`/`onChange`/`onReady` and reshapes them into the exact, memoized prop bag `Provider` expects.
+
+```tsx
+// Theme.tsx
+import { Provider as AutoPaperProvider, useThemeBridgeProps } from '@rific/auto-paper'
+import { useCallback } from 'react'
+import { shallowEqual, useDispatch, useSelector } from 'react-redux'
+
+export function Theme({ children }: { children: React.ReactNode }) {
+  const settings = useSelector((state: RootState) => state.theme, shallowEqual)
+  const dispatch = useDispatch()
+  const onChange = useCallback((next: ThemeSettings) => dispatch(themeActions.initialize(next)), [dispatch])
+  const bridgeProps = useThemeBridgeProps({ initialValue: settings, onChange, onReady: SplashScreen.hideAsync })
+
+  return <AutoPaperProvider {...bridgeProps}>{children}</AutoPaperProvider>
+}
+```
+
+Keep the scope honest: this only replaces the final `<Provider initialValue={...} onChange={...} onReady={...}>` prop list with `<Provider {...bridgeProps}>`. It doesn't do the `useSelector`/`useDispatch` wiring above it — that's still yours to write, since `RootState`'s shape is app-local and this package has no opinion on it (or on state management being Redux at all; `useThemeBridgeProps` takes plain values and callbacks, not a `dispatch` function).
+
 ### With `useComputedTheme`
 
 Use the hook directly when you need to extend the theme before passing it to `PaperProvider`, for example to merge in a navigation theme or add custom color keys:
@@ -262,6 +282,21 @@ export default function App() {
 | `blur` | `boolean` | `true` |
 | `blurTint` | `number` | `0.2` |
 
+### `useThemeBridgeProps({ initialValue, onChange, onReady })`
+
+Reshapes already-resolved values into the exact `Pick<ProviderProps, 'initialValue' | 'onChange' | 'onReady'>` shape `Provider` expects, memoized on those three fields so the returned object is referentially stable across re-renders until an input actually changes. Meant for a consuming app's own Redux-backed "Theme" component — see "With Redux" above — but takes plain values and callbacks rather than a `dispatch` function or anything Redux-specific, so it works with any state management, or none.
+
+It only replaces the final prop list handed to `Provider`; it does not do any `useSelector`/`dispatch` wiring itself, and `onReady` is threaded through unchanged.
+
+```ts
+import { useThemeBridgeProps } from '@rific/auto-paper'
+
+const bridgeProps = useThemeBridgeProps({ initialValue: settings, onChange, onReady })
+// → { initialValue, onChange, onReady }
+
+<Provider {...bridgeProps}>{children}</Provider>
+```
+
 ### `useThemeSettings()`
 
 Returns `{ settings: ThemeSettings, set: (patch: Partial<ThemeSettings>) => void }`. Use this hook from any component inside `Provider` to read or update the current theme settings.

package/dist/index.d.mts

@@ -6,6 +6,8 @@ import { AppbarHeaderProps, MD3Theme, BottomNavigationRoute, BottomNavigationPro
 export { AppbarHeaderProps, BottomNavigationProps, BottomNavigationRoute, ButtonProps, FABProps, ChipProps as PaperChipProps, DialogProps as PaperDialogProps, IconButtonProps as PaperIconButtonProps, MenuProps as PaperMenuProps, TextInputProps } from 'react-native-paper';
 import * as react from 'react';
 import react__default, { RefObject, ReactNode, ComponentType } from 'react';
+import * as _rific_core from '@rific/core';
+import { SettingsContextValue } from '@rific/core';
 
 declare function useBlur(override?: boolean): boolean;
 
@@ -227,53 +229,46 @@ type ThemeState = {
     color: string | TriadicPalette;
     harmony: ColorHarmony;
 };
-type PayloadAction<P> = {
-    payload: P;
-    type: string;
-};
 declare const themeActions: {
     initialize: {
-        (payload: Partial<ThemeState>): PayloadAction<Partial<ThemeState>>;
+        (payload: Partial<ThemeState>): _rific_core.SettingsAction<Partial<ThemeState>>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<Partial<ThemeState>>;
+        }) => action is _rific_core.SettingsAction<Partial<ThemeState>>;
     };
-    setAppearance: {
-        (payload: ThemeAppearance): PayloadAction<ThemeAppearance>;
+} & {
+    setColor: {
+        (payload: string | TriadicPalette): _rific_core.SettingsAction<string | TriadicPalette>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<ThemeAppearance>;
+        }) => action is _rific_core.SettingsAction<string | TriadicPalette>;
     };
-    setBlur: {
-        (payload: boolean): PayloadAction<boolean>;
+    setAppearance: {
+        (payload: ThemeAppearance): _rific_core.SettingsAction<ThemeAppearance>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<boolean>;
+        }) => action is _rific_core.SettingsAction<ThemeAppearance>;
     };
-    setColor: {
-        (payload: string | TriadicPalette): PayloadAction<string | TriadicPalette>;
+    setBlur: {
+        (payload: boolean): _rific_core.SettingsAction<boolean>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<string | TriadicPalette>;
+        }) => action is _rific_core.SettingsAction<boolean>;
     };
     setHarmony: {
-        (payload: ColorHarmony): PayloadAction<ColorHarmony>;
+        (payload: ColorHarmony): _rific_core.SettingsAction<ColorHarmony>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<ColorHarmony>;
+        }) => action is _rific_core.SettingsAction<ColorHarmony>;
     };
 };
-declare function createThemeReducer(initialState?: Partial<ThemeState>): (state: ThemeState | undefined, action: {
-    type: string;
-}) => ThemeState;
-declare const themeReducer: (state: ThemeState | undefined, action: {
-    type: string;
-}) => ThemeState;
+declare const themeReducer: _rific_core.SettingsReducer<ThemeState>;
+declare const createThemeReducer: (overrideInitialState?: Partial<ThemeState> | undefined) => _rific_core.SettingsReducer<ThemeState>;
 declare const selectThemeAppearance: (state: ThemeState) => ThemeAppearance;
 declare const selectThemeBlur: (state: ThemeState) => boolean;
 declare const selectThemeColor: (state: ThemeState) => string | TriadicPalette;
@@ -287,11 +282,8 @@ type ThemeSettings = {
     harmony: ColorHarmony;
 };
 declare const defaultThemeSettings: ThemeSettings;
-type ThemeSettingsContextType = {
-    settings: ThemeSettings;
-    set: (patch: Partial<ThemeSettings>) => void;
-};
-declare const ThemeSettingsContext: react.Context<ThemeSettingsContextType>;
+type ThemeSettingsContextType = SettingsContextValue<ThemeSettings>;
+declare const ThemeSettingsContext: react.Context<SettingsContextValue<ThemeSettings>>;
 
 type NavBarContextType = {
     navigationBar?: ExpoNavigationBarModule;
@@ -322,11 +314,52 @@ type ProviderProps = {
     statusBarProps?: StatusBarProps;
     style?: StyleProp<ViewStyle>;
 };
-declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }: ProviderProps): react.JSX.Element | null;
+declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }: ProviderProps): react.JSX.Element;
 
 declare const useAutoPaperTheme: () => AutoPaperTheme;
 
-declare const useThemeSettings: () => ThemeSettingsContextType;
+/**
+ * The subset of ProviderProps a consuming app's own Redux-backed "Theme" component is responsible
+ * for supplying. Every field here has an identically-named counterpart on ProviderProps itself
+ * (see ThemeProvider.tsx) - deliberately not renamed, so wiring this up needs no new vocabulary
+ * beyond the provider's own.
+ */
+type ThemeBridgeProps = Pick<ProviderProps, 'initialValue' | 'onChange' | 'onReady'>;
+/**
+ * Reshapes an app's own Redux-sourced theme state and callbacks into the exact prop object
+ * `<Provider>` expects, so a consuming app's own "Theme" component - every game in the fleet
+ * defines one, reading `state.theme` from its own store via `useSelector(..., shallowEqual)` and
+ * dispatching `themeActions.initialize` on change - can hand its own `useSelector`/`dispatch`
+ * results straight to this hook instead of re-deriving the same three-prop shape by hand in every
+ * app:
+ *
+ * ```tsx
+ * export function Theme({ children }: Props) {
+ *   const settings = useSelector((state: RootState) => state.theme, shallowEqual)
+ *   const dispatch = useDispatch()
+ *   const onChange = useCallback((next: ThemeSettings) => dispatch(themeActions.initialize(next)), [dispatch])
+ *   const onReady = useCallback(() => markSplashReady('theme'), [])
+ *   const bridgeProps = useThemeBridgeProps({ initialValue: settings, onChange, onReady })
+ *   return <Provider {...bridgeProps}>{children}</Provider>
+ * }
+ * ```
+ *
+ * Deliberately takes plain values and callbacks rather than a `dispatch` function or any
+ * Redux-specific type: this package has no opinion on any app's own RootState shape, or even that
+ * state management is Redux at all - the app does its own `useSelector`/`dispatch` wiring and
+ * passes just the results in.
+ *
+ * `onReady` is threaded through completely unchanged, never recomputed or wrapped here - it fires
+ * exactly once, the first time `<Provider>` itself reports its computed theme is ready, which is
+ * the timing a consuming app's own splash-gate mark depends on. A wrong `onReady` callback (e.g.
+ * one that marks the gate ready before `<Provider>` actually is) is a bug in the app's own
+ * callback, not something this hook can catch or fix - see BoxHockey's and LightCycles' own history
+ * of hand-fixing exactly that "marked ready before Provider was actually ready" bug in their own
+ * Theme.tsx before this hook existed.
+ */
+declare function useThemeBridgeProps(props: ThemeBridgeProps): ThemeBridgeProps;
+
+declare const useThemeSettings: () => _rific_core.SettingsContextValue<ThemeSettings>;
 
 declare const getBlendedColor: (foreground: string, background: string, alpha: number) => string;
 
@@ -360,4 +393,4 @@ declare const isDarkColor: (value: string) => boolean;
 
 declare const resolveSeedColor: (color: string | TriadicPalette) => string;
 
-export { Appbar, type AppearanceIcons, AppearancePicker, AutoAppearancePicker, AutoPalettePicker, type AutoPaperTheme, BlurView, type BlurViewProps, BottomNavigation, Button, Chip, type ChipProps, type ColorHarmony, ColorPicker, type ColorRoles, Dialog, type DialogProps, type ExpoBlurModule, type ExpoNavigationBarModule, FAB, HarmonyPicker, IconButton, type IconButtonProps, Menu, type MenuProps, PalettePicker, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SEMANTIC_BASE_COLORS, type SeedColor, type SemanticColorRoles, TextInput, type ThemeAppearance, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getColorRoles, getContrastColor, getHex, getRgb, getThirdColor, getTintTextColor, getTonalColor, getTriadicPalette, isDarkColor, resolveSeedColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useAutoPaperTheme, useBlur, useBlurModule, useComputedTheme, useNavBarContext, usePaperDefaults, useReanimatedModule, useThemeSettings };
+export { Appbar, type AppearanceIcons, AppearancePicker, AutoAppearancePicker, AutoPalettePicker, type AutoPaperTheme, BlurView, type BlurViewProps, BottomNavigation, Button, Chip, type ChipProps, type ColorHarmony, ColorPicker, type ColorRoles, Dialog, type DialogProps, type ExpoBlurModule, type ExpoNavigationBarModule, FAB, HarmonyPicker, IconButton, type IconButtonProps, Menu, type MenuProps, PalettePicker, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SEMANTIC_BASE_COLORS, type SeedColor, type SemanticColorRoles, TextInput, type ThemeAppearance, type ThemeBridgeProps, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getColorRoles, getContrastColor, getHex, getRgb, getThirdColor, getTintTextColor, getTonalColor, getTriadicPalette, isDarkColor, resolveSeedColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useAutoPaperTheme, useBlur, useBlurModule, useComputedTheme, useNavBarContext, usePaperDefaults, useReanimatedModule, useThemeBridgeProps, useThemeSettings };

package/dist/index.d.ts

@@ -6,6 +6,8 @@ import { AppbarHeaderProps, MD3Theme, BottomNavigationRoute, BottomNavigationPro
 export { AppbarHeaderProps, BottomNavigationProps, BottomNavigationRoute, ButtonProps, FABProps, ChipProps as PaperChipProps, DialogProps as PaperDialogProps, IconButtonProps as PaperIconButtonProps, MenuProps as PaperMenuProps, TextInputProps } from 'react-native-paper';
 import * as react from 'react';
 import react__default, { RefObject, ReactNode, ComponentType } from 'react';
+import * as _rific_core from '@rific/core';
+import { SettingsContextValue } from '@rific/core';
 
 declare function useBlur(override?: boolean): boolean;
 
@@ -227,53 +229,46 @@ type ThemeState = {
     color: string | TriadicPalette;
     harmony: ColorHarmony;
 };
-type PayloadAction<P> = {
-    payload: P;
-    type: string;
-};
 declare const themeActions: {
     initialize: {
-        (payload: Partial<ThemeState>): PayloadAction<Partial<ThemeState>>;
+        (payload: Partial<ThemeState>): _rific_core.SettingsAction<Partial<ThemeState>>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<Partial<ThemeState>>;
+        }) => action is _rific_core.SettingsAction<Partial<ThemeState>>;
     };
-    setAppearance: {
-        (payload: ThemeAppearance): PayloadAction<ThemeAppearance>;
+} & {
+    setColor: {
+        (payload: string | TriadicPalette): _rific_core.SettingsAction<string | TriadicPalette>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<ThemeAppearance>;
+        }) => action is _rific_core.SettingsAction<string | TriadicPalette>;
     };
-    setBlur: {
-        (payload: boolean): PayloadAction<boolean>;
+    setAppearance: {
+        (payload: ThemeAppearance): _rific_core.SettingsAction<ThemeAppearance>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<boolean>;
+        }) => action is _rific_core.SettingsAction<ThemeAppearance>;
     };
-    setColor: {
-        (payload: string | TriadicPalette): PayloadAction<string | TriadicPalette>;
+    setBlur: {
+        (payload: boolean): _rific_core.SettingsAction<boolean>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<string | TriadicPalette>;
+        }) => action is _rific_core.SettingsAction<boolean>;
     };
     setHarmony: {
-        (payload: ColorHarmony): PayloadAction<ColorHarmony>;
+        (payload: ColorHarmony): _rific_core.SettingsAction<ColorHarmony>;
         type: string;
-        match(action: {
+        match: (action: {
             type: string;
-        }): action is PayloadAction<ColorHarmony>;
+        }) => action is _rific_core.SettingsAction<ColorHarmony>;
     };
 };
-declare function createThemeReducer(initialState?: Partial<ThemeState>): (state: ThemeState | undefined, action: {
-    type: string;
-}) => ThemeState;
-declare const themeReducer: (state: ThemeState | undefined, action: {
-    type: string;
-}) => ThemeState;
+declare const themeReducer: _rific_core.SettingsReducer<ThemeState>;
+declare const createThemeReducer: (overrideInitialState?: Partial<ThemeState> | undefined) => _rific_core.SettingsReducer<ThemeState>;
 declare const selectThemeAppearance: (state: ThemeState) => ThemeAppearance;
 declare const selectThemeBlur: (state: ThemeState) => boolean;
 declare const selectThemeColor: (state: ThemeState) => string | TriadicPalette;
@@ -287,11 +282,8 @@ type ThemeSettings = {
     harmony: ColorHarmony;
 };
 declare const defaultThemeSettings: ThemeSettings;
-type ThemeSettingsContextType = {
-    settings: ThemeSettings;
-    set: (patch: Partial<ThemeSettings>) => void;
-};
-declare const ThemeSettingsContext: react.Context<ThemeSettingsContextType>;
+type ThemeSettingsContextType = SettingsContextValue<ThemeSettings>;
+declare const ThemeSettingsContext: react.Context<SettingsContextValue<ThemeSettings>>;
 
 type NavBarContextType = {
     navigationBar?: ExpoNavigationBarModule;
@@ -322,11 +314,52 @@ type ProviderProps = {
     statusBarProps?: StatusBarProps;
     style?: StyleProp<ViewStyle>;
 };
-declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }: ProviderProps): react.JSX.Element | null;
+declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }: ProviderProps): react.JSX.Element;
 
 declare const useAutoPaperTheme: () => AutoPaperTheme;
 
-declare const useThemeSettings: () => ThemeSettingsContextType;
+/**
+ * The subset of ProviderProps a consuming app's own Redux-backed "Theme" component is responsible
+ * for supplying. Every field here has an identically-named counterpart on ProviderProps itself
+ * (see ThemeProvider.tsx) - deliberately not renamed, so wiring this up needs no new vocabulary
+ * beyond the provider's own.
+ */
+type ThemeBridgeProps = Pick<ProviderProps, 'initialValue' | 'onChange' | 'onReady'>;
+/**
+ * Reshapes an app's own Redux-sourced theme state and callbacks into the exact prop object
+ * `<Provider>` expects, so a consuming app's own "Theme" component - every game in the fleet
+ * defines one, reading `state.theme` from its own store via `useSelector(..., shallowEqual)` and
+ * dispatching `themeActions.initialize` on change - can hand its own `useSelector`/`dispatch`
+ * results straight to this hook instead of re-deriving the same three-prop shape by hand in every
+ * app:
+ *
+ * ```tsx
+ * export function Theme({ children }: Props) {
+ *   const settings = useSelector((state: RootState) => state.theme, shallowEqual)
+ *   const dispatch = useDispatch()
+ *   const onChange = useCallback((next: ThemeSettings) => dispatch(themeActions.initialize(next)), [dispatch])
+ *   const onReady = useCallback(() => markSplashReady('theme'), [])
+ *   const bridgeProps = useThemeBridgeProps({ initialValue: settings, onChange, onReady })
+ *   return <Provider {...bridgeProps}>{children}</Provider>
+ * }
+ * ```
+ *
+ * Deliberately takes plain values and callbacks rather than a `dispatch` function or any
+ * Redux-specific type: this package has no opinion on any app's own RootState shape, or even that
+ * state management is Redux at all - the app does its own `useSelector`/`dispatch` wiring and
+ * passes just the results in.
+ *
+ * `onReady` is threaded through completely unchanged, never recomputed or wrapped here - it fires
+ * exactly once, the first time `<Provider>` itself reports its computed theme is ready, which is
+ * the timing a consuming app's own splash-gate mark depends on. A wrong `onReady` callback (e.g.
+ * one that marks the gate ready before `<Provider>` actually is) is a bug in the app's own
+ * callback, not something this hook can catch or fix - see BoxHockey's and LightCycles' own history
+ * of hand-fixing exactly that "marked ready before Provider was actually ready" bug in their own
+ * Theme.tsx before this hook existed.
+ */
+declare function useThemeBridgeProps(props: ThemeBridgeProps): ThemeBridgeProps;
+
+declare const useThemeSettings: () => _rific_core.SettingsContextValue<ThemeSettings>;
 
 declare const getBlendedColor: (foreground: string, background: string, alpha: number) => string;
 
@@ -360,4 +393,4 @@ declare const isDarkColor: (value: string) => boolean;
 
 declare const resolveSeedColor: (color: string | TriadicPalette) => string;
 
-export { Appbar, type AppearanceIcons, AppearancePicker, AutoAppearancePicker, AutoPalettePicker, type AutoPaperTheme, BlurView, type BlurViewProps, BottomNavigation, Button, Chip, type ChipProps, type ColorHarmony, ColorPicker, type ColorRoles, Dialog, type DialogProps, type ExpoBlurModule, type ExpoNavigationBarModule, FAB, HarmonyPicker, IconButton, type IconButtonProps, Menu, type MenuProps, PalettePicker, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SEMANTIC_BASE_COLORS, type SeedColor, type SemanticColorRoles, TextInput, type ThemeAppearance, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getColorRoles, getContrastColor, getHex, getRgb, getThirdColor, getTintTextColor, getTonalColor, getTriadicPalette, isDarkColor, resolveSeedColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useAutoPaperTheme, useBlur, useBlurModule, useComputedTheme, useNavBarContext, usePaperDefaults, useReanimatedModule, useThemeSettings };
+export { Appbar, type AppearanceIcons, AppearancePicker, AutoAppearancePicker, AutoPalettePicker, type AutoPaperTheme, BlurView, type BlurViewProps, BottomNavigation, Button, Chip, type ChipProps, type ColorHarmony, ColorPicker, type ColorRoles, Dialog, type DialogProps, type ExpoBlurModule, type ExpoNavigationBarModule, FAB, HarmonyPicker, IconButton, type IconButtonProps, Menu, type MenuProps, PalettePicker, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SEMANTIC_BASE_COLORS, type SeedColor, type SemanticColorRoles, TextInput, type ThemeAppearance, type ThemeBridgeProps, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getColorRoles, getContrastColor, getHex, getRgb, getThirdColor, getTintTextColor, getTonalColor, getTriadicPalette, isDarkColor, resolveSeedColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useAutoPaperTheme, useBlur, useBlurModule, useComputedTheme, useNavBarContext, usePaperDefaults, useReanimatedModule, useThemeBridgeProps, useThemeSettings };