@rific/auto-paper 0.2.0 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 # @rific/auto-paper
 
-Adaptive theming for [`react-native-paper`](https://callstack.github.io/react-native-paper/). Give it one color and an appearance setting — it generates a triadic MD3 palette and handles light/dark/system mode automatically.
+Adaptive theming for [`react-native-paper`](https://callstack.github.io/react-native-paper/). Give it one color and an appearance setting — it generates an MD3 palette and handles light/dark/system mode automatically.
 
 ## Features
 
-- Triadic color palette from a single seed color (primary → secondary → tertiary, 120° apart on the color wheel)
+- Color harmony palette from a single seed color (primary → secondary → tertiary) — 6 harmony modes available, defaulting to `split-complementary`
 - System/light/dark appearance with live updates via `Appearance` API
 - Tinted surface, surfaceVariant, outline, and elevation levels derived from the seed
 - Optional Redux slice for wiring appearance and color into your store
@@ -37,11 +37,8 @@ npm install expo-navigation-bar
 import { Provider as AutoPaperProvider } from '@rific/auto-paper'
 
 export default function App() {
-  const [appearance, setAppearance] = useState<'system' | 'light' | 'dark'>('system')
-  const [color, setColor] = useState('#6750a4')
-
   return (
-    <AutoPaperProvider appearance={appearance} color={color}>
+    <AutoPaperProvider initialValue={{ appearance: 'system', color: '#6750a4' }}>
       {/* your app */}
     </AutoPaperProvider>
   )
@@ -51,11 +48,44 @@ export default function App() {
 `Provider` renders `null` on the first render while the theme computes, then wraps your app in `PaperProvider` with the computed theme, a matching `StatusBar`, and a background `View`. Use `onReady` to hook into that moment — e.g. to dismiss a splash screen:
 
 ```tsx
-<AutoPaperProvider appearance={appearance} color={color} onReady={SplashScreen.hideAsync}>
+<AutoPaperProvider initialValue={{ appearance: 'system', color: '#6750a4' }} onReady={SplashScreen.hideAsync}>
   {/* your app */}
 </AutoPaperProvider>
 ```
 
+Update theme settings from anywhere inside the tree using `useThemeSettings`:
+
+```tsx
+import { useThemeSettings } from '@rific/auto-paper'
+
+function SettingsScreen() {
+  const { settings, set } = useThemeSettings()
+  return (
+    <>
+      <Button onPress={() => set({ appearance: 'dark' })}>Dark mode</Button>
+      <Button onPress={() => set({ color: '#e91e63' })}>Change color</Button>
+    </>
+  )
+}
+```
+
+### Choosing a color harmony
+
+The `harmony` prop controls how secondary and tertiary colors are derived from your seed. The default is `split-complementary`, which works well for most apps — it keeps secondary and tertiary close together in hue so they feel like a family of accents rather than three competing dominant colors.
+
+```tsx
+<AutoPaperProvider initialValue={{ appearance: 'system', color: '#6750a4', harmony: 'split-complementary' }}>
+```
+
+| Harmony | Offsets | Character |
+|---|---|---|
+| `split-complementary` *(default)* | 0°, +150°, +210° | Harmonious contrast — flanks the complement by ±30° |
+| `triadic` | 0°, +120°, +240° | Equilateral — maximum variety, three equal-weight colors |
+| `analogous` | 0°, +30°, +60° | Cohesive, natural — neighboring hues |
+| `square` | 0°, +90°, +270° | Balanced, structured — right-angle symmetry |
+| `complementary` | 0°, +90°, +180° | Bold — accent at 90° plus true opposite |
+| `double-split` | 0°, +30°, +330° | Tight — flanks the primary by ±30° |
+
 ### With component defaults
 
 Pass a `defaults` object to `Provider` to set prop defaults for any of the included wrapper components. Each component merges defaults under its own props, so per-instance props always win:
@@ -64,8 +94,7 @@ Pass a `defaults` object to `Provider` to set prop defaults for any of the inclu
 import { Button, Chip, Provider as AutoPaperProvider } from '@rific/auto-paper'
 
 <AutoPaperProvider
-  appearance={appearance}
-  color={color}
+  initialValue={{ appearance: 'system', color: '#6750a4' }}
   defaults={{
     AppbarHeader: { elevated: true },
     BottomNavigation: { labeled: false },
@@ -107,7 +136,7 @@ import { Provider as AutoPaperProvider } from '@rific/auto-paper'
 export default function App() {
   const { appearance, color } = useSelector((state: RootState) => state.theme)
   return (
-    <AutoPaperProvider appearance={appearance} color={color} onReady={SplashScreen.hideAsync}>
+    <AutoPaperProvider initialValue={{ appearance, color }} onReady={SplashScreen.hideAsync}>
       {/* your app */}
     </AutoPaperProvider>
   )
@@ -161,20 +190,45 @@ export default function App() {
 
 | Prop | Type | Description |
 |---|---|---|
-| `appearance` | `'system' \| 'light' \| 'dark'` | Appearance mode |
-| `color` | `string` | Seed color (hex, rgb, or CSS name) |
+| `initialValue` | `Partial<ThemeSettings>` | Initial theme settings — `appearance`, `color`, `harmony`, `blur`, `blurTint`. Defaults from `defaultThemeSettings` fill any omitted fields. |
+| `onChange` | `(settings: ThemeSettings) => void` | Called whenever settings change via `useThemeSettings().set()` |
 | `children` | `ReactNode` | |
 | `defaults` | `PaperDefaults` | Prop defaults for wrapper components (see below) |
 | `onReady` | `() => void` | Called once when the theme first resolves |
 | `statusBarProps` | `StatusBarProps` | Spread over the auto-derived `StatusBar` defaults |
 | `style` | `StyleProp<ViewStyle>` | Applied to the wrapper `View` |
 
-### `useComputedTheme(appearance, color)`
+`ThemeSettings` fields:
+
+| Field | Type | Default |
+|---|---|---|
+| `appearance` | `'system' \| 'light' \| 'dark'` | `'system'` |
+| `color` | `string` | `'#6750a4'` |
+| `harmony` | `ColorHarmony` | `'split-complementary'` |
+| `blur` | `boolean` | `true` |
+| `blurTint` | `number` | `0.2` |
+
+### `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.
+
+```tsx
+import { useThemeSettings } from '@rific/auto-paper'
+
+const { settings, set } = useThemeSettings()
+
+set({ appearance: 'dark' })
+set({ color: '#e91e63' })
+set({ harmony: 'triadic' })
+```
+
+### `useComputedTheme(appearance, color, harmony?)`
 
 Returns `MD3Theme | null`. `null` on the first render while the theme computes.
 
 ```ts
 const theme = useComputedTheme('system', '#6750a4')
+const theme = useComputedTheme('system', '#6750a4', 'triadic')
 ```
 
 ### `Appbar`
@@ -209,6 +263,48 @@ import { BottomNavigation } from '@rific/auto-paper'
 
 `BottomNavigation.Bar` and `BottomNavigation.SceneMap` are also available and both sync the navigation bar.
 
+### `Chip`
+
+A thin wrapper around `react-native-paper`'s `Chip` that adds a `variant` prop for applying theme-derived container colors.
+
+```tsx
+import { Chip } from '@rific/auto-paper'
+
+<Chip>Default</Chip>
+<Chip variant="primary">Primary</Chip>
+<Chip variant="secondary">Secondary</Chip>
+<Chip variant="tertiary">Tertiary</Chip>
+<Chip variant="surface">Surface</Chip>
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'surface'` | Applies the matching container color as background and its `on*` counterpart as `selectedColor` |
+| ...all `ChipProps` | | All props from `react-native-paper`'s `Chip` are supported |
+
+`ChipProps` is exported from `@rific/auto-paper` and extends `react-native-paper`'s `ChipProps` with the `variant` field. Use `PaperChipProps` if you need the base paper type.
+
+### `IconButton`
+
+A thin wrapper around `react-native-paper`'s `IconButton` that adds a `variant` prop for applying theme-derived container and icon colors.
+
+```tsx
+import { IconButton } from '@rific/auto-paper'
+
+<IconButton icon="pencil" />
+<IconButton icon="pencil" variant="primary" />
+<IconButton icon="pencil" variant="secondary" />
+<IconButton icon="pencil" variant="tertiary" />
+<IconButton icon="pencil" variant="surface" />
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'surface'` | Sets `containerColor` and `iconColor` from the matching theme color pair |
+| ...all `IconButtonProps` | | All props from `react-native-paper`'s `IconButton` are supported — explicit `containerColor` or `iconColor` override the variant |
+
+`IconButtonProps` is exported from `@rific/auto-paper` and extends `react-native-paper`'s `IconButtonProps` with the `variant` field. Use `PaperIconButtonProps` if you need the base paper type.
+
 ### `PaperDefaults` / `usePaperDefaults`
 
 `PaperDefaults` is the type for the `defaults` prop on `Provider`:
@@ -264,9 +360,14 @@ const appearance = useSelector((state: RootState) => selectThemeAppearance(state
 
 ```ts
 import { getTriadicPalette, getBlendedColor, isDarkColor, getRgb, getHex } from '@rific/auto-paper'
-
-getTriadicPalette('#ff0000')
-// → { primary: '#ff0000', secondary: '#00ff00', tertiary: '#0000ff' }
+import type { ColorHarmony } from '@rific/auto-paper'
+
+getTriadicPalette('#6750a4')                          // split-complementary (default)
+getTriadicPalette('#6750a4', 'triadic')               // → { primary, secondary, tertiary }
+getTriadicPalette('#6750a4', 'analogous')
+getTriadicPalette('#6750a4', 'square')
+getTriadicPalette('#6750a4', 'complementary')
+getTriadicPalette('#6750a4', 'double-split')
 
 getBlendedColor('#ff0000', '#0000ff', 0.5)  // → '#800080'
 isDarkColor('#6750a4')                       // → true

package/dist/index.d.mts

@@ -1,17 +1,19 @@
 import * as react_native_paper_lib_typescript_utils_forwardRef from 'react-native-paper/lib/typescript/utils/forwardRef';
 import * as react_native from 'react-native';
-import { TextInput as TextInput$1, StatusBarProps, StyleProp, ViewStyle } from 'react-native';
+import { StyleProp, ViewStyle, TextInput as TextInput$1, StatusBarProps } from 'react-native';
+import * as react_native_paper from 'react-native-paper';
+import { AppbarHeaderProps, MD3Theme, BottomNavigationRoute, BottomNavigationProps, BottomNavigation as BottomNavigation$1, ButtonProps, ChipProps as ChipProps$1, DialogProps as DialogProps$1, DialogTitleProps, DialogContentProps, DialogActionsProps, DialogScrollAreaProps, FABProps, IconButtonProps as IconButtonProps$1, MenuProps as MenuProps$1, MenuItemProps, TextInputProps } from 'react-native-paper';
+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, { ReactNode } from 'react';
-import * as react_native_paper from 'react-native-paper';
-import { AppbarHeaderProps, BottomNavigationRoute, BottomNavigationProps, BottomNavigation as BottomNavigation$1, ButtonProps, ChipProps, FABProps, IconButtonProps, TextInputProps, MD3Theme } from 'react-native-paper';
-export { AppbarHeaderProps, BottomNavigationProps, BottomNavigationRoute, ButtonProps, ChipProps, FABProps, IconButtonProps, TextInputProps } from 'react-native-paper';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { BlurViewProps as BlurViewProps$1 } from 'expo-blur';
 import * as _reduxjs_toolkit from '@reduxjs/toolkit';
 import { PayloadAction } from '@reduxjs/toolkit';
 import * as redux from 'redux';
 
-declare function Header({ style, ...props }: AppbarHeaderProps): react_jsx_runtime.JSX.Element;
+declare function useBlur(override?: boolean): boolean;
+
+declare function Header({ style, ...props }: AppbarHeaderProps): react.JSX.Element;
 declare const Appbar: {
     Header: typeof Header;
     Content: {
@@ -22,9 +24,34 @@ declare const Appbar: {
     BackAction: react_native_paper_lib_typescript_utils_forwardRef.ForwardRefComponent<react_native.View, react_native_paper.AppbarBackActionProps>;
 };
 
-declare function BottomNavigationComponent<Route extends BottomNavigationRoute>(props: BottomNavigationProps<Route>): react_jsx_runtime.JSX.Element;
+type ColorHarmony = 'triadic' | 'split-complementary' | 'analogous' | 'square' | 'complementary' | 'double-split';
+type TriadicPalette = {
+    primary: string;
+    secondary: string;
+    tertiary: string;
+};
+declare function getTriadicPalette(primaryColor: string, harmony?: ColorHarmony): TriadicPalette;
+
+type ThemeAppearance = 'system' | 'light' | 'dark';
+declare function useComputedTheme(appearance: ThemeAppearance, color: string, harmony?: ColorHarmony): MD3Theme | null;
+
+type Props$2 = {
+    value: ThemeAppearance;
+    onChange: (appearance: ThemeAppearance) => void;
+};
+declare const AppearancePicker: ({ value, onChange }: Props$2) => react.JSX.Element;
+
+type BlurViewProps = BlurViewProps$1 & {
+    blur?: boolean;
+    children?: ReactNode;
+    elevation?: 0 | 1 | 2 | 3 | 4 | 5;
+    style?: StyleProp<ViewStyle>;
+};
+declare const BlurView: ({ blur, children, elevation, style, ...props }: BlurViewProps) => react.JSX.Element;
+
+declare function BottomNavigationComponent<Route extends BottomNavigationRoute>(props: BottomNavigationProps<Route>): react__default.JSX.Element;
 declare namespace BottomNavigationComponent {
-    var Bar: (props: BarProps) => react_jsx_runtime.JSX.Element;
+    var Bar: (props: BarProps) => react__default.JSX.Element;
     var SceneMap: <Route extends BottomNavigationRoute>(scenes: {
         [key: string]: react__default.ComponentType<{
             route: Route;
@@ -38,13 +65,58 @@ declare namespace BottomNavigationComponent {
 type BarProps = react__default.ComponentProps<typeof BottomNavigation$1.Bar>;
 declare const BottomNavigation: typeof BottomNavigationComponent;
 
-declare function Button(props: ButtonProps): react_jsx_runtime.JSX.Element;
+declare function Button(props: ButtonProps): react.JSX.Element;
+
+type ChipProps = ChipProps$1 & {
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'surface';
+};
+declare function Chip({ variant, style, selectedColor, ...props }: ChipProps): react.JSX.Element;
+
+type SeedColor = {
+    label: string;
+    value: string;
+};
+declare const defaultColors: SeedColor[];
+type Props$1 = {
+    value: string;
+    onChange: (color: string) => void;
+    colors?: SeedColor[];
+    blur?: boolean;
+};
+declare const ColorPicker: ({ value, onChange, colors, blur: blurProp }: Props$1) => react.JSX.Element;
 
-declare function Chip(props: ChipProps): react_jsx_runtime.JSX.Element;
+type DialogProps = DialogProps$1 & {
+    blur?: boolean;
+};
+declare function DialogComponent({ blur: blurProp, visible, onDismiss, children, style, ...rest }: DialogProps): react__default.JSX.Element | null;
+declare namespace DialogComponent {
+    var Title: react__default.FC<DialogTitleProps>;
+    var Content: react__default.FC<DialogContentProps>;
+    var Actions: react__default.FC<DialogActionsProps>;
+    var ScrollArea: react__default.FC<DialogScrollAreaProps>;
+}
+declare const Dialog: typeof DialogComponent;
 
-declare function FAB(props: FABProps): react_jsx_runtime.JSX.Element;
+declare function FAB(props: FABProps): react.JSX.Element;
 
-declare function IconButton(props: IconButtonProps): react_jsx_runtime.JSX.Element;
+type Props = {
+    value: ColorHarmony;
+    onChange: (harmony: ColorHarmony) => void;
+    blur?: boolean;
+};
+declare const HarmonyPicker: ({ value, onChange, blur: blurProp }: Props) => react.JSX.Element;
+
+type IconButtonProps = IconButtonProps$1 & {
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'surface';
+};
+declare function IconButton({ variant, iconColor, containerColor, ...props }: IconButtonProps): react.JSX.Element;
+
+type MenuProps = MenuProps$1 & {
+    blur?: boolean;
+};
+declare const Menu: (({ blur: blurProp, children, ...props }: MenuProps) => react__default.JSX.Element) & {
+    Item: react__default.FC<MenuItemProps>;
+};
 
 declare const TextInput: react.ForwardRefExoticComponent<Omit<TextInputProps, "ref"> & react.RefAttributes<TextInput$1>>;
 
@@ -52,52 +124,90 @@ type PaperDefaults = {
     AppbarHeader?: Partial<AppbarHeaderProps>;
     BottomNavigation?: Partial<BottomNavigationProps<BottomNavigationRoute>>;
     Button?: Partial<ButtonProps>;
-    Chip?: Partial<ChipProps>;
+    Chip?: Partial<ChipProps$1>;
     FAB?: Partial<FABProps>;
-    IconButton?: Partial<IconButtonProps>;
+    IconButton?: Partial<IconButtonProps$1>;
     TextInput?: Partial<TextInputProps>;
 };
 declare function usePaperDefaults(): PaperDefaults;
 
-type ThemeAppearance = 'system' | 'light' | 'dark';
-declare function useComputedTheme(appearance: ThemeAppearance, color: string): MD3Theme | null;
-
 type ThemeState = {
     appearance: ThemeAppearance;
+    blur: boolean;
     color: string;
+    harmony: ColorHarmony;
 };
 declare function createThemeReducer(initialState?: Partial<ThemeState>): redux.Reducer<{
     appearance: ThemeAppearance;
+    blur: boolean;
     color: string;
+    harmony: ColorHarmony;
 }>;
 declare const themeActions: _reduxjs_toolkit.CaseReducerActions<{
     initialize: (state: ThemeState, action: PayloadAction<Partial<ThemeState>>) => {
         appearance: ThemeAppearance;
+        blur: boolean;
         color: string;
+        harmony: ColorHarmony;
     };
     setAppearance: (state: ThemeState, action: PayloadAction<ThemeAppearance>) => {
         appearance: ThemeAppearance;
+        blur: boolean;
         color: string;
+        harmony: ColorHarmony;
+    };
+    setBlur: (state: ThemeState, action: PayloadAction<boolean>) => {
+        blur: boolean;
+        appearance: ThemeAppearance;
+        color: string;
+        harmony: ColorHarmony;
     };
     setColor: (state: ThemeState, action: PayloadAction<string>) => {
         color: string;
         appearance: ThemeAppearance;
+        blur: boolean;
+        harmony: ColorHarmony;
+    };
+    setHarmony: (state: ThemeState, action: PayloadAction<ColorHarmony>) => {
+        harmony: ColorHarmony;
+        appearance: ThemeAppearance;
+        blur: boolean;
+        color: string;
     };
 }, "theme">;
 declare const themeReducer: redux.Reducer<ThemeState>;
 declare const selectThemeAppearance: (state: ThemeState) => ThemeAppearance;
+declare const selectThemeBlur: (state: ThemeState) => boolean;
 declare const selectThemeColor: (state: ThemeState) => string;
+declare const selectThemeHarmony: (state: ThemeState) => ColorHarmony;
 
-type ProviderProps = {
+type ThemeSettings = {
     appearance: ThemeAppearance;
+    blur: boolean;
+    blurTint: number;
     color: string;
+    harmony: ColorHarmony;
+};
+declare const defaultThemeSettings: ThemeSettings;
+type ThemeSettingsContextType = {
+    settings: ThemeSettings;
+    set: (patch: Partial<ThemeSettings>) => void;
+};
+declare const ThemeSettingsContext: react.Context<ThemeSettingsContextType>;
+
+type ProviderProps = {
+    initialValue?: Partial<ThemeSettings>;
+    onChange?: (settings: ThemeSettings) => void;
     children: ReactNode;
     defaults?: PaperDefaults;
+    onNavBarChange?: (color: string, dark: boolean) => void;
     onReady?: () => void;
     statusBarProps?: StatusBarProps;
     style?: StyleProp<ViewStyle>;
 };
-declare function Provider({ appearance, color, children, defaults, onReady, statusBarProps, style }: ProviderProps): react_jsx_runtime.JSX.Element | null;
+declare function Provider({ initialValue, onChange, children, defaults, onNavBarChange, onReady, statusBarProps, style }: ProviderProps): react.JSX.Element | null;
+
+declare const useThemeSettings: () => ThemeSettingsContextType;
 
 declare const getBlendedColor: (foreground: string, background: string, alpha: number) => string;
 
@@ -111,13 +221,6 @@ type RGB = {
 };
 declare const getRgb: (value: string) => RGB | null;
 
-type TriadicPalette = {
-    primary: string;
-    secondary: string;
-    tertiary: string;
-};
-declare function getTriadicPalette(primaryColor: string): TriadicPalette;
-
 declare const isDarkColor: (value: string) => boolean;
 
-export { Appbar, BottomNavigation, Button, Chip, FAB, IconButton, type PaperDefaults, Provider, type ProviderProps, type RGB, TextInput, type ThemeAppearance, type ThemeState, type TriadicPalette, createThemeReducer, getBlendedColor, getHex, getRgb, getTriadicPalette, isDarkColor, selectThemeAppearance, selectThemeColor, themeActions, themeReducer, useComputedTheme, usePaperDefaults };
+export { Appbar, AppearancePicker, BlurView, type BlurViewProps, BottomNavigation, Button, Chip, type ChipProps, type ColorHarmony, ColorPicker, Dialog, type DialogProps, FAB, HarmonyPicker, IconButton, type IconButtonProps, Menu, type MenuProps, type PaperDefaults, Provider, type ProviderProps, type RGB, type SeedColor, TextInput, type ThemeAppearance, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getHex, getRgb, getTriadicPalette, isDarkColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useBlur, useComputedTheme, usePaperDefaults, useThemeSettings };