@metacells/mcellui-core 0.1.2 → 0.2.0

package/dist/index-DtYPPizh.d.ts

@@ -0,0 +1,682 @@
+import { TextStyle, ViewStyle, ImageStyle, AccessibilityRole, AccessibilityState } from 'react-native';
+
+/**
+ * Typography Tokens
+ *
+ * Consistent typography scale for all text elements.
+ * Based on iOS Human Interface Guidelines with
+ * consideration for React Native defaults.
+ *
+ * Supports Geist font family when loaded, falls back to system fonts.
+ *
+ * Usage:
+ * ```tsx
+ * const { typography, fontFamily } = useTheme();
+ * <Text style={typography.body} />
+ * <Text style={{ fontFamily: fontFamily.sans, fontSize: fontSize.lg }} />
+ * ```
+ */
+
+declare const fontSize: {
+    /** 10px - fine print */
+    readonly '2xs': 10;
+    /** 11px - captions, labels */
+    readonly xs: 11;
+    /** 12px - small text, badges */
+    readonly sm: 12;
+    /** 14px - secondary text */
+    readonly base: 14;
+    /** 16px - body text (default) */
+    readonly md: 16;
+    /** 18px - emphasized body */
+    readonly lg: 18;
+    /** 20px - small headings */
+    readonly xl: 20;
+    /** 24px - section headings */
+    readonly '2xl': 24;
+    /** 30px - page headings */
+    readonly '3xl': 30;
+    /** 36px - large headings */
+    readonly '4xl': 36;
+    /** 48px - display */
+    readonly '5xl': 48;
+};
+type FontSizeKey = keyof typeof fontSize;
+declare const fontWeight: {
+    /** 100 */
+    readonly thin: "100";
+    /** 200 */
+    readonly extralight: "200";
+    /** 300 */
+    readonly light: "300";
+    /** 400 - body text */
+    readonly normal: "400";
+    /** 500 - slightly emphasized */
+    readonly medium: "500";
+    /** 600 - buttons, labels */
+    readonly semibold: "600";
+    /** 700 - headings */
+    readonly bold: "700";
+    /** 800 */
+    readonly extrabold: "800";
+    /** 900 */
+    readonly black: "900";
+};
+type FontWeightKey = keyof typeof fontWeight;
+declare const lineHeight: {
+    /** Tight: 1.0 */
+    readonly none: 1;
+    /** Tight: 1.25 */
+    readonly tight: 1.25;
+    /** Snug: 1.375 */
+    readonly snug: 1.375;
+    /** Normal: 1.5 (default) */
+    readonly normal: 1.5;
+    /** Relaxed: 1.625 */
+    readonly relaxed: 1.625;
+    /** Loose: 2.0 */
+    readonly loose: 2;
+};
+type LineHeightKey = keyof typeof lineHeight;
+declare const letterSpacing: {
+    readonly tighter: -0.8;
+    readonly tight: -0.4;
+    readonly normal: 0;
+    readonly wide: 0.4;
+    readonly wider: 0.8;
+    readonly widest: 1.6;
+};
+type LetterSpacingKey = keyof typeof letterSpacing;
+/**
+ * System font fallbacks for when custom fonts aren't loaded.
+ */
+declare const systemFonts: {
+    /** Sans-serif system font */
+    readonly sans: string;
+    /** Monospace system font */
+    readonly mono: string;
+};
+/**
+ * Semantic font tokens.
+ *
+ * Three fonts cover all use cases:
+ * - `sans`: Body text, UI elements (default)
+ * - `heading`: Headlines h1-h4 (can be display/serif font)
+ * - `mono`: Code blocks, monospace text
+ *
+ * @example
+ * ```tsx
+ * // Use defaults (Geist)
+ * <ThemeProvider>
+ *
+ * // Custom fonts
+ * <ThemeProvider fonts={{
+ *   sans: 'Inter_400Regular',
+ *   heading: 'PlayfairDisplay_700Bold',
+ *   mono: 'FiraCode_400Regular',
+ * }}>
+ * ```
+ */
+interface Fonts {
+    /** Body text, UI elements */
+    sans: string;
+    /** Headlines (h1-h4) - defaults to bold variant of sans */
+    heading: string;
+    /** Code, monospace text */
+    mono: string;
+}
+/**
+ * Default fonts using Geist font family.
+ * Used when no custom fonts are provided to ThemeProvider.
+ */
+declare const defaultFonts: Fonts;
+/**
+ * Legacy fontFamily export for backwards compatibility.
+ * @deprecated Use `fonts` from useTheme() instead
+ */
+declare const fontFamily: {
+    /** Sans-serif: Geist or system default */
+    readonly sans: string;
+    /** Monospace: Geist Mono or system default */
+    readonly mono: string;
+    /** System font - always available */
+    readonly system: string;
+};
+/**
+ * Font family with weight suffix for Geist.
+ * Use these when Geist fonts are loaded.
+ */
+declare const geistFontFamily: {
+    readonly 'sans-thin': "Geist_100Thin";
+    readonly 'sans-extralight': "Geist_200ExtraLight";
+    readonly 'sans-light': "Geist_300Light";
+    readonly 'sans-regular': "Geist_400Regular";
+    readonly 'sans-medium': "Geist_500Medium";
+    readonly 'sans-semibold': "Geist_600SemiBold";
+    readonly 'sans-bold': "Geist_700Bold";
+    readonly 'sans-extrabold': "Geist_800ExtraBold";
+    readonly 'sans-black': "Geist_900Black";
+    readonly 'mono-thin': "GeistMono_100Thin";
+    readonly 'mono-extralight': "GeistMono_200ExtraLight";
+    readonly 'mono-light': "GeistMono_300Light";
+    readonly 'mono-regular': "GeistMono_400Regular";
+    readonly 'mono-medium': "GeistMono_500Medium";
+    readonly 'mono-semibold': "GeistMono_600SemiBold";
+    readonly 'mono-bold': "GeistMono_700Bold";
+    readonly 'mono-extrabold': "GeistMono_800ExtraBold";
+    readonly 'mono-black': "GeistMono_900Black";
+};
+type FontFamilyKey = keyof typeof fontFamily;
+type GeistFontFamilyKey = keyof typeof geistFontFamily;
+/**
+ * Typography preset styles type.
+ */
+interface Typography {
+    display: TextStyle;
+    h1: TextStyle;
+    h2: TextStyle;
+    h3: TextStyle;
+    h4: TextStyle;
+    h5: TextStyle;
+    h6: TextStyle;
+    bodyLg: TextStyle;
+    body: TextStyle;
+    bodySm: TextStyle;
+    label: TextStyle;
+    labelSm: TextStyle;
+    button: TextStyle;
+    buttonSm: TextStyle;
+    buttonLg: TextStyle;
+    caption: TextStyle;
+    overline: TextStyle;
+    badge: TextStyle;
+    code: TextStyle;
+}
+type TypographyKey = keyof Typography;
+/**
+ * Creates typography presets with the given fonts.
+ * Used internally by ThemeProvider to generate typography styles.
+ */
+declare function createTypography(fonts: Fonts): Typography;
+/**
+ * Default typography presets using default fonts.
+ * @deprecated Use typography from useTheme() for font customization support
+ */
+declare const typography: Typography;
+
+/**
+ * cn() - Class Name / Style Merger
+ *
+ * The core utility for merging styles in mcellui.
+ * Inspired by shadcn/ui's cn() but adapted for React Native StyleSheet.
+ */
+
+type Style = ViewStyle | TextStyle | ImageStyle;
+type StyleInput = Style | Style[] | null | undefined | false;
+/**
+ * Merges multiple style objects into a single flattened style.
+ *
+ * Handles undefined, null, false, and nested arrays. React Native equivalent
+ * of clsx/cn for web.
+ *
+ * @param inputs - Style objects or falsy values to merge
+ * @returns Merged and flattened style object
+ *
+ * @example
+ * ```tsx
+ * const styles = cn(
+ *   baseStyles.container,
+ *   isActive && activeStyles,
+ *   { padding: 16 }
+ * );
+ * ```
+ */
+declare function cn(...inputs: StyleInput[]): Style;
+/**
+ * Creates a style object from conditional styles.
+ *
+ * More explicit alternative to cn() for complex conditions.
+ *
+ * @param styles - Object mapping condition names to style values
+ * @returns Merged and flattened style object
+ *
+ * @example
+ * ```tsx
+ * const styles = mergeStyles({
+ *   base: baseStyle,
+ *   active: isActive && activeStyle,
+ *   disabled: isDisabled && disabledStyle,
+ * });
+ * ```
+ */
+declare function mergeStyles(styles: Record<string, StyleInput>): Style;
+
+/**
+ * Platform Utilities
+ *
+ * Helpers for platform-specific behavior
+ */
+/** True if running on iOS */
+declare const isIOS: boolean;
+/** True if running on Android */
+declare const isAndroid: boolean;
+/** True if running on web */
+declare const isWeb: boolean;
+/** iOS version number (returns 0 on non-iOS platforms) */
+declare const iosVersion: number;
+/** Android API level (returns 0 on non-Android platforms) */
+declare const androidApiLevel: number;
+/**
+ * Check if device is a tablet.
+ *
+ * Uses screen dimensions heuristic (600dp minimum, aspect ratio < 1.6).
+ *
+ * @returns True if device is likely a tablet
+ */
+declare function isTablet(): boolean;
+/** Device pixel ratio for crisp rendering */
+declare const pixelRatio: number;
+/**
+ * Round to nearest pixel for crisp lines and borders.
+ *
+ * @param value - Value in logical pixels
+ * @returns Value rounded to nearest physical pixel
+ */
+declare function roundToNearestPixel(value: number): number;
+/**
+ * Get safe font scale (clamped for accessibility).
+ *
+ * Prevents excessively large text from breaking layouts when users enable
+ * large text accessibility settings.
+ *
+ * @param maxScale - Maximum scale to allow (defaults to 1.3)
+ * @returns Clamped font scale factor
+ */
+declare function getFontScale(maxScale?: number): number;
+
+/**
+ * Accessibility Utilities
+ *
+ * Helpers for building accessible components
+ */
+
+interface A11yProps {
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+    accessibilityRole?: AccessibilityRole;
+    accessibilityState?: AccessibilityState;
+}
+/**
+ * Creates accessibility props for a button.
+ *
+ * @param label - Accessible label for the button
+ * @param options - Optional button state (hint, disabled, selected)
+ * @returns Accessibility props to spread onto component
+ *
+ * @example
+ * ```tsx
+ * <Pressable {...buttonA11y('Submit', { disabled: isLoading })} />
+ * ```
+ */
+declare function buttonA11y(label: string, options?: {
+    hint?: string;
+    disabled?: boolean;
+    selected?: boolean;
+}): A11yProps;
+/**
+ * Creates accessibility props for a checkbox/switch.
+ *
+ * @param label - Accessible label for the toggle
+ * @param checked - Whether the toggle is checked
+ * @param options - Optional toggle state (hint, disabled)
+ * @returns Accessibility props to spread onto component
+ *
+ * @example
+ * ```tsx
+ * <Pressable {...toggleA11y('Dark Mode', isDark, { disabled: false })} />
+ * ```
+ */
+declare function toggleA11y(label: string, checked: boolean, options?: {
+    hint?: string;
+    disabled?: boolean;
+}): A11yProps;
+/**
+ * Creates accessibility props for a link.
+ *
+ * @param label - Accessible label for the link
+ * @param options - Optional hint text
+ * @returns Accessibility props to spread onto component
+ *
+ * @example
+ * ```tsx
+ * <Pressable {...linkA11y('View Details', { hint: 'Opens product page' })} />
+ * ```
+ */
+declare function linkA11y(label: string, options?: {
+    hint?: string;
+}): A11yProps;
+/**
+ * Creates accessibility props for an image.
+ *
+ * @param label - Accessible label describing the image
+ * @param options - Optional decorative flag (hides from screen readers)
+ * @returns Accessibility props to spread onto Image component
+ *
+ * @example
+ * ```tsx
+ * <Image {...imageA11y('Profile photo')} />
+ * <Image {...imageA11y('', { decorative: true })} />
+ * ```
+ */
+declare function imageA11y(label: string, options?: {
+    decorative?: boolean;
+}): A11yProps;
+/**
+ * Creates accessibility props for a heading.
+ *
+ * @param label - Accessible label for the heading
+ * @returns Accessibility props to spread onto Text component
+ *
+ * @example
+ * ```tsx
+ * <Text {...headingA11y('Dashboard')} style={typography.h1}>Dashboard</Text>
+ * ```
+ */
+declare function headingA11y(label: string): A11yProps;
+
+/**
+ * Haptics Utilities
+ *
+ * Unified haptic feedback interface.
+ * Falls back gracefully when expo-haptics is not available.
+ *
+ * Design Philosophy:
+ * - Every interactive element should provide tactile feedback
+ * - Haptics should be subtle and purposeful
+ * - Respect user's haptic preferences
+ */
+/** Available haptic feedback styles */
+type HapticStyle = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';
+/**
+ * Haptic presets for common interactions
+ */
+declare const hapticPresets: {
+    /** For button presses, checkbox toggles */
+    readonly buttonPress: HapticStyle;
+    /** For switch toggles */
+    readonly toggle: HapticStyle;
+    /** For successful actions */
+    readonly success: HapticStyle;
+    /** For errors */
+    readonly error: HapticStyle;
+    /** For selection changes (radio, picker) */
+    readonly selection: HapticStyle;
+    /** For destructive actions */
+    readonly destructive: HapticStyle;
+};
+/**
+ * Enable or disable haptic feedback globally.
+ *
+ * Use this to respect user preferences or accessibility settings.
+ *
+ * @param enabled - Whether to enable haptic feedback
+ *
+ * @example
+ * ```tsx
+ * // In ThemeProvider or app setup
+ * setHapticsEnabled(false);
+ *
+ * // Or via config
+ * <ThemeProvider haptics={false}>
+ * ```
+ */
+declare function setHapticsEnabled(enabled: boolean): void;
+/**
+ * Check if haptics are currently enabled.
+ *
+ * @returns True if haptics are enabled and expo-haptics is available
+ */
+declare function isHapticsEnabled(): boolean;
+/**
+ * Trigger haptic feedback.
+ *
+ * Respects the global haptics enabled state. Disabled via:
+ * - `setHapticsEnabled(false)`
+ * - `<ThemeProvider haptics={false}>`
+ *
+ * @param style - Haptic feedback style (defaults to 'light')
+ * @returns Promise that resolves when haptic completes
+ *
+ * @example
+ * ```tsx
+ * onPress={() => {
+ *   haptic('light');
+ *   // ... rest of handler
+ * }}
+ * ```
+ */
+declare function haptic(style?: HapticStyle): Promise<void>;
+/**
+ * Check if haptics are available.
+ *
+ * @returns True if expo-haptics is installed and can be used
+ */
+declare function hapticsAvailable(): boolean;
+
+/**
+ * Expo Go Detection Utility
+ *
+ * Provides detection for Expo Go environment to gracefully disable
+ * Reanimated animations when running in Expo Go client.
+ *
+ * @example
+ * ```tsx
+ * import { isExpoGo, areAnimationsDisabled } from '@metacells/mcellui-core';
+ *
+ * // Check environment
+ * if (isExpoGo()) {
+ *   console.log('Running in Expo Go');
+ * }
+ *
+ * // Check if animations should be disabled
+ * if (areAnimationsDisabled()) {
+ *   // Skip animation, use static styles
+ * }
+ * ```
+ */
+/**
+ * Check if the app is running in Expo Go client.
+ *
+ * Returns false in development builds, production builds, or non-Expo environments.
+ *
+ * @returns True if running in Expo Go client
+ */
+declare function isExpoGo(): boolean;
+/**
+ * Manually override the animation disabled state.
+ *
+ * Set to `true` to force disable animations, `false` to force enable,
+ * or `null` to use automatic detection (Expo Go = disabled).
+ *
+ * @param disabled - Override value (true/false) or null for automatic detection
+ */
+declare function setAnimationsDisabled(disabled: boolean | null): void;
+/**
+ * Check if animations should be disabled.
+ *
+ * Returns true if:
+ * - Manually overridden to true via setAnimationsDisabled(true)
+ * - Running in Expo Go (automatic detection)
+ *
+ * Returns false if:
+ * - Manually overridden to false via setAnimationsDisabled(false)
+ * - Running in development/production build
+ *
+ * @returns True if animations should be disabled
+ */
+declare function areAnimationsDisabled(): boolean;
+
+/**
+ * Typography Utilities
+ *
+ * Helper functions for working with typography tokens in React Native.
+ * React Native requires absolute lineHeight values (in pixels), not CSS
+ * multipliers like web.
+ *
+ * @example
+ * ```tsx
+ * import { getLineHeight, lineHeight, fontSize } from '@metacells/mcellui-core';
+ *
+ * // Instead of inline calculations:
+ * // lineHeight: fontSize.base * 1.5
+ *
+ * // Use the helper:
+ * lineHeight: getLineHeight(fontSize.base, lineHeight.normal)
+ * // or with shorthand:
+ * lineHeight: getLineHeight(14, 'normal')
+ * ```
+ */
+
+/**
+ * Calculates absolute lineHeight for React Native.
+ *
+ * React Native requires lineHeight as absolute pixel values, not CSS multipliers.
+ * This helper converts fontSize + multiplier into the correct absolute value.
+ *
+ * @param size - Font size in pixels (e.g., fontSize.base = 14)
+ * @param multiplier - Either a numeric multiplier (1.5) or a lineHeight key ('normal')
+ * @returns Absolute lineHeight in pixels
+ *
+ * @example
+ * ```tsx
+ * // Using numeric multiplier
+ * getLineHeight(14, 1.5) // => 21
+ *
+ * // Using lineHeight token key
+ * getLineHeight(fontSize.base, 'normal') // => 21
+ *
+ * // Using lineHeight token value directly
+ * getLineHeight(fontSize.base, lineHeight.normal) // => 21
+ * ```
+ */
+declare function getLineHeight(size: number, multiplier: number | LineHeightKey): number;
+/**
+ * Pre-computed lineHeight values for common fontSize + lineHeight combinations.
+ *
+ * Use these when you want consistent, pre-calculated values without calling
+ * getLineHeight() each time.
+ *
+ * @example
+ * ```tsx
+ * import { computedLineHeight } from '@metacells/mcellui-core';
+ *
+ * <Text style={{ fontSize: 14, lineHeight: computedLineHeight.base.normal }}>
+ *   Body text with normal line height
+ * </Text>
+ * ```
+ */
+declare const computedLineHeight: {
+    /** fontSize['2xs'] = 10 */
+    readonly '2xs': {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize.xs = 11 */
+    readonly xs: {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize.sm = 12 */
+    readonly sm: {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize.base = 14 */
+    readonly base: {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize.md = 16 */
+    readonly md: {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize.lg = 18 */
+    readonly lg: {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize.xl = 20 */
+    readonly xl: {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize['2xl'] = 24 */
+    readonly '2xl': {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize['3xl'] = 30 */
+    readonly '3xl': {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize['4xl'] = 36 */
+    readonly '4xl': {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+    /** fontSize['5xl'] = 48 */
+    readonly '5xl': {
+        readonly none: number;
+        readonly tight: number;
+        readonly snug: number;
+        readonly normal: number;
+        readonly relaxed: number;
+        readonly loose: number;
+    };
+};
+type ComputedLineHeightKey = keyof typeof computedLineHeight;
+
+export { buttonA11y as A, toggleA11y as B, linkA11y as C, imageA11y as D, headingA11y as E, type Fonts as F, type GeistFontFamilyKey as G, type A11yProps as H, haptic as I, hapticsAvailable as J, setHapticsEnabled as K, type LineHeightKey as L, isHapticsEnabled as M, hapticPresets as N, type HapticStyle as O, isExpoGo as P, setAnimationsDisabled as Q, areAnimationsDisabled as R, getLineHeight as S, type Typography as T, computedLineHeight as U, type ComputedLineHeightKey as V, fontWeight as a, letterSpacing as b, fontFamily as c, defaultFonts as d, createTypography as e, fontSize as f, geistFontFamily as g, type FontSizeKey as h, type FontWeightKey as i, type LetterSpacingKey as j, type FontFamilyKey as k, lineHeight as l, type TypographyKey as m, cn as n, mergeStyles as o, isIOS as p, isAndroid as q, isWeb as r, systemFonts as s, typography as t, iosVersion as u, androidApiLevel as v, isTablet as w, pixelRatio as x, roundToNearestPixel as y, getFontScale as z };