@rific/auto-paper 0.13.3 → 0.14.0

package/README.md

@@ -2,6 +2,8 @@
 
 Adaptive theming for [`react-native-paper`](https://callstack.github.io/react-native-paper/). Give it one color and an appearance setting, and it generates an MD3 palette and handles light/dark/system mode automatically.
 
+**[Live demo](https://rific.jaydeaton.com/demos/auto-paper)**
+
 ## Features
 
 - Color harmony palette from a single seed color (primary → secondary → tertiary), with 6 harmony modes available, defaulting to `split-complementary`
@@ -271,6 +273,7 @@ export default function App() {
 | `navigationBar` | `ExpoNavigationBarModule` | Injects `expo-navigation-bar` (`import * as ExpoNavigationBar from 'expo-navigation-bar'`) so the Android nav bar icon style auto-syncs with the theme while a `BottomNavigation` is mounted. Omit (and don't pass `onNavBarChange`) to skip nav bar syncing entirely. |
 | `onNavBarChange` | `(color: string, dark: boolean) => void` | Overrides the built-in nav bar sync: called on Android when the theme changes while a `BottomNavigation` is mounted, instead of the automatic `navigationBar`-driven icon-style sync |
 | `onReady` | `() => void` | Called once when the theme first resolves |
+| `paletteTone` | `PaletteTone` | Maps each palette color (primary, secondary and tertiary, after the harmony rotation) to the color the theme uses, given the resolved appearance: `(color, dark) => string`. Everything else (roles, containers, outline, surfaces) derives from the toned palette, the stored seed stays the player's raw pick, and `AutoPalettePicker` previews its swatches through the same tone. Signal colors (success, warning, danger, error) are never toned. Must be referentially stable (a module-level function). `getChalkboardColor` is one (marker in light mode, chalk in dark). Omit for the untoned palette. |
 | `reanimated` | `ReanimatedModule` | Injects `react-native-reanimated` (for example `import Reanimated from 'react-native-reanimated'`) so `<Dialog animatedStyle={...}>` can animate its card on the UI thread. Omit to keep `animatedStyle` as a no-op. |
 | `statusBar` | `boolean` | Renders React Native's `StatusBar`, styled from the theme (here and in `Appbar.Header`). Default `true`. Pass `false` when the app sets the status bar per screen instead (react-native-screens' `statusBarStyle`/`statusBarHidden` screen options, which need `UIViewControllerBasedStatusBarAppearance` on): there a React Native `StatusBar` logs an error. An app linked against the iOS 27 SDK can't set the status bar app-wide at all, which is the only way that component works on iOS, so per-screen options are the way to style it there. |
 | `statusBarProps` | `StatusBarProps` | Spread over the auto-derived `StatusBar` defaults (ignored when `statusBar` is `false`) |
@@ -648,7 +651,7 @@ const appearance = useSelector((state: RootState) => selectThemeAppearance(state
 ### Color utilities
 
 ```ts
-import { getTriadicPalette, getThirdColor, getBlendedColor, getColorRoles, getContrastColor, isDarkColor, getRgb, getHex, getTonalColor, getTintTextColor, resolveSeedColor } from '@rific/auto-paper'
+import { getTriadicPalette, getThirdColor, getBlendedColor, getColorRoles, getContrastColor, getContrastRatio, getLuminance, isDarkColor, getRgb, getHex, getOklch, getOklchHex, getChalkboardColor, createChalkboardTone, getTonalColor, getTintTextColor, resolveSeedColor } from '@rific/auto-paper'
 import type { ColorHarmony, TriadicPalette } from '@rific/auto-paper'
 
 getTriadicPalette('#6750a4')                          // split-complementary (default)
@@ -661,11 +664,20 @@ getTriadicPalette('#6750a4', 'double-split')
 getThirdColor('#e53935', '#1e88e5')          // → '#59e52a' (hue maximally distant from both inputs; s/l averaged from both)
 
 getBlendedColor('#ff0000', '#0000ff', 0.5)   // → '#800080'
-getColorRoles('#6750a4', '#fffbfe')          // → { color, onColor, container, onContainer }: the MD3 color/onColor/container/onContainer math, generalized (this is what useComputedTheme uses internally for every role)
+getColorRoles('#6750a4', '#fffbfe')          // → { color, onColor, container, onContainer }: the MD3 color/onColor/container/onContainer math, generalized (this is what useComputedTheme uses internally for every role). onColor is light while light text reads on the color at 2.5:1, dark below that
+getContrastRatio('#767676', '#ffffff')       // → 4.54 (WCAG 2 contrast ratio, 1 to 21, either order)
+getLuminance('#ffffff')                      // → 1 (WCAG 2 relative luminance, 0 for black)
 getContrastColor('#6750a4')                  // → '#ffffff' (black/white pick for content sitting on a fully saturated fill)
 isDarkColor('#6750a4')                       // → true
 getRgb('coral')                              // → { r: 255, g: 127, b: 80 }
 getHex('rgb(255, 0, 0)')                     // → '#ff0000'
+getOklch('#6750a4')                          // → { l, c, h } (OKLCH: perceptual lightness 0-1, chroma, hue in degrees); null if unparseable
+getOklchHex({ l: 0.5, c: 0.15, h: 300 })     // → back to hex, losing only as much chroma as it must to stay in sRGB
+
+// Palette tones, for Provider's `paletteTone`: hue never moves, only lightness and chroma
+getChalkboardColor('#e53935', false)         // → a deeper marker red (light mode)
+getChalkboardColor('#e53935', true)          // → a pastel chalk red (dark mode)
+const softChalk = createChalkboardTone({ chalk: { minLuminance: 0 } }) // your own tone (marker and chalk options); define it at module level so it stays referentially stable
 
 resolveSeedColor('#6750a4')                  // → '#6750a4' (already a plain string)
 resolveSeedColor({ primary: '#6750a4', secondary: '#a4916c', tertiary: '#916ca4' }) // → '#6750a4' (a ThemeSettings.color explicit triad narrows to its own primary)

package/dist/index.d.mts

@@ -22,6 +22,22 @@ declare const Appbar: {
     BackAction: react_native_paper_lib_typescript_utils_forwardRef.ForwardRefComponent<react_native.View, react_native_paper.AppbarBackActionProps>;
 };
 
+type PaletteTone = (color: string, dark: boolean) => string;
+type ChalkboardToneOptions = {
+    marker?: {
+        maxLightness?: number;
+        chroma?: number;
+    };
+    chalk?: {
+        lightness?: number;
+        lift?: number;
+        chroma?: number;
+        minLuminance?: number;
+    };
+};
+declare const createChalkboardTone: (options?: ChalkboardToneOptions) => PaletteTone;
+declare const getChalkboardColor: PaletteTone;
+
 type ColorHarmony = 'triadic' | 'split-complementary' | 'analogous' | 'square' | 'complementary' | 'double-split';
 type TriadicPalette = {
     primary: string;
@@ -53,7 +69,7 @@ type SemanticColorRoles = {
 type AutoPaperTheme = Omit<MD3Theme, 'colors'> & {
     colors: MD3Theme['colors'] & SemanticColorRoles;
 };
-declare function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony?: ColorHarmony): AutoPaperTheme | null;
+declare function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony?: ColorHarmony, paletteTone?: PaletteTone): AutoPaperTheme | null;
 
 type AppearanceIcons = Partial<Record<ThemeAppearance, string>>;
 type Props$5 = {
@@ -96,8 +112,9 @@ type Props$2 = {
     weights?: PaletteWeights;
     colors?: SeedColor[];
     blur?: boolean;
+    previewColor?: (color: string) => string;
 };
-declare const PalettePicker: ({ value, onChange, harmony, onHarmonyChange, weights, colors, blur: blurProp }: Props$2) => react.JSX.Element;
+declare const PalettePicker: ({ value, onChange, harmony, onHarmonyChange, weights, colors, blur: blurProp, previewColor }: Props$2) => react.JSX.Element;
 
 type Props$1 = {
     weights?: PaletteWeights;
@@ -305,6 +322,7 @@ declare const useNavBarContext: () => NavBarContextType;
 declare const useBlurModule: () => ExpoBlurModule | undefined;
 declare const useReanimatedModule: () => ReanimatedModule | undefined;
 declare const useMaskedViewModule: () => MaskedViewModule | undefined;
+declare const usePaletteTone: () => PaletteTone | undefined;
 type ProviderProps = {
     children: ReactNode;
     defaults?: PaperDefaults;
@@ -324,6 +342,15 @@ type ProviderProps = {
     onChange?: (settings: ThemeSettings) => void;
     onNavBarChange?: (color: string, dark: boolean) => void;
     onReady?: () => void;
+    /** Maps each palette color (primary, secondary and tertiary, after the harmony rotation) before the
+     * theme derives anything from it, for an app that wants its whole palette toned, e.g.
+     * `getChalkboardColor` (marker in light mode, chalk in dark). The stored seed stays the player's
+     * raw pick, so nothing compounds on save, and `AutoPalettePicker` previews its swatches through
+     * the same tone. onColor/onContainer follow the toned colors by the usual light/dark split, so a
+     * tone decides their polarity: chalk's luminance floor is what gives its pastels dark text.
+     * Signal colors (success, warning, danger, MD3's error) are never toned. Must be referentially stable (a module-level
+     * function): the theme recomputes whenever it changes. Omit for the untoned palette. */
+    paletteTone?: PaletteTone;
     /** Injects react-native-reanimated so `<Dialog animatedStyle={...}>` (e.g. from `useAnimatedStyle()`) can animate its card on the UI thread. Pass `import Reanimated from 'react-native-reanimated'`; omit to keep Dialog's `animatedStyle` prop a no-op. */
     reanimated?: ReanimatedModule;
     /** Renders React Native's `StatusBar`, styled from the theme (here and in `Appbar.Header`). Default true. Pass false
@@ -334,7 +361,7 @@ type ProviderProps = {
     statusBarProps?: StatusBarProps;
     style?: StyleProp<ViewStyle>;
 };
-declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, maskedView, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBar, statusBarProps, style }: ProviderProps): react.JSX.Element;
+declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, maskedView, navigationBar, onChange, onNavBarChange, onReady, paletteTone, reanimated, statusBar, statusBarProps, style }: ProviderProps): react.JSX.Element;
 
 declare const useAutoPaperTheme: () => AutoPaperTheme;
 
@@ -391,8 +418,19 @@ type ColorRoles = {
 };
 declare const getColorRoles: (base: string, surface: string, containerAlpha?: number) => ColorRoles;
 
+declare const getLuminance: (value: string) => number;
+declare const getContrastRatio: (a: string, b: string) => number;
+
 declare const getHex: (value: string) => string | null;
 
+type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+};
+declare const getOklch: (value: string) => Oklch | null;
+declare const getOklchHex: ({ l, c, h }: Oklch) => string;
+
 type RGB = {
     r: number;
     g: number;
@@ -413,4 +451,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, FadingScrollView, type FadingScrollViewProps, HarmonyPicker, IconButton, type IconButtonProps, type MaskedViewModule, Menu, type MenuProps, PalettePicker, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SCROLL_FADE_HEIGHT, 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, useMaskedViewModule, useNavBarContext, usePaperDefaults, useReanimatedModule, useThemeBridgeProps, useThemeSettings };
+export { Appbar, type AppearanceIcons, AppearancePicker, AutoAppearancePicker, AutoPalettePicker, type AutoPaperTheme, BlurView, type BlurViewProps, BottomNavigation, Button, type ChalkboardToneOptions, Chip, type ChipProps, type ColorHarmony, ColorPicker, type ColorRoles, Dialog, type DialogProps, type ExpoBlurModule, type ExpoNavigationBarModule, FAB, FadingScrollView, type FadingScrollViewProps, HarmonyPicker, IconButton, type IconButtonProps, type MaskedViewModule, Menu, type MenuProps, type Oklch, PalettePicker, type PaletteTone, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SCROLL_FADE_HEIGHT, SEMANTIC_BASE_COLORS, type SeedColor, type SemanticColorRoles, TextInput, type ThemeAppearance, type ThemeBridgeProps, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createChalkboardTone, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getChalkboardColor, getColorRoles, getContrastColor, getContrastRatio, getHex, getLuminance, getOklch, getOklchHex, getRgb, getThirdColor, getTintTextColor, getTonalColor, getTriadicPalette, isDarkColor, resolveSeedColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useAutoPaperTheme, useBlur, useBlurModule, useComputedTheme, useMaskedViewModule, useNavBarContext, usePaletteTone, usePaperDefaults, useReanimatedModule, useThemeBridgeProps, useThemeSettings };

package/dist/index.d.ts

@@ -22,6 +22,22 @@ declare const Appbar: {
     BackAction: react_native_paper_lib_typescript_utils_forwardRef.ForwardRefComponent<react_native.View, react_native_paper.AppbarBackActionProps>;
 };
 
+type PaletteTone = (color: string, dark: boolean) => string;
+type ChalkboardToneOptions = {
+    marker?: {
+        maxLightness?: number;
+        chroma?: number;
+    };
+    chalk?: {
+        lightness?: number;
+        lift?: number;
+        chroma?: number;
+        minLuminance?: number;
+    };
+};
+declare const createChalkboardTone: (options?: ChalkboardToneOptions) => PaletteTone;
+declare const getChalkboardColor: PaletteTone;
+
 type ColorHarmony = 'triadic' | 'split-complementary' | 'analogous' | 'square' | 'complementary' | 'double-split';
 type TriadicPalette = {
     primary: string;
@@ -53,7 +69,7 @@ type SemanticColorRoles = {
 type AutoPaperTheme = Omit<MD3Theme, 'colors'> & {
     colors: MD3Theme['colors'] & SemanticColorRoles;
 };
-declare function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony?: ColorHarmony): AutoPaperTheme | null;
+declare function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony?: ColorHarmony, paletteTone?: PaletteTone): AutoPaperTheme | null;
 
 type AppearanceIcons = Partial<Record<ThemeAppearance, string>>;
 type Props$5 = {
@@ -96,8 +112,9 @@ type Props$2 = {
     weights?: PaletteWeights;
     colors?: SeedColor[];
     blur?: boolean;
+    previewColor?: (color: string) => string;
 };
-declare const PalettePicker: ({ value, onChange, harmony, onHarmonyChange, weights, colors, blur: blurProp }: Props$2) => react.JSX.Element;
+declare const PalettePicker: ({ value, onChange, harmony, onHarmonyChange, weights, colors, blur: blurProp, previewColor }: Props$2) => react.JSX.Element;
 
 type Props$1 = {
     weights?: PaletteWeights;
@@ -305,6 +322,7 @@ declare const useNavBarContext: () => NavBarContextType;
 declare const useBlurModule: () => ExpoBlurModule | undefined;
 declare const useReanimatedModule: () => ReanimatedModule | undefined;
 declare const useMaskedViewModule: () => MaskedViewModule | undefined;
+declare const usePaletteTone: () => PaletteTone | undefined;
 type ProviderProps = {
     children: ReactNode;
     defaults?: PaperDefaults;
@@ -324,6 +342,15 @@ type ProviderProps = {
     onChange?: (settings: ThemeSettings) => void;
     onNavBarChange?: (color: string, dark: boolean) => void;
     onReady?: () => void;
+    /** Maps each palette color (primary, secondary and tertiary, after the harmony rotation) before the
+     * theme derives anything from it, for an app that wants its whole palette toned, e.g.
+     * `getChalkboardColor` (marker in light mode, chalk in dark). The stored seed stays the player's
+     * raw pick, so nothing compounds on save, and `AutoPalettePicker` previews its swatches through
+     * the same tone. onColor/onContainer follow the toned colors by the usual light/dark split, so a
+     * tone decides their polarity: chalk's luminance floor is what gives its pastels dark text.
+     * Signal colors (success, warning, danger, MD3's error) are never toned. Must be referentially stable (a module-level
+     * function): the theme recomputes whenever it changes. Omit for the untoned palette. */
+    paletteTone?: PaletteTone;
     /** Injects react-native-reanimated so `<Dialog animatedStyle={...}>` (e.g. from `useAnimatedStyle()`) can animate its card on the UI thread. Pass `import Reanimated from 'react-native-reanimated'`; omit to keep Dialog's `animatedStyle` prop a no-op. */
     reanimated?: ReanimatedModule;
     /** Renders React Native's `StatusBar`, styled from the theme (here and in `Appbar.Header`). Default true. Pass false
@@ -334,7 +361,7 @@ type ProviderProps = {
     statusBarProps?: StatusBarProps;
     style?: StyleProp<ViewStyle>;
 };
-declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, maskedView, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBar, statusBarProps, style }: ProviderProps): react.JSX.Element;
+declare function Provider({ children, defaults, expoBlur, fontFamily, initialValue, maskedView, navigationBar, onChange, onNavBarChange, onReady, paletteTone, reanimated, statusBar, statusBarProps, style }: ProviderProps): react.JSX.Element;
 
 declare const useAutoPaperTheme: () => AutoPaperTheme;
 
@@ -391,8 +418,19 @@ type ColorRoles = {
 };
 declare const getColorRoles: (base: string, surface: string, containerAlpha?: number) => ColorRoles;
 
+declare const getLuminance: (value: string) => number;
+declare const getContrastRatio: (a: string, b: string) => number;
+
 declare const getHex: (value: string) => string | null;
 
+type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+};
+declare const getOklch: (value: string) => Oklch | null;
+declare const getOklchHex: ({ l, c, h }: Oklch) => string;
+
 type RGB = {
     r: number;
     g: number;
@@ -413,4 +451,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, FadingScrollView, type FadingScrollViewProps, HarmonyPicker, IconButton, type IconButtonProps, type MaskedViewModule, Menu, type MenuProps, PalettePicker, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SCROLL_FADE_HEIGHT, 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, useMaskedViewModule, useNavBarContext, usePaperDefaults, useReanimatedModule, useThemeBridgeProps, useThemeSettings };
+export { Appbar, type AppearanceIcons, AppearancePicker, AutoAppearancePicker, AutoPalettePicker, type AutoPaperTheme, BlurView, type BlurViewProps, BottomNavigation, Button, type ChalkboardToneOptions, Chip, type ChipProps, type ColorHarmony, ColorPicker, type ColorRoles, Dialog, type DialogProps, type ExpoBlurModule, type ExpoNavigationBarModule, FAB, FadingScrollView, type FadingScrollViewProps, HarmonyPicker, IconButton, type IconButtonProps, type MaskedViewModule, Menu, type MenuProps, type Oklch, PalettePicker, type PaletteTone, type PaletteWeights, type PaperDefaults, Provider, type ProviderProps, type RGB, type ReanimatedModule, SCROLL_FADE_HEIGHT, SEMANTIC_BASE_COLORS, type SeedColor, type SemanticColorRoles, TextInput, type ThemeAppearance, type ThemeBridgeProps, type ThemeSettings, ThemeSettingsContext, type ThemeSettingsContextType, type ThemeState, type TriadicPalette, createChalkboardTone, createThemeReducer, defaultColors, defaultThemeSettings, getBlendedColor, getChalkboardColor, getColorRoles, getContrastColor, getContrastRatio, getHex, getLuminance, getOklch, getOklchHex, getRgb, getThirdColor, getTintTextColor, getTonalColor, getTriadicPalette, isDarkColor, resolveSeedColor, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer, useAutoPaperTheme, useBlur, useBlurModule, useComputedTheme, useMaskedViewModule, useNavBarContext, usePaletteTone, usePaperDefaults, useReanimatedModule, useThemeBridgeProps, useThemeSettings };