@nexub/react-native 0.0.0-stage → 2.1.0

package/src/primitives/Surface.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { Platform, StyleSheet, View, type ViewProps } from 'react-native';
+import type { NativeTokens } from '@nexub/tokens/native';
+import { useTheme, type ElevationLevel, type RoleName } from '../theme/ThemeProvider';
+
+// Optional peer: native Liquid Glass on iOS 26+. Everything else gets the solid fallback.
+let Glass: typeof import('expo-glass-effect') | undefined;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- optional peer, must not fail when absent
+  Glass = require('expo-glass-effect');
+} catch {
+  Glass = undefined;
+}
+const liquidGlass = Platform.OS === 'ios' && !!Glass?.isLiquidGlassAvailable();
+
+export type SurfaceTone = Extract<RoleName, `surface${string}`>;
+export type ShapeName = keyof NativeTokens['shape'];
+
+export interface SurfaceProps extends ViewProps {
+  /** Tonal tier. @default 'surface' */
+  tone?: SurfaceTone;
+  /** @default 0 */
+  elevation?: ElevationLevel;
+  /** 'glass' is for the control layer only (bars, floating controls), never content. @default 'solid' */
+  material?: 'solid' | 'glass';
+  /** Corner radius: a shape token or dp. */
+  radius?: ShapeName | number;
+}
+
+/**
+ * A tonal surface. `material="glass"` is native Liquid Glass on iOS 26+, and
+ * `surface-elevated` + hairline elsewhere, or whenever glass is 'off' (user
+ * setting or Reduce Transparency).
+ */
+export function Surface({
+  tone = 'surface',
+  elevation = 0,
+  material = 'solid',
+  radius,
+  style,
+  ...rest
+}: SurfaceProps) {
+  const theme = useTheme();
+  const borderRadius = typeof radius === 'string' ? theme.tokens.shape[radius] : radius;
+  const glass = material === 'glass' && theme.glass !== 'off';
+
+  if (glass && liquidGlass && Glass) {
+    return (
+      <Glass.GlassView
+        glassEffectStyle={theme.glass === 'clear' ? 'clear' : 'regular'}
+        tintColor={theme.glass === 'tinted' ? theme.roles['surface-elevated'] : undefined}
+        colorScheme={theme.scheme}
+        style={[{ borderRadius, boxShadow: theme.elevation(elevation) }, style]}
+        {...rest}
+      />
+    );
+  }
+  return (
+    <View
+      style={[
+        {
+          backgroundColor: theme.roles[material === 'glass' ? 'surface-elevated' : tone],
+          borderRadius,
+          boxShadow: theme.elevation(elevation),
+        },
+        material === 'glass' && {
+          borderWidth: StyleSheet.hairlineWidth,
+          borderColor: theme.roles['outline-variant'],
+        },
+        style,
+      ]}
+      {...rest}
+    />
+  );
+}

package/src/primitives/Text.tsx

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import { Text as RNText, type TextProps as RNTextProps } from 'react-native';
+import type { NativeTypeRole } from '@nexub/tokens/native';
+import { fontStyle, type FontFamily } from '../theme/fonts';
+import { useTheme, type RoleName } from '../theme/ThemeProvider';
+
+type Ramp = NonNullable<RNTextProps['dynamicTypeRamp']>;
+
+// iOS Dynamic Type: each role follows its Apple text style's scaling curve.
+const RAMP: Record<NativeTypeRole, Ramp> = {
+  'display-lg': 'largeTitle',
+  'display-md': 'largeTitle',
+  'display-sm': 'largeTitle',
+  'headline-lg': 'title1',
+  'headline-md': 'title2',
+  'headline-sm': 'title3',
+  'title-lg': 'title3',
+  'title-md': 'headline',
+  'title-sm': 'subheadline',
+  'body-lg': 'body',
+  'body-md': 'body',
+  'body-sm': 'footnote',
+  'label-lg': 'subheadline',
+  'label-md': 'footnote',
+  'label-sm': 'caption1',
+};
+
+// Big type already reads at large sizes; cap it so it doesn't push content off
+// screen. Body, title and label roles scale without a cap (WCAG 1.4.4).
+const cap = (role: NativeTypeRole) =>
+  role.startsWith('display') ? 1.3 : role.startsWith('headline') ? 1.6 : undefined;
+
+export interface TextProps extends RNTextProps {
+  /** Type role. @default 'body-md' */
+  variant?: NativeTypeRole;
+  /** Colour role. @default 'on-surface' */
+  color?: RoleName;
+  /** Tabular figures, for numbers that line up. */
+  tabular?: boolean;
+  /** Overrides the role's family (e.g. 'mono' for codes). */
+  family?: FontFamily;
+}
+
+export function Text({
+  variant = 'body-md',
+  color = 'on-surface',
+  tabular,
+  family,
+  style,
+  ...rest
+}: TextProps) {
+  const { roles, tokens, fonts } = useTheme();
+  const t = tokens.type[variant];
+  return (
+    <RNText
+      dynamicTypeRamp={RAMP[variant]}
+      maxFontSizeMultiplier={cap(variant)}
+      style={[
+        {
+          ...fontStyle(family ?? t.family, t.weight, fonts),
+          fontSize: t.size,
+          lineHeight: t.lineHeight,
+          letterSpacing: t.letterSpacing,
+          color: roles[color],
+        },
+        tabular && { fontVariant: ['tabular-nums'] },
+        style,
+      ]}
+      {...rest}
+    />
+  );
+}
+
+export interface HeadingProps extends TextProps {}
+
+/** Text announced as a heading. @default variant 'headline-sm' */
+export function Heading({ variant = 'headline-sm', ...rest }: HeadingProps) {
+  return <Text accessibilityRole="header" variant={variant} {...rest} />;
+}

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,210 @@
+import * as React from 'react';
+import {
+  AccessibilityInfo,
+  AppState,
+  Platform,
+  StyleSheet,
+  View,
+  useColorScheme,
+} from 'react-native';
+import { native, type NativeRoles } from '@nexub/tokens/native';
+import { createSeedRoles } from '@nexub/tokens/seed';
+import {
+  defaultMessages,
+  directionOf,
+  type ContrastLevel,
+  type Direction,
+  type GlassMode,
+  type NexubMessages,
+  type Product,
+} from '@nexub/core';
+import { playHaptic, type HapticToken } from './haptics';
+import type { FontSource } from './fonts';
+
+export type Scheme = 'light' | 'dark';
+export type Roles = { -readonly [K in keyof NativeRoles]: string };
+export type RoleName = keyof Roles;
+export type ElevationLevel = 0 | 1 | 2 | 3;
+
+export interface NexubTheme {
+  scheme: Scheme;
+  contrast: ContrastLevel;
+  product: Product | undefined;
+  /** Colour roles, already resolved for scheme, contrast, product and seed. */
+  roles: Roles;
+  /** Every native token (spacing, shape, size, type, state, motion). */
+  tokens: typeof native;
+  /** `boxShadow` for an elevation level, undefined for 0. */
+  elevation: (level: ElevationLevel) => string | undefined;
+  /** Effective glass: 'off' when the user has Reduce Transparency on. */
+  glass: GlassMode;
+  reducedMotion: boolean;
+  haptics: boolean;
+  fonts: FontSource;
+  locale: string;
+  dir: Direction;
+  messages: NexubMessages;
+}
+
+export interface NexubNativeProviderProps {
+  /** @default 'system' */
+  scheme?: Scheme | 'system';
+  /** 'system' = iOS Increase Contrast / Android high-contrast text → 'high'. @default 'system' */
+  contrast?: ContrastLevel | 'system';
+  /** Product brand: remaps the tertiary role family. */
+  product?: Product;
+  /** White-label seed colour (#rgb / #rrggbb); regenerates the `seedTarget` family. */
+  seed?: string;
+  /** @default 'primary' */
+  seedTarget?: 'primary' | 'tertiary';
+  /** Glass intensity (the app persists the user's choice). @default 'balanced' */
+  glass?: GlassMode;
+  /** Haptics on/off (user setting). @default true */
+  haptics?: boolean;
+  /** 'nexub' needs `nexubFonts` loaded; 'system' uses the platform font. @default 'nexub' */
+  fonts?: FontSource;
+  /** BCP 47 locale for Intl formatting. @default 'en' */
+  locale?: string;
+  /** @default derived from `locale` */
+  dir?: Direction;
+  /** Overrides for the default English strings. */
+  messages?: Partial<NexubMessages>;
+  children?: React.ReactNode;
+}
+
+const ThemeContext = React.createContext<NexubTheme | null>(null);
+
+// AccessibilityInfo reads that fire no change event (contrast): re-read on foreground.
+function useForegroundSetting(
+  read: (() => Promise<boolean>) | undefined,
+  enabled: boolean,
+): boolean {
+  const [on, setOn] = React.useState(false);
+  React.useEffect(() => {
+    if (!enabled || !read) return;
+    const get = () => read().then(setOn, () => setOn(false));
+    get();
+    const sub = AppState.addEventListener('change', (s) => s === 'active' && get());
+    return () => sub.remove();
+  }, [enabled, read]);
+  return on;
+}
+
+function useSetting(
+  read: () => Promise<boolean>,
+  event: 'reduceMotionChanged' | 'reduceTransparencyChanged',
+): boolean {
+  const [on, setOn] = React.useState(false);
+  React.useEffect(() => {
+    read().then(setOn, () => setOn(false));
+    const sub = AccessibilityInfo.addEventListener(event, setOn);
+    return () => sub.remove();
+  }, [read, event]);
+  return on;
+}
+
+type A11y = typeof AccessibilityInfo & {
+  isDarkerSystemColorsEnabled?: () => Promise<boolean>;
+  isHighTextContrastEnabled?: () => Promise<boolean>;
+};
+const a11y = AccessibilityInfo as A11y;
+const readHighContrast =
+  Platform.OS === 'ios'
+    ? a11y.isDarkerSystemColorsEnabled?.bind(a11y)
+    : a11y.isHighTextContrastEnabled?.bind(a11y);
+const readReduceMotion = () => AccessibilityInfo.isReduceMotionEnabled();
+const readReduceTransparency = () =>
+  Platform.OS === 'ios' ? AccessibilityInfo.isReduceTransparencyEnabled() : Promise.resolve(false);
+
+/**
+ * Theme, accessibility preferences, locale and strings for every
+ * @nexub/react-native component. Wrap the app once, inside the safe-area provider.
+ */
+export function NexubNativeProvider({
+  scheme: schemeProp = 'system',
+  contrast: contrastProp = 'system',
+  product,
+  seed,
+  seedTarget = 'primary',
+  glass = 'balanced',
+  haptics = true,
+  fonts = 'nexub',
+  locale = 'en',
+  dir,
+  messages,
+  children,
+}: NexubNativeProviderProps) {
+  const system = useColorScheme();
+  const scheme: Scheme =
+    schemeProp === 'system' ? (system === 'dark' ? 'dark' : 'light') : schemeProp;
+  const systemHigh = useForegroundSetting(readHighContrast, contrastProp === 'system');
+  const contrast: ContrastLevel =
+    contrastProp === 'system' ? (systemHigh ? 'high' : 'standard') : contrastProp;
+  const reducedMotion = useSetting(readReduceMotion, 'reduceMotionChanged');
+  const reduceTransparency = useSetting(readReduceTransparency, 'reduceTransparencyChanged');
+  const resolvedDir = dir ?? directionOf(locale);
+
+  const theme = React.useMemo<NexubTheme>(() => {
+    const roles: Roles = {
+      ...native.color.roles[contrast][scheme],
+      ...(product ? native.color.products[product][contrast][scheme] : {}),
+      ...(seed ? createSeedRoles(seed, { contrast, target: seedTarget })[scheme] : {}),
+    };
+    return {
+      scheme,
+      contrast,
+      product,
+      roles,
+      tokens: native,
+      elevation: (level) => (level ? native.elevation[level][scheme] : undefined),
+      glass: reduceTransparency ? 'off' : glass,
+      reducedMotion,
+      haptics,
+      fonts,
+      locale,
+      dir: resolvedDir,
+      messages: { ...defaultMessages, ...messages },
+    };
+  }, [
+    scheme,
+    contrast,
+    product,
+    seed,
+    seedTarget,
+    glass,
+    reduceTransparency,
+    reducedMotion,
+    haptics,
+    fonts,
+    locale,
+    resolvedDir,
+    messages,
+  ]);
+
+  return (
+    <ThemeContext.Provider value={theme}>
+      <View style={[styles.root, { direction: resolvedDir }]}>{children}</View>
+    </ThemeContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({ root: { flex: 1 } });
+
+/** The active theme. Throws outside NexubNativeProvider. */
+export function useTheme(): NexubTheme {
+  const theme = React.useContext(ThemeContext);
+  if (!theme) throw new Error('@nexub/react-native: wrap your app in <NexubNativeProvider>.');
+  return theme;
+}
+
+/** Shorthand for `useTheme().roles`. */
+export const useRoles = (): Roles => useTheme().roles;
+
+/** The active strings: defaults merged with the provider's overrides. */
+export const useNexubMessages = (): NexubMessages => useTheme().messages;
+
+/** Plays a semantic haptic, unless the user turned haptics off. */
+export function useHaptics(): (token: HapticToken) => void {
+  const { haptics } = useTheme();
+  return React.useCallback((token) => haptics && playHaptic(token), [haptics]);
+}

package/src/theme/fonts.ts

@@ -0,0 +1,52 @@
+// Nexub faces as static TTFs (OFL) from @expo-google-fonts, one file per weight.
+// Load them once at startup:  const [ready] = useFonts(nexubFonts)  (expo-font).
+// Per-weight subpaths don't import expo-font, so bare RN apps can load the same
+// files with their own loader.
+import { Inter_400Regular } from '@expo-google-fonts/inter/400Regular';
+import { Inter_500Medium } from '@expo-google-fonts/inter/500Medium';
+import { Inter_600SemiBold } from '@expo-google-fonts/inter/600SemiBold';
+import { Inter_700Bold } from '@expo-google-fonts/inter/700Bold';
+import { PlusJakartaSans_600SemiBold } from '@expo-google-fonts/plus-jakarta-sans/600SemiBold';
+import { PlusJakartaSans_700Bold } from '@expo-google-fonts/plus-jakarta-sans/700Bold';
+import { PlusJakartaSans_800ExtraBold } from '@expo-google-fonts/plus-jakarta-sans/800ExtraBold';
+import { GeistMono_400Regular } from '@expo-google-fonts/geist-mono/400Regular';
+
+export const nexubFonts = {
+  Inter_400Regular,
+  Inter_500Medium,
+  Inter_600SemiBold,
+  Inter_700Bold,
+  PlusJakartaSans_600SemiBold,
+  PlusJakartaSans_700Bold,
+  PlusJakartaSans_800ExtraBold,
+  GeistMono_400Regular,
+};
+
+export type FontFamily = 'sans' | 'display' | 'mono';
+export type FontSource = 'nexub' | 'system';
+
+const SANS: Record<number, string> = {
+  400: 'Inter_400Regular',
+  500: 'Inter_500Medium',
+  600: 'Inter_600SemiBold',
+  700: 'Inter_700Bold',
+  800: 'Inter_700Bold',
+};
+const DISPLAY: Record<number, string> = {
+  400: 'PlusJakartaSans_600SemiBold',
+  500: 'PlusJakartaSans_600SemiBold',
+  600: 'PlusJakartaSans_600SemiBold',
+  700: 'PlusJakartaSans_700Bold',
+  800: 'PlusJakartaSans_800ExtraBold',
+};
+
+/**
+ * Style for a family + weight. With static files the weight lives in the file
+ * name, so `fontWeight` is only set for the system font (Android picks the
+ * wrong file when both are set).
+ */
+export function fontStyle(family: FontFamily, weight: number, source: FontSource) {
+  if (source === 'system') return { fontWeight: String(weight) as '400' };
+  if (family === 'mono') return { fontFamily: 'GeistMono_400Regular' };
+  return { fontFamily: (family === 'display' ? DISPLAY : SANS)[weight] ?? SANS[400] };
+}

package/src/theme/haptics.ts

@@ -0,0 +1,57 @@
+import { Platform } from 'react-native';
+
+// Semantic haptics (MOBILE_PLAN.md §4.4). Apple's rule: never on plain taps,
+// never the only feedback. Android uses the platform constants, not the
+// vibrator-based impact API.
+export type HapticToken =
+  'selection' | 'toggleOn' | 'toggleOff' | 'confirm' | 'reject' | 'warning' | 'snap';
+
+// Optional peer: without expo-haptics every haptic is a no-op.
+let H: typeof import('expo-haptics') | undefined;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- optional peer, must not fail when absent
+  H = require('expo-haptics');
+} catch {
+  H = undefined;
+}
+
+const ANDROID = {
+  selection: 'Segment_Tick',
+  toggleOn: 'Toggle_On',
+  toggleOff: 'Toggle_Off',
+  confirm: 'Confirm',
+  reject: 'Reject',
+  warning: 'Reject',
+  snap: 'Gesture_End',
+} as const;
+
+export function playHaptic(token: HapticToken): void {
+  if (!H) return;
+  const done = () => {};
+  if (Platform.OS === 'android') {
+    H.performAndroidHapticsAsync(H.AndroidHaptics[ANDROID[token]]).catch(done);
+    return;
+  }
+  if (Platform.OS !== 'ios') return;
+  switch (token) {
+    case 'selection':
+      H.selectionAsync().catch(done);
+      break;
+    case 'toggleOn':
+    case 'toggleOff':
+      H.impactAsync(H.ImpactFeedbackStyle.Light).catch(done);
+      break;
+    case 'snap':
+      H.impactAsync(H.ImpactFeedbackStyle.Medium).catch(done);
+      break;
+    case 'confirm':
+      H.notificationAsync(H.NotificationFeedbackType.Success).catch(done);
+      break;
+    case 'reject':
+      H.notificationAsync(H.NotificationFeedbackType.Error).catch(done);
+      break;
+    case 'warning':
+      H.notificationAsync(H.NotificationFeedbackType.Warning).catch(done);
+      break;
+  }
+}

package/src/theme/navigation.ts

@@ -0,0 +1,68 @@
+// Native chrome, Nexub colours: options for the system navigation (native
+// stack header, tabs, React Navigation theme). We theme it; we never redraw it.
+import { fontStyle } from './fonts';
+import { useTheme, type NexubTheme } from './ThemeProvider';
+
+/** Native stack `screenOptions`: large titles on a surface-coloured native header, Nexub type and tint. */
+export function nexubStackOptions(theme: NexubTheme) {
+  const { roles, fonts } = theme;
+  return {
+    headerLargeTitle: true,
+    // Opaque: a transparent header hid the expanded large title (iOS 26); the
+    // system still draws its scroll-edge effect on an opaque native header.
+    headerTransparent: false,
+    headerShadowVisible: false,
+    headerLargeTitleShadowVisible: false,
+    headerTintColor: roles.primary,
+    headerStyle: { backgroundColor: roles.surface },
+    headerTitleStyle: { color: roles['on-surface'], ...fontStyle('sans', 600, fonts) },
+    headerLargeTitleStyle: { color: roles['on-surface'], ...fontStyle('display', 700, fonts) },
+    contentStyle: { backgroundColor: roles.surface },
+  };
+}
+
+/** React Navigation `theme` (also Expo Router's ThemeProvider). */
+export function nexubNavigationTheme(theme: NexubTheme) {
+  const { roles, fonts, scheme } = theme;
+  const font = (weight: 400 | 500 | 600 | 700) => {
+    const f = fontStyle('sans', weight, fonts);
+    return {
+      fontFamily: 'fontFamily' in f ? (f.fontFamily as string) : 'System',
+      fontWeight: String(weight) as '400',
+    };
+  };
+  return {
+    dark: scheme === 'dark',
+    colors: {
+      primary: roles.primary,
+      background: roles.surface,
+      card: roles['surface-container'],
+      text: roles['on-surface'],
+      border: roles['outline-variant'],
+      notification: roles.error,
+    },
+    fonts: { regular: font(400), medium: font(500), bold: font(600), heavy: font(700) },
+  };
+}
+
+/** Colours for native tab bars (Expo Router NativeTabs / react-native-bottom-tabs). */
+export function nexubTabsOptions(theme: NexubTheme) {
+  const { roles, fonts } = theme;
+  return {
+    tintColor: roles.primary,
+    inactiveTintColor: roles['on-surface-variant'],
+    backgroundColor: roles['surface-container'],
+    badgeBackgroundColor: roles.error,
+    labelStyle: { ...fontStyle('sans', 500, fonts), fontSize: 11 },
+  };
+}
+
+/** All three for the current theme: `const nav = useNexubNavigation()`. */
+export function useNexubNavigation() {
+  const theme = useTheme();
+  return {
+    stack: nexubStackOptions(theme),
+    theme: nexubNavigationTheme(theme),
+    tabs: nexubTabsOptions(theme),
+  };
+}