@rific/auto-paper 0.13.3 → 0.14.0

package/src/useComputedTheme.ts

@@ -3,6 +3,7 @@ import { Appearance } from 'react-native'
 import { MD3DarkTheme, MD3LightTheme, MD3Theme } from 'react-native-paper'
 
 import { getBlendedColor } from './utils/getBlendedColor'
+import type { PaletteTone } from './utils/getChalkboardColor'
 import { getColorRoles } from './utils/getColorRoles'
 import { getHex } from './utils/getHex'
 import { getRgb } from './utils/getRgb'
@@ -57,7 +58,9 @@ export type SemanticColorRoles = {
 // with react-native-paper's own `useTheme<T>()` generic (see useTheme.ts's useAutoPaperTheme).
 export type AutoPaperTheme = Omit<MD3Theme, 'colors'> & { colors: MD3Theme['colors'] & SemanticColorRoles }
 
-export function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony: ColorHarmony = 'split-complementary'): AutoPaperTheme | null {
+// `paletteTone` (optional, see Provider's prop of the same name) maps each resolved palette color
+// before anything is derived from it. It must be referentially stable: it's a dependency.
+export function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony: ColorHarmony = 'split-complementary', paletteTone?: PaletteTone): AutoPaperTheme | null {
   const [theme, setTheme] = useState<AutoPaperTheme | null>(null)
 
   // Destructured to primitives (rather than depending on `color` itself below) so that passing a
@@ -104,7 +107,12 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string | Tr
       }
     }
 
-    const palette: TriadicPalette = secondaryInput !== null && tertiaryInput !== null ? { primary: normalizeExplicitColor(primaryInput), secondary: normalizeExplicitColor(secondaryInput), tertiary: normalizeExplicitColor(tertiaryInput) } : getTriadicPalette(primaryInput, harmony)
+    const untoned: TriadicPalette = secondaryInput !== null && tertiaryInput !== null ? { primary: normalizeExplicitColor(primaryInput), secondary: normalizeExplicitColor(secondaryInput), tertiary: normalizeExplicitColor(tertiaryInput) } : getTriadicPalette(primaryInput, harmony)
+    // Toned per member, after the harmony rotation: a tone that moves lightness doesn't commute
+    // with rotating hue, so toning the seed first would give secondary and tertiary colors the
+    // pickers never showed. Everything below (roles, containers, outline, surfaceVariant,
+    // elevation) derives from the toned palette; the semantic roles above never pass through it.
+    const palette: TriadicPalette = paletteTone ? { primary: paletteTone(untoned.primary, base.dark), secondary: paletteTone(untoned.secondary, base.dark), tertiary: paletteTone(untoned.tertiary, base.dark) } : untoned
 
     const primaryRoles = getColorRoles(palette.primary, surface)
     _theme.colors.primary = primaryRoles.color
@@ -144,7 +152,7 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string | Tr
     }
 
     setTheme(_theme)
-  }, [appearance, primaryInput, secondaryInput, tertiaryInput, harmony])
+  }, [appearance, primaryInput, secondaryInput, tertiaryInput, harmony, paletteTone])
 
   useEffect(() => {
     // eslint-disable-next-line react-hooks/set-state-in-effect -- intentional: first render must stay theme-less (README's onReady/splash-screen contract) and Appearance must not be read during render (SSR/hydration risk)

package/src/utils/getChalkboardColor.ts

@@ -0,0 +1,77 @@
+import { getLuminance } from './getContrastRatio'
+import { getOklch, getOklchHex } from './getOklch'
+
+// What Provider's `paletteTone` takes: a pure function from one palette color (primary, secondary
+// or tertiary, after the harmony rotation) and the resolved appearance to the color the theme
+// should actually use. It must be referentially stable (a module-level function, not an inline
+// arrow), since the theme recomputes whenever it changes.
+export type PaletteTone = (color: string, dark: boolean) => string
+
+export type ChalkboardToneOptions = {
+  // Light mode, marker on a whiteboard: deep ink, never neon. A color lighter than `maxLightness`
+  // (OKLCH lightness) is brought down to it, and every color keeps `chroma` of its chroma.
+  marker?: { maxLightness?: number; chroma?: number }
+  // Dark mode, chalk on a chalkboard: pastel at an even value. Lightness moves `lift` of the way
+  // toward `lightness` (never darker), chroma is scaled by `chroma`, and then lightness rises until
+  // the color's WCAG luminance reaches `minLuminance`, so it reads as chalk on the board and takes
+  // dark text when it's a fill (0 turns that floor off).
+  chalk?: { lightness?: number; lift?: number; chroma?: number; minLuminance?: number }
+}
+
+const MARKER = { maxLightness: 0.6, chroma: 0.85 }
+const CHALK = { lightness: 0.86, lift: 0.5, chroma: 0.8, minLuminance: 0.5 }
+
+// The pickers tone 60 colors per render (20 swatches, three wedges each), and chalk's luminance
+// floor is a search, so results are cached per tone. Bounded, since a picker only ever shows a
+// few dozen distinct colors.
+const CACHE_LIMIT = 512
+
+// A PaletteTone for apps that want their palette muted like marker and chalk: a little in light
+// mode (deeper, slightly less chroma), more in dark mode (pastel). Hue never moves, so a palette
+// keeps its colors, only toned down. Signal colors (success, warning, danger, error) never pass
+// through a tone. Pass the result straight to Provider's `paletteTone`; `getChalkboardColor` below
+// is this with the defaults.
+export const createChalkboardTone = (options: ChalkboardToneOptions = {}): PaletteTone => {
+  const marker = { ...MARKER, ...options.marker }
+  const chalk = { ...CHALK, ...options.chalk }
+  const cache = new Map<string, string>()
+
+  const toMarker = (color: string) => {
+    const oklch = getOklch(color)
+    if (!oklch) return color
+    return getOklchHex({ l: Math.min(oklch.l, marker.maxLightness), c: oklch.c * marker.chroma, h: oklch.h })
+  }
+
+  const toChalk = (color: string) => {
+    const oklch = getOklch(color)
+    if (!oklch) return color
+    const c = oklch.c * chalk.chroma
+    const lifted = oklch.l < chalk.lightness ? oklch.l + (chalk.lightness - oklch.l) * chalk.lift : oklch.l
+    const result = getOklchHex({ l: lifted, c, h: oklch.h })
+    if (getLuminance(result) >= chalk.minLuminance) return result
+    // Luminance rises with lightness at a fixed hue, so the lowest lightness that clears the floor
+    // is a bisection between the lifted lightness and white.
+    let low = lifted
+    let high = 1
+    for (let i = 0; i < 20; i++) {
+      const mid = (low + high) / 2
+      if (getLuminance(getOklchHex({ l: mid, c, h: oklch.h })) >= chalk.minLuminance) high = mid
+      else low = mid
+    }
+    return getOklchHex({ l: high, c, h: oklch.h })
+  }
+
+  return (color, dark) => {
+    const key = `${dark ? 'd' : 'l'}${color}`
+    const cached = cache.get(key)
+    if (cached !== undefined) return cached
+    const result = dark ? toChalk(color) : toMarker(color)
+    if (cache.size >= CACHE_LIMIT) cache.clear()
+    cache.set(key, result)
+    return result
+  }
+}
+
+export const getChalkboardColor: PaletteTone = createChalkboardTone()
+
+export default getChalkboardColor

package/src/utils/getColorRoles.ts

@@ -1,4 +1,5 @@
 import { getBlendedColor } from './getBlendedColor'
+import { getContrastRatio } from './getContrastRatio'
 import { getTonalColor } from './getTonalColor'
 import { isDarkColor } from './isDarkColor'
 
@@ -9,18 +10,28 @@ export type ColorRoles = {
   onContainer: string
 }
 
+// The lowest contrast light text may have on a color before onColor turns dark instead. The fleet's
+// colored buttons have always had light text, and keep it wherever it reads about as well as it does on
+// their reds, blues and greens (2.8 to 3.1:1 for the picker's Red, Blue, Emerald and Coral); only
+// colors light enough that it fades take dark text: the picker's Lime, Amber, Cyan and Sky (Yellow
+// already did). Judging by the color's own darkness alone gave those near-white text that all but
+// vanished (Jay, 2026-10-19: 1.96:1 on a light green Ready button).
+const MIN_LIGHT_ON_COLOR_CONTRAST = 2.5
+
 // The MD3 "color / onColor / container / onContainer" quadruple, generalized from the math
 // useComputedTheme already uses for primary/secondary/tertiary: onColor is tuned to sit on the
-// vivid color itself, container is base blended toward the theme's real surface (so it inherits
+// vivid color itself (light while it reads, MIN_LIGHT_ON_COLOR_CONTRAST, else dark), container is
+// base blended toward the theme's real surface (so it inherits
 // that surface's actual lightness rather than a fixed light/dark guess), and onContainer is tuned
 // against the *computed* container rather than a light/dark assumption, so it stays readable
 // whatever surface color it's handed. onContainer also reads safely directly on `surface` itself
 // (not just on `container`), since container is only lightly blended toward it.
 export const getColorRoles = (base: string, surface: string, containerAlpha = 0.15): ColorRoles => {
   const container = getBlendedColor(base, surface, containerAlpha)
+  const lightOnColor = getTonalColor(base, 0.95)
   return {
     color: base,
-    onColor: getTonalColor(base, isDarkColor(base) ? 0.95 : 0.08),
+    onColor: getContrastRatio(lightOnColor, base) >= MIN_LIGHT_ON_COLOR_CONTRAST ? lightOnColor : getTonalColor(base, 0.08),
     container,
     onContainer: getTonalColor(base, isDarkColor(container) ? 0.92 : 0.12)
   }

package/src/utils/getContrastRatio.ts

@@ -0,0 +1,20 @@
+import { getRgb } from './getRgb'
+
+// WCAG 2's relative luminance (0 for black, 1 for white): the same formula isDarkColor applies.
+export const getLuminance = (value: string): number => {
+  const rgb = getRgb(value)
+  if (!rgb) return 0
+  const [r, g, b] = [rgb.r, rgb.g, rgb.b].map((channel) => {
+    const c = channel / 255
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+// WCAG 2's contrast ratio between two colors, 1 (identical) to 21 (black on white). Order doesn't matter.
+export const getContrastRatio = (a: string, b: string): number => {
+  const [lighter, darker] = [getLuminance(a), getLuminance(b)].sort((x, y) => y - x)
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+export default getContrastRatio

package/src/utils/getOklch.ts

@@ -0,0 +1,68 @@
+import { getRgb } from './getRgb'
+
+// OKLCH: lightness 0-1, chroma (0 for greys, about 0.37 at most inside sRGB), hue in degrees.
+export type Oklch = { l: number; c: number; h: number }
+
+type Triple = [number, number, number]
+
+const toLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+const toGamma = (c: number) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055)
+
+// Björn Ottosson's OKLab matrices (https://bottosson.github.io/posts/oklab/), from linear sRGB.
+const linearToOklab = ([r, g, b]: Triple): Triple => {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s]
+}
+
+const oklabToLinear = ([L, a, b]: Triple): Triple => {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3
+  return [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s]
+}
+
+const inGamut = (rgb: Triple) => rgb.every((v) => v >= -1e-6 && v <= 1 + 1e-6)
+
+const clamp01 = (v: number) => Math.min(1, Math.max(0, v))
+
+const toHex = (rgb: Triple) =>
+  `#${rgb
+    .map((v) =>
+      Math.round(clamp01(toGamma(clamp01(v))) * 255)
+        .toString(16)
+        .padStart(2, '0')
+    )
+    .join('')}`
+
+// A color in OKLCH, the perceptual space where equal steps of lightness or chroma look equal
+// across hues (HSL's lightness doesn't: a yellow and a blue at the same HSL lightness differ
+// several-fold in brightness). Null for anything getRgb can't parse. Alpha is dropped.
+export const getOklch = (value: string): Oklch | null => {
+  const rgb = getRgb(value)
+  if (!rgb) return null
+  const [l, a, b] = linearToOklab([toLinear(rgb.r / 255), toLinear(rgb.g / 255), toLinear(rgb.b / 255)])
+  return { l, c: Math.hypot(a, b), h: ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360 }
+}
+
+// Back to a hex string. A color outside sRGB keeps its lightness and hue and loses only as much
+// chroma as it has to (a bisection on chroma, CSS Color 4's gamut mapping without its JND
+// shortcut), so lifting a saturated blue toward pastel can't swing it off toward purple.
+export const getOklchHex = ({ l, c, h }: Oklch): string => {
+  const lightness = Math.min(1, Math.max(0, l))
+  const radians = (h * Math.PI) / 180
+  const atChroma = (chroma: number) => oklabToLinear([lightness, chroma * Math.cos(radians), chroma * Math.sin(radians)])
+  const direct = atChroma(Math.max(0, c))
+  if (inGamut(direct)) return toHex(direct)
+  let low = 0
+  let high = c
+  for (let i = 0; i < 24; i++) {
+    const mid = (low + high) / 2
+    if (inGamut(atChroma(mid))) low = mid
+    else high = mid
+  }
+  return toHex(atChroma(low))
+}
+
+export default getOklch