@rific/auto-paper 0.8.0 → 0.9.0

package/src/useComputedTheme.ts

@@ -4,25 +4,32 @@ import { MD3DarkTheme, MD3LightTheme, MD3Theme } from 'react-native-paper'
 
 import { getBlendedColor } from './utils/getBlendedColor'
 import { getColorRoles } from './utils/getColorRoles'
-import { type ColorHarmony, getTriadicPalette } from './utils/getTriadicPalette'
+import { getHex } from './utils/getHex'
+import { getRgb } from './utils/getRgb'
+import { type ColorHarmony, getTriadicPalette, type TriadicPalette } from './utils/getTriadicPalette'
+
+function normalizeExplicitColor(value: string): string {
+  if (!getRgb(value)) throw new Error(`Invalid color format: ${value}`)
+  return getHex(value) ?? value
+}
 
 export type ThemeAppearance = 'system' | 'light' | 'dark'
 
-// Fixed hue/saturation, like MD3's own `error` role (see LightTheme.tsx/DarkTheme.tsx — error is a
+// Fixed hue/saturation, like MD3's own `error` role (see LightTheme.tsx/DarkTheme.tsx: error is a
 // static Material palette constant, never derived from the seed color either). A "warning" amber
 // shouldn't drift toward the app's accent hue any more than the built-in danger red does; only
 // lightness adapts per light/dark mode below, via getColorRoles. #A15C00 (not the more obvious
 // goldenrod #B8860B) was picked because its onWarning text fails WCAG AA (3.05:1) against the base
-// color itself — see getColorRoles.test.ts's "onColor" caveat: the onColor heuristic (isDarkColor-
+// color itself; see getColorRoles.test.ts's "onColor" caveat: the onColor heuristic (isDarkColor-
 // based binary lightness pick) isn't a verified guarantee like onContainer is, so the base hex
 // itself has to be chosen to land safely, not assumed to.
 //
 // `danger` is deliberately a separate namespace from MD3's own `error` (below, untouched) rather
-// than a fourth tier folded into it — react-native-paper's own components (TextInput's error state,
+// than a fourth tier folded into it: react-native-paper's own components (TextInput's error state,
 // HelperText, Badge) read theme.colors.error/onError directly, so a consumer that wants a
 // getColorRoles-derived "high severity" color without changing what those components render needs
 // its own name. #B00020 already clears WCAG AA for both onDanger-vs-danger (6.16:1) and
-// dangerContainer/onDangerContainer (12–17:1 across modes) — verified the same way as warning's
+// dangerContainer/onDangerContainer (12–17:1 across modes), verified the same way as warning's
 // base above.
 export const SEMANTIC_BASE_COLORS = {
   success: '#2E7D32',
@@ -46,13 +53,20 @@ export type SemanticColorRoles = {
 }
 
 // MD3Theme's `colors` is a closed `type` (not an `interface`), so it can't be widened via
-// TypeScript's declare-module augmentation — this is the extension point instead, meant to be used
+// TypeScript's declare-module augmentation: this is the extension point instead, meant to be used
 // 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, harmony: ColorHarmony = 'split-complementary'): AutoPaperTheme | null {
+export function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony: ColorHarmony = 'split-complementary'): AutoPaperTheme | null {
   const [theme, setTheme] = useState<AutoPaperTheme | null>(null)
 
+  // Destructured to primitives (rather than depending on `color` itself below) so that passing a
+  // fresh `{ primary, secondary, tertiary }` object literal inline on every render, the natural
+  // way to use this mode, doesn't retrigger computeTheme unless a field actually changed.
+  const primaryInput = typeof color === 'string' ? color : color.primary
+  const secondaryInput = typeof color === 'string' ? null : color.secondary
+  const tertiaryInput = typeof color === 'string' ? null : color.tertiary
+
   const computeTheme = useCallback(() => {
     let resolved: string | null | undefined = appearance
     if (resolved === 'system') resolved = Appearance.getColorScheme()
@@ -61,7 +75,7 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string, har
     const surface = base.colors.surface
 
     // error/onError/errorContainer/onErrorContainer are deliberately left untouched below (not run
-    // through getColorRoles like success/warning/primary/secondary/tertiary are) — they're a fixed,
+    // through getColorRoles like success/warning/primary/secondary/tertiary are): they're a fixed,
     // Google-verified Material palette that react-native-paper's own components (TextInput's error
     // state, HelperText, Badge) read directly, so re-deriving them would change form-validation
     // colors across every consuming app and risk diverging from a contrast guarantee that's already
@@ -90,7 +104,7 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string, har
       }
     }
 
-    const palette = getTriadicPalette(color, harmony)
+    const palette: TriadicPalette = secondaryInput !== null && tertiaryInput !== null ? { primary: normalizeExplicitColor(primaryInput), secondary: normalizeExplicitColor(secondaryInput), tertiary: normalizeExplicitColor(tertiaryInput) } : getTriadicPalette(primaryInput, harmony)
 
     const primaryRoles = getColorRoles(palette.primary, surface)
     _theme.colors.primary = primaryRoles.color
@@ -110,13 +124,13 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string, har
     _theme.colors.tertiaryContainer = tertiaryRoles.container
     _theme.colors.onTertiaryContainer = tertiaryRoles.onContainer
 
-    const blended = getBlendedColor(color, palette.secondary, 0.5)
+    const blended = getBlendedColor(palette.primary, palette.secondary, 0.5)
     const tintSurface = (alpha: number) => getBlendedColor(blended, surface, alpha)
 
     _theme.colors.background = base.dark ? '#0F0F0F' : '#F0F0F0'
     _theme.colors.surface = surface
     _theme.colors.surfaceVariant = tintSurface(0.2)
-    _theme.colors.outline = getBlendedColor(color, base.colors.outline, 0.45)
+    _theme.colors.outline = getBlendedColor(palette.primary, base.colors.outline, 0.45)
 
     const grey = base.dark ? '#424242' : '#c2c2c2'
     const blendedGrey = getBlendedColor(blended, grey, 0.05)
@@ -130,7 +144,7 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string, har
     }
 
     setTheme(_theme)
-  }, [appearance, color, harmony])
+  }, [appearance, primaryInput, secondaryInput, tertiaryInput, harmony])
 
   useEffect(() => {
     computeTheme()

package/src/useSwatchGrid.ts

@@ -2,7 +2,7 @@ import { useState } from 'react'
 import type { LayoutChangeEvent } from 'react-native'
 
 // Fixed column count so the swatch grid always fills complete rows, regardless of dialog width
-// (phone vs tablet vs web) — sizing the swatches to fit, rather than wrapping fixed-size swatches
+// (phone vs tablet vs web): sizing the swatches to fit, rather than wrapping fixed-size swatches
 // and hoping the total divides evenly into whatever column count the width happens to produce.
 export const SWATCH_GRID_COLUMNS = 5
 export const SWATCH_GRID_GAP = 12

package/src/useTheme.ts

@@ -3,7 +3,7 @@ import { useTheme as usePaperTheme } from 'react-native-paper'
 import type { AutoPaperTheme } from './useComputedTheme'
 
 // react-native-paper's own useTheme is generic (`useTheme<T = MD3Theme>()`) specifically so
-// consumers can extend MD3Theme with their own fields — this is that extension point, so any
+// consumers can extend MD3Theme with their own fields: this is that extension point, so any
 // component can read theme.colors.success/warning (and their onX/Container variants) with full
 // type safety, without redeclaring the type parameter at every call site. Named distinctly from
 // react-native-paper's own `useTheme` (not re-exported under the same name) to avoid the two being

package/src/utils/getColorRoles.ts

@@ -13,7 +13,7 @@ export type ColorRoles = {
 // 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
 // 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
+// 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 => {

package/src/utils/getSwatchContrast.ts

@@ -5,7 +5,7 @@ const RING_WIDTH = 1
 // The selected swatch trades that outline for a thicker one in a contrasting colour.
 const SELECTED_RING_WIDTH = 3
 
-// Colour for content sitting directly on a fill of `color` — a check mark or a 20px icon. Plain
+// Colour for content sitting directly on a fill of `color` (a check mark or a 20px icon). Plain
 // white/black rather than a tinted tone from getTonalColor, because this has to stay legible on
 // fully saturated fills and on pure black/white alike.
 export const getContrastColor = (color: string): string => (isDarkColor(color) ? '#ffffff' : '#000000')
@@ -14,7 +14,7 @@ export const getContrastColor = (color: string): string => (isDarkColor(color) ?
 // things:
 //
 // - Unselected: separate the swatch from the *surface* it sits on. A white swatch on a light
-//   dialog and a black swatch on a dark one are otherwise edgeless — invisible, not just subtle.
+//   dialog and a black swatch on a dark one are otherwise edgeless: invisible, not just subtle.
 //   The theme's outline colour tracks the surface, so it works in both appearances.
 // - Selected: read as a marker against the *swatch's own fill*. A hardcoded white ring vanished on
 //   the white swatch, so picking white gave no feedback that anything had been picked.

package/src/utils/getThirdColor.ts

@@ -0,0 +1,103 @@
+import { getHex } from './getHex'
+import { getRgb } from './getRgb'
+
+type HSL = { h: number; s: number; l: number }
+
+function rgbToHsl(r: number, g: number, b: number): HSL {
+  r /= 255
+  g /= 255
+  b /= 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  const delta = max - min
+
+  let h = 0
+  if (delta !== 0) {
+    if (max === r) h = ((g - b) / delta) % 6
+    else if (max === g) h = (b - r) / delta + 2
+    else h = (r - g) / delta + 4
+    h = (h * 60 + 360) % 360
+  }
+
+  const l = (max + min) / 2
+  const s = delta === 0 ? 0 : delta / (1 - Math.abs(2 * l - 1))
+
+  return { h, s, l }
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+  const c = (1 - Math.abs(2 * l - 1)) * s
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = l - c / 2
+
+  let r = 0
+  let g = 0
+  let b = 0
+
+  if (h < 60) {
+    r = c
+    g = x
+    b = 0
+  } else if (h < 120) {
+    r = x
+    g = c
+    b = 0
+  } else if (h < 180) {
+    r = 0
+    g = c
+    b = x
+  } else if (h < 240) {
+    r = 0
+    g = x
+    b = c
+  } else if (h < 300) {
+    r = x
+    g = 0
+    b = c
+  } else {
+    r = c
+    g = 0
+    b = x
+  }
+
+  const toInt = (value: number) => Math.round((value + m) * 255)
+  return getHex(`rgb(${toInt(r)}, ${toInt(g)}, ${toInt(b)})`) ?? '#000000'
+}
+
+const toRad = (deg: number) => (deg * Math.PI) / 180
+const toDeg = (rad: number) => (rad * 180) / Math.PI
+
+// The hue maximally distant from both inputs: the midpoint of the longer arc between them.
+// Falls back to a perpendicular hue when the inputs are exact complements, since both arcs are
+// equal length there, so every point on the perpendicular bisector is equally valid.
+function thirdHue(hA: number, hB: number): number {
+  const x = Math.cos(toRad(hA)) + Math.cos(toRad(hB))
+  const y = Math.sin(toRad(hA)) + Math.sin(toRad(hB))
+
+  if (Math.abs(x) < 1e-9 && Math.abs(y) < 1e-9) return (hA + 90) % 360
+
+  const meanHue = (toDeg(Math.atan2(y, x)) + 360) % 360
+  return (meanHue + 180) % 360
+}
+
+// Given two arbitrary colors, derives a third that's maximally distinct in hue from both, useful
+// for a neutral element that shouldn't visually clash with either. Saturation and lightness are
+// averaged from the two inputs.
+export function getThirdColor(colorA: string, colorB: string): string {
+  const rgbA = getRgb(colorA)
+  const rgbB = getRgb(colorB)
+  if (!rgbA) throw new Error(`Invalid color format: ${colorA}`)
+  if (!rgbB) throw new Error(`Invalid color format: ${colorB}`)
+
+  const hslA = rgbToHsl(rgbA.r, rgbA.g, rgbA.b)
+  const hslB = rgbToHsl(rgbB.r, rgbB.g, rgbB.b)
+
+  const h = thirdHue(hslA.h, hslB.h)
+  const s = (hslA.s + hslB.s) / 2
+  const l = (hslA.l + hslB.l) / 2
+
+  return hslToHex(h, s, l)
+}
+
+export default getThirdColor