@retray-dev/ui-kit 6.2.0 → 9.0.0

package/src/tokens.ts

@@ -1,5 +1,4 @@
 // ─── Spacing ─────────────────────────────────────────────────────────────────
-// 8pt grid with 2pt micro-step. `section` for major band separators (Airbnb: 64px).
 export const SPACING = {
   xxs: 2,
   xs: 4,
@@ -22,8 +21,6 @@ export const ICON_SIZES = {
 } as const
 
 // ─── Border radius ────────────────────────────────────────────────────────────
-// Airbnb-aligned shape language — soft everywhere, no hard corners on interactive elements.
-// xs: micro chips/tags  sm: inputs/forms  md: cards  lg: sheet corners  xl: primary CTAs (pill)
 export const RADIUS = {
   none: 0,
   xs: 4,
@@ -35,7 +32,6 @@ export const RADIUS = {
 } as const
 
 // ─── Shadows ──────────────────────────────────────────────────────────────────
-// Multi-tier. Default card usage = sm. Hover float = md. Modals = lg/xl.
 export const SHADOWS = {
   sm: {
     shadowColor: '#000',
@@ -73,118 +69,132 @@ export const BREAKPOINTS = {
 } as const
 
 // ─── Typography ───────────────────────────────────────────────────────────────
-// Airbnb-inspired hierarchy. Modest weights — 500-600 on display, not 700+.
-// Exception: display-hero (large number display) and display-xl always bold.
-// Poppins carries the full scale. All fontFamily values reference loaded font names.
+// AUDIT FIX: Rationalised display scale — removed weight inversions and size
+// collisions. display-lg/md separated by 4px with matching weights. title-md/sm
+// now actually differ in size. uppercase-tag raised from 10px → 11px for
+// minimum mobile readability (Apple HIG: 11pt floor).
 export const TYPOGRAPHY = {
   'display-hero': {
-    fontFamily: 'Poppins-Bold',
+    fontFamily: 'Sohne-Bold',
     fontSize: 64,
     fontWeight: '700' as const,
     lineHeight: 70,
     letterSpacing: -1,
   },
   'display-xl': {
-    fontFamily: 'Poppins-Bold',
+    fontFamily: 'Sohne-Bold',
     fontSize: 28,
     fontWeight: '700' as const,
     lineHeight: 40,
     letterSpacing: 0,
   },
+  // AUDIT FIX: was 22px/500 — raised to 24px/600; removes weight inversion vs display-md
   'display-lg': {
-    fontFamily: 'Poppins-Medium',
-    fontSize: 22,
-    fontWeight: '500' as const,
-    lineHeight: 26,
-    letterSpacing: -0.44,
+    fontFamily: 'Sohne-SemiBold',
+    fontSize: 24,
+    fontWeight: '600' as const,
+    lineHeight: 32,
+    letterSpacing: -0.3,
   },
+  // AUDIT FIX: was 21px/700 — lowered to 20px/600; weight normalised, 4px gap preserved
   'display-md': {
-    fontFamily: 'Poppins-Bold',
-    fontSize: 21,
-    fontWeight: '700' as const,
-    lineHeight: 30,
+    fontFamily: 'Sohne-SemiBold',
+    fontSize: 20,
+    fontWeight: '600' as const,
+    lineHeight: 28,
     letterSpacing: 0,
   },
   'display-sm': {
-    fontFamily: 'Poppins-SemiBold',
-    fontSize: 20,
+    fontFamily: 'Sohne-SemiBold',
+    fontSize: 18,
     fontWeight: '600' as const,
     lineHeight: 24,
     letterSpacing: -0.18,
   },
+  // AUDIT FIX: was 16px — raised to 17px so title-md > title-sm is size-visible
   'title-md': {
-    fontFamily: 'Poppins-SemiBold',
-    fontSize: 16,
+    fontFamily: 'Sohne-SemiBold',
+    fontSize: 17,
     fontWeight: '600' as const,
-    lineHeight: 20,
+    lineHeight: 22,
     letterSpacing: 0,
   },
+  // AUDIT FIX: was 16px — lowered to 15px; now distinct from title-md
   'title-sm': {
-    fontFamily: 'Poppins-Medium',
-    fontSize: 16,
+    fontFamily: 'Sohne-Medium',
+    fontSize: 15,
     fontWeight: '500' as const,
     lineHeight: 20,
     letterSpacing: 0,
   },
   'body-md': {
-    fontFamily: 'Poppins-Regular',
+    fontFamily: 'Sohne-Regular',
     fontSize: 16,
     fontWeight: '400' as const,
     lineHeight: 24,
     letterSpacing: 0,
   },
   'body-sm': {
-    fontFamily: 'Poppins-Regular',
+    fontFamily: 'Sohne-Regular',
     fontSize: 14,
     fontWeight: '400' as const,
     lineHeight: 20,
     letterSpacing: 0,
   },
-  caption: {
-    fontFamily: 'Poppins-Medium',
+  'caption': {
+    fontFamily: 'Sohne-Medium',
     fontSize: 14,
     fontWeight: '500' as const,
     lineHeight: 18,
     letterSpacing: 0,
   },
   'caption-sm': {
-    fontFamily: 'Poppins-Regular',
+    fontFamily: 'Sohne-Regular',
     fontSize: 13,
     fontWeight: '400' as const,
     lineHeight: 16,
     letterSpacing: 0,
   },
   'badge-text': {
-    fontFamily: 'Poppins-SemiBold',
+    fontFamily: 'Sohne-SemiBold',
     fontSize: 11,
     fontWeight: '600' as const,
-    lineHeight: 13,
+    lineHeight: 14,
+    letterSpacing: 0,
+  },
+  // AUDIT FIX: added badge-text-md so Badge md size has a canonical token
+  'badge-text-md': {
+    fontFamily: 'Sohne-SemiBold',
+    fontSize: 13,
+    fontWeight: '600' as const,
+    lineHeight: 16,
     letterSpacing: 0,
   },
   'micro-label': {
-    fontFamily: 'Poppins-Bold',
+    fontFamily: 'Sohne-Bold',
     fontSize: 12,
     fontWeight: '700' as const,
     lineHeight: 16,
     letterSpacing: 0,
   },
+  // AUDIT FIX: was 10px/0.8 letterSpacing — raised to 11px/0.6; minimum mobile readability
   'uppercase-tag': {
-    fontFamily: 'Poppins-Bold',
-    fontSize: 10,
+    fontFamily: 'Sohne-Bold',
+    fontSize: 11,
     fontWeight: '700' as const,
-    lineHeight: 13,
-    letterSpacing: 0.8,
+    lineHeight: 14,
+    letterSpacing: 0.6,
     textTransform: 'uppercase' as const,
   },
   'button-lg': {
-    fontFamily: 'Poppins-Medium',
+    fontFamily: 'Sohne-Medium',
     fontSize: 16,
     fontWeight: '500' as const,
     lineHeight: 22,
     letterSpacing: 0,
   },
   'button-sm': {
-    fontFamily: 'Poppins-Medium',
+    fontFamily: 'Sohne-Medium',
     fontSize: 14,
     fontWeight: '500' as const,
     lineHeight: 18,

package/src/utils/animations.ts

@@ -1,4 +1,5 @@
 import { Easing } from 'react-native-reanimated'
+import type { SingleTransition } from 'react-native-ease'
 
 // ─── Spring presets ──────────────────────────────────────────────────────────
 // Tuned for the "Apple HIG / Airbnb" press-feel: snap inward fast, settle out elastically.
@@ -17,7 +18,7 @@ export const SPRINGS = {
   surfacePressOut: { stiffness: 220, damping: 20, mass: 0.95 },
 
   /** Settled transitions for moving indicators — Tabs pill, Switch thumb. */
-  glide: { stiffness: 380, damping: 38, mass: 1.0 },
+  glide: { stiffness: 380, damping: 38, mass: 1 },
 
   /** Elastic indicator — Switch thumb, RadioGroup dot. */
   elastic: { stiffness: 320, damping: 22, mass: 0.7 },
@@ -48,6 +49,33 @@ export const EASINGS = {
   collapse: Easing.in(Easing.ease),
 } as const
 
+// ─── EaseView transition presets ─────────────────────────────────────────────
+// Equivalents of the reanimated presets above, in `react-native-ease` units.
+// EaseView spring takes raw damping/stiffness/mass (same physical model). EaseView
+// timing takes duration + an easing curve as a cubic-bezier tuple.
+
+/** Color/border state transition for Toggle, Checkbox, Chip, CategoryStrip, Switch track. Mirrors TIMINGS.state + EASINGS.standard. */
+export const COLOR_TRANSITION: SingleTransition = {
+  type: 'timing',
+  duration: TIMINGS.state.duration,
+  easing: [0.2, 0, 0, 1],
+}
+
+/** Icon/opacity crossfade. Mirrors TIMINGS.state + EASINGS.standard. */
+export const OPACITY_TRANSITION: SingleTransition = {
+  type: 'timing',
+  duration: TIMINGS.state.duration,
+  easing: [0.2, 0, 0, 1],
+}
+
+/** Elastic indicator spring — Switch thumb, RadioGroup dot. Mirrors SPRINGS.elastic. */
+export const SPRING_ELASTIC: SingleTransition = {
+  type: 'spring',
+  stiffness: 320,
+  damping: 22,
+  mass: 0.7,
+}
+
 // ─── Press scale tokens ──────────────────────────────────────────────────────
 // Per-component press intensities — taken from DESIGN.md.
 export const PRESS_SCALE = {

package/src/utils/fontGuard.ts

@@ -0,0 +1,34 @@
+import { isLoaded } from 'expo-font'
+
+declare const __DEV__: boolean
+
+let warned = false
+
+/**
+ * Dev-only guard: warns once if the Sohne font family is not loaded.
+ *
+ * Called lazily from `Text` on first render. Without this, a missing
+ * `useFonts(SohneFonts)` call (or a broken font path) produces invisible /
+ * system-font text with no signal — a silent failure consumers reported losing
+ * hours to. In production (`__DEV__ === false`) this is a no-op.
+ */
+export function warnIfFontsMissing(): void {
+  if (warned) return
+  if (typeof __DEV__ !== 'undefined' && !__DEV__) return
+  warned = true
+  try {
+    if (!isLoaded('Sohne-Regular')) {
+      console.warn(
+        '[retray-ui-kit] Sohne fonts are not loaded — text will fall back to the ' +
+          'system font. Load them at your app root before rendering any UI kit ' +
+          'component:\n\n' +
+          "  import { useFonts } from 'expo-font'\n" +
+          "  import { SohneFonts } from '@retray-dev/ui-kit/fonts'\n\n" +
+          '  const [fontsLoaded] = useFonts(SohneFonts)\n' +
+          '  if (!fontsLoaded) return null\n',
+      )
+    }
+  } catch {
+    // `isLoaded` not available in this expo-font version — skip the guard silently.
+  }
+}

package/src/utils/haptics.ts

@@ -1,38 +1,240 @@
-import { Platform } from 'react-native'
+/**
+ * Haptic feedback utilities using expo-haptics.
+ *
+ * Uses expo-haptics which works with both Expo Go and development builds.
+ * react-native-pulsar support is optional for dev builds with native modules.
+ *
+ * All functions are web-safe (no-op on web platform).
+ */
+import { Platform, NativeModules } from 'react-native'
 
+// ─── expo-haptics (primary) ───────────────────────────────────────────────────
 type HapticsModule = typeof import('expo-haptics')
-
 let _haptics: HapticsModule | null = null
+let _hapticsLoaded = false
 
 async function getHaptics(): Promise<HapticsModule | null> {
   if (Platform.OS === 'web') return null
-  if (!_haptics) {
-    _haptics = await import('expo-haptics')
+  if (!_hapticsLoaded) {
+    _hapticsLoaded = true
+    try {
+      _haptics = await import('expo-haptics')
+    } catch {
+      _haptics = null
+    }
   }
   return _haptics
 }
 
+// ─── Pulsar (optional for dev builds) ─────────────────────────────────────────
+// Only available in development builds with native modules installed.
+// Gracefully falls back to expo-haptics if not available.
+type PulsarModule = typeof import('react-native-pulsar')
+let _pulsar: PulsarModule | null = null
+let _pulsarChecked = false
+let _pulsarAvailable = false
+
+function isPulsarNativeRegistered(): boolean {
+  // react-native-pulsar's NativeRNPulsar.ts calls
+  // TurboModuleRegistry.getEnforcing('RNPulsar') at module-eval time. When the
+  // native binary is absent (e.g. Expo Go), requiring the package throws during
+  // Metro module eval — and that throw is surfaced by RN's global error handler
+  // (red screen) even when wrapped in try/catch, because guardedLoadModule
+  // reports it before rethrowing. So we must confirm the native module is
+  // actually registered BEFORE requiring the JS wrapper.
+  //
+  // TurboModuleRegistry.get() returns a truthy proxy even for unregistered
+  // modules (false positive), so it can't be trusted. Instead we probe the low
+  // level: the new-arch turbo proxy returns null for unregistered names, and
+  // the old-arch NativeModules map omits them. A direct lookup throws nothing —
+  // unlike a top-level import — so any failure is caught safely here.
+  try {
+    const g = globalThis as {
+      __turboModuleProxy?: (name: string) => unknown
+    }
+    if (typeof g.__turboModuleProxy === 'function') {
+      return g.__turboModuleProxy('RNPulsar') != null
+    }
+    return NativeModules?.RNPulsar != null
+  } catch {
+    return false
+  }
+}
+
+function getPulsar(): PulsarModule | null {
+  if (Platform.OS === 'web') return null
+  if (!_pulsarChecked) {
+    _pulsarChecked = true
+    try {
+      // Only require the package when its native module is registered —
+      // otherwise the require would red-screen the app (see above).
+      if (isPulsarNativeRegistered()) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _pulsar = require('react-native-pulsar') as PulsarModule
+        _pulsarAvailable = true
+      }
+    } catch {
+      _pulsar = null
+      _pulsarAvailable = false
+    }
+  }
+  return _pulsarAvailable ? _pulsar : null
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Light selection feedback — checkboxes, switches, toggles, pickers.
+ */
 export function selectionAsync(): void {
   if (Platform.OS === 'web') return
-  getHaptics().then(h => h?.selectionAsync())
+  // Try expo-haptics first (always available in Expo Go)
+  getHaptics().then((h) => {
+    if (h) {
+      h.selectionAsync()
+    } else {
+      // Fallback to Pulsar if available
+      getPulsar()?.Presets.System.selection()
+    }
+  })
 }
 
+/**
+ * Light impact — cards, surfaces, light interactions.
+ */
 export function impactLight(): void {
   if (Platform.OS === 'web') return
-  getHaptics().then(h => h?.impactAsync(h.ImpactFeedbackStyle.Light))
+  getHaptics().then((h) => {
+    if (h) {
+      h.impactAsync(h.ImpactFeedbackStyle.Light)
+    } else {
+      getPulsar()?.Presets.System.impactLight()
+    }
+  })
 }
 
+/**
+ * Medium impact — buttons, primary actions.
+ */
 export function impactMedium(): void {
   if (Platform.OS === 'web') return
-  getHaptics().then(h => h?.impactAsync(h.ImpactFeedbackStyle.Medium))
+  getHaptics().then((h) => {
+    if (h) {
+      h.impactAsync(h.ImpactFeedbackStyle.Medium)
+    } else {
+      getPulsar()?.Presets.System.impactMedium()
+    }
+  })
+}
+
+/**
+ * Heavy impact — confirmations, important actions.
+ */
+export function impactHeavy(): void {
+  if (Platform.OS === 'web') return
+  getHaptics().then((h) => {
+    if (h) {
+      h.impactAsync(h.ImpactFeedbackStyle.Heavy)
+    } else {
+      getPulsar()?.Presets.System.impactHeavy()
+    }
+  })
 }
 
+/**
+ * Success notification — confirmations, completed actions.
+ */
 export function notificationSuccess(): void {
   if (Platform.OS === 'web') return
-  getHaptics().then(h => h?.notificationAsync(h.NotificationFeedbackType.Success))
+  getHaptics().then((h) => {
+    if (h) {
+      h.notificationAsync(h.NotificationFeedbackType.Success)
+    } else {
+      getPulsar()?.Presets.System.notificationSuccess()
+    }
+  })
 }
 
+/**
+ * Error notification — failed actions, errors.
+ */
 export function notificationError(): void {
   if (Platform.OS === 'web') return
-  getHaptics().then(h => h?.notificationAsync(h.NotificationFeedbackType.Error))
+  getHaptics().then((h) => {
+    if (h) {
+      h.notificationAsync(h.NotificationFeedbackType.Error)
+    } else {
+      getPulsar()?.Presets.System.notificationError()
+    }
+  })
+}
+
+/**
+ * Warning notification — caution states.
+ */
+export function notificationWarning(): void {
+  if (Platform.OS === 'web') return
+  getHaptics().then((h) => {
+    if (h) {
+      h.notificationAsync(h.NotificationFeedbackType.Warning)
+    } else {
+      getPulsar()?.Presets.System.notificationWarning()
+    }
+  })
+}
+
+// ─── Rich Pulsar Presets (enhanced feedback) ──────────────────────────────────
+
+/**
+ * Rich haptic presets from Pulsar — enhanced feedback for special interactions.
+ * Falls back to basic expo-haptics on Expo Go or unsupported devices.
+ */
+export const richHaptics = {
+  /** Hammer strike — strong confirmation feedback. */
+  hammer: (): void => {
+    if (Platform.OS === 'web') return
+    const p = getPulsar()
+    if (p) p.Presets.hammer()
+    else impactHeavy()
+  },
+
+  /** Pulse — rhythmic feedback for toggles or state changes. */
+  pulse: (): void => {
+    if (Platform.OS === 'web') return
+    const p = getPulsar()
+    if (p) p.Presets.pulse()
+    else selectionAsync()
+  },
+
+  /** Buzz — continuous vibration for attention. */
+  buzz: (): void => {
+    if (Platform.OS === 'web') return
+    const p = getPulsar()
+    if (p) p.Presets.buzz()
+    else impactMedium()
+  },
+
+  /** Flick — crisp click feedback. */
+  flick: (): void => {
+    if (Platform.OS === 'web') return
+    const p = getPulsar()
+    if (p) p.Presets.flick()
+    else selectionAsync()
+  },
+
+  /** Soft — gentle, subtle feedback. */
+  soft: (): void => {
+    if (Platform.OS === 'web') return
+    const p = getPulsar()
+    if (p) p.Presets.System.impactSoft()
+    else impactLight()
+  },
+
+  /** Rigid — firm, solid feedback. */
+  rigid: (): void => {
+    if (Platform.OS === 'web') return
+    const p = getPulsar()
+    if (p) p.Presets.System.impactRigid()
+    else impactMedium()
+  },
 }

package/src/utils/icons.ts

@@ -17,36 +17,63 @@ export interface IconProps {
   family?: IconFamily
 }
 
-type ResolvedFamily = {
+type IconComponentType = React.ComponentType<{ name: string; size: number; color: string }>
+type IconFamilyEntry = {
   name: IconFamily
-  component: React.ComponentType<{ name: any; size: number; color: string }>
-  glyphMap: Record<string, number>
+  component: IconComponentType
+  /** Deferred — glyphMap is only read when the resolution cache is first built. */
+  getGlyphMap: () => Record<string, number>
 }
 
-// Priority order: highest-priority family listed last so it overwrites lower-priority entries in the cache
-const ICON_FAMILIES: ResolvedFamily[] = [
-  { name: 'Ionicons',      component: Ionicons as any,      glyphMap: (Ionicons as any).glyphMap },
-  { name: 'MaterialIcons', component: MaterialIcons as any, glyphMap: (MaterialIcons as any).glyphMap },
-  { name: 'FontAwesome5',  component: FontAwesome5 as any,  glyphMap: (FontAwesome5 as any).glyphMap },
-  { name: 'Entypo',        component: Entypo as any,        glyphMap: (Entypo as any).glyphMap },
-  { name: 'AntDesign',     component: AntDesign as any,     glyphMap: (AntDesign as any).glyphMap },
-  { name: 'Feather',       component: Feather as any,       glyphMap: (Feather as any).glyphMap },
+type WithGlyphMap = { glyphMap?: Record<string, number> }
+
+const glyphMapOf = (mod: unknown): Record<string, number> =>
+  (mod as WithGlyphMap).glyphMap ?? {}
+
+// Priority order: highest-priority family LAST so it overwrites lower-priority entries in the cache.
+const ALL_FAMILIES: IconFamilyEntry[] = [
+  { name: 'Ionicons',      component: Ionicons as unknown as IconComponentType,      getGlyphMap: () => glyphMapOf(Ionicons) },
+  { name: 'MaterialIcons', component: MaterialIcons as unknown as IconComponentType, getGlyphMap: () => glyphMapOf(MaterialIcons) },
+  { name: 'FontAwesome5',  component: FontAwesome5 as unknown as IconComponentType,  getGlyphMap: () => glyphMapOf(FontAwesome5) },
+  { name: 'Entypo',        component: Entypo as unknown as IconComponentType,        getGlyphMap: () => glyphMapOf(Entypo) },
+  { name: 'AntDesign',     component: AntDesign as unknown as IconComponentType,     getGlyphMap: () => glyphMapOf(AntDesign) },
+  { name: 'Feather',       component: Feather as unknown as IconComponentType,       getGlyphMap: () => glyphMapOf(Feather) },
 ]
 
-let resolvedCache: Map<string, ResolvedFamily> | null = null
+// Active families participating in name resolution. Defaults to all six.
+let activeFamilies: IconFamilyEntry[] = ALL_FAMILIES
+let resolvedCache: Map<string, IconFamilyEntry> | null = null
+
+/**
+ * Restrict which icon families participate in automatic name resolution.
+ * Narrowing to the families you actually use shrinks the resolution cache and
+ * speeds up the first `renderIcon` call (no scanning thousands of unused glyphs).
+ *
+ * Note: all six families are still statically imported by this module — Metro
+ * bundles them regardless. This controls *resolution scope*, not bundle size.
+ *
+ * @example configureIconFamilies(['Feather', 'MaterialIcons'])
+ */
+export function configureIconFamilies(families: IconFamily[]): void {
+  const order = families
+    .map((n) => ALL_FAMILIES.find((f) => f.name === n))
+    .filter((f): f is IconFamilyEntry => f !== undefined)
+  activeFamilies = order.length > 0 ? order : ALL_FAMILIES
+  resolvedCache = null // invalidate — rebuilt lazily on next resolve
+}
 
-function buildCache(): Map<string, ResolvedFamily> {
-  const cache = new Map<string, ResolvedFamily>()
-  for (const family of ICON_FAMILIES) {
-    if (!family.glyphMap) continue
-    for (const iconName of Object.keys(family.glyphMap)) {
+function buildCache(): Map<string, IconFamilyEntry> {
+  const cache = new Map<string, IconFamilyEntry>()
+  for (const family of activeFamilies) {
+    const glyphMap = family.getGlyphMap()
+    for (const iconName of Object.keys(glyphMap)) {
       cache.set(iconName, family)
     }
   }
   return cache
 }
 
-function resolveFamily(name: string): ResolvedFamily | null {
+function resolveFamily(name: string): IconFamilyEntry | null {
   if (!resolvedCache) {
     resolvedCache = buildCache()
   }
@@ -54,10 +81,10 @@ function resolveFamily(name: string): ResolvedFamily | null {
 }
 
 export function Icon({ name, size, color, family }: IconProps): React.ReactElement | null {
-  let resolved: ResolvedFamily | null = null
+  let resolved: IconFamilyEntry | null = null
 
   if (family) {
-    resolved = ICON_FAMILIES.find((f) => f.name === family) ?? null
+    resolved = ALL_FAMILIES.find((f) => f.name === family) ?? null
   } else {
     resolved = resolveFamily(name)
   }