@metacells/mcellui-core 0.1.0

package/src/utils/accessibility.ts

@@ -0,0 +1,112 @@
+/**
+ * Accessibility Utilities
+ *
+ * Helpers for building accessible components
+ */
+
+import { AccessibilityRole, AccessibilityState } from 'react-native';
+
+export interface A11yProps {
+  accessible?: boolean;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  accessibilityRole?: AccessibilityRole;
+  accessibilityState?: AccessibilityState;
+}
+
+/**
+ * Creates accessibility props for a button
+ */
+export function buttonA11y(
+  label: string,
+  options?: {
+    hint?: string;
+    disabled?: boolean;
+    selected?: boolean;
+  }
+): A11yProps {
+  return {
+    accessible: true,
+    accessibilityRole: 'button',
+    accessibilityLabel: label,
+    accessibilityHint: options?.hint,
+    accessibilityState: {
+      disabled: options?.disabled,
+      selected: options?.selected,
+    },
+  };
+}
+
+/**
+ * Creates accessibility props for a checkbox/switch
+ */
+export function toggleA11y(
+  label: string,
+  checked: boolean,
+  options?: {
+    hint?: string;
+    disabled?: boolean;
+  }
+): A11yProps {
+  return {
+    accessible: true,
+    accessibilityRole: 'switch',
+    accessibilityLabel: label,
+    accessibilityHint: options?.hint,
+    accessibilityState: {
+      checked,
+      disabled: options?.disabled,
+    },
+  };
+}
+
+/**
+ * Creates accessibility props for a link
+ */
+export function linkA11y(
+  label: string,
+  options?: {
+    hint?: string;
+  }
+): A11yProps {
+  return {
+    accessible: true,
+    accessibilityRole: 'link',
+    accessibilityLabel: label,
+    accessibilityHint: options?.hint ?? 'Double tap to open',
+  };
+}
+
+/**
+ * Creates accessibility props for an image
+ */
+export function imageA11y(
+  label: string,
+  options?: {
+    decorative?: boolean;
+  }
+): A11yProps {
+  if (options?.decorative) {
+    return {
+      accessible: false,
+      accessibilityLabel: undefined,
+    };
+  }
+
+  return {
+    accessible: true,
+    accessibilityRole: 'image',
+    accessibilityLabel: label,
+  };
+}
+
+/**
+ * Creates accessibility props for a heading
+ */
+export function headingA11y(label: string): A11yProps {
+  return {
+    accessible: true,
+    accessibilityRole: 'header',
+    accessibilityLabel: label,
+  };
+}

package/src/utils/cn.ts

@@ -0,0 +1,58 @@
+/**
+ * cn() - Class Name / Style Merger
+ *
+ * The core utility for merging styles in nativeui.
+ * Inspired by shadcn/ui's cn() but adapted for React Native StyleSheet.
+ */
+
+import { StyleSheet, ViewStyle, TextStyle, ImageStyle } from 'react-native';
+
+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.
+ *
+ * @example
+ * ```tsx
+ * const styles = cn(
+ *   baseStyles.container,
+ *   isActive && activeStyles,
+ *   { padding: 16 }
+ * );
+ * ```
+ */
+export function cn(...inputs: StyleInput[]): Style {
+  const styles: Style[] = [];
+
+  for (const input of inputs) {
+    if (!input) continue;
+
+    if (Array.isArray(input)) {
+      const flattened = StyleSheet.flatten(input);
+      if (flattened) styles.push(flattened);
+    } else {
+      styles.push(input);
+    }
+  }
+
+  return StyleSheet.flatten(styles);
+}
+
+/**
+ * Creates a style object from conditional styles.
+ * More explicit alternative to cn() for complex conditions.
+ *
+ * @example
+ * ```tsx
+ * const styles = mergeStyles({
+ *   base: baseStyle,
+ *   active: isActive && activeStyle,
+ *   disabled: isDisabled && disabledStyle,
+ * });
+ * ```
+ */
+export function mergeStyles(styles: Record<string, StyleInput>): Style {
+  return cn(...Object.values(styles));
+}

package/src/utils/haptics.ts

@@ -0,0 +1,125 @@
+/**
+ * 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
+ */
+
+export type HapticStyle = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';
+
+/**
+ * Haptic presets for common interactions
+ */
+export const hapticPresets = {
+  /** For button presses, checkbox toggles */
+  buttonPress: 'light' as HapticStyle,
+  /** For switch toggles */
+  toggle: 'medium' as HapticStyle,
+  /** For successful actions */
+  success: 'success' as HapticStyle,
+  /** For errors */
+  error: 'error' as HapticStyle,
+  /** For selection changes (radio, picker) */
+  selection: 'selection' as HapticStyle,
+  /** For destructive actions */
+  destructive: 'warning' as HapticStyle,
+} as const;
+
+let Haptics: typeof import('expo-haptics') | null = null;
+
+// Try to load expo-haptics (optional dependency)
+try {
+  Haptics = require('expo-haptics');
+} catch {
+  // expo-haptics not available, haptics will be no-ops
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Global Haptics State
+// ─────────────────────────────────────────────────────────────────────────────
+
+let hapticsEnabled = true;
+
+/**
+ * Enable or disable haptic feedback globally.
+ * Use this to respect user preferences or accessibility settings.
+ *
+ * @example
+ * ```tsx
+ * // In ThemeProvider or app setup
+ * setHapticsEnabled(false);
+ *
+ * // Or via config
+ * <ThemeProvider haptics={false}>
+ * ```
+ */
+export function setHapticsEnabled(enabled: boolean): void {
+  hapticsEnabled = enabled;
+}
+
+/**
+ * Check if haptics are currently enabled
+ */
+export function isHapticsEnabled(): boolean {
+  return hapticsEnabled && Haptics !== null;
+}
+
+/**
+ * Trigger haptic feedback
+ *
+ * Respects the global haptics enabled state. Disabled via:
+ * - `setHapticsEnabled(false)`
+ * - `<ThemeProvider haptics={false}>`
+ * - `nativeui.config.ts` with `haptics: false`
+ *
+ * @example
+ * ```tsx
+ * onPress={() => {
+ *   haptic('light');
+ *   // ... rest of handler
+ * }}
+ * ```
+ */
+export async function haptic(style: HapticStyle = 'light'): Promise<void> {
+  if (!hapticsEnabled || !Haptics) return;
+
+  try {
+    switch (style) {
+      case 'light':
+        await Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+        break;
+      case 'medium':
+        await Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
+        break;
+      case 'heavy':
+        await Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Heavy);
+        break;
+      case 'success':
+        await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+        break;
+      case 'warning':
+        await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Warning);
+        break;
+      case 'error':
+        await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+        break;
+      case 'selection':
+        await Haptics.selectionAsync();
+        break;
+    }
+  } catch {
+    // Silently fail if haptics not supported
+  }
+}
+
+/**
+ * Check if haptics are available
+ */
+export function hapticsAvailable(): boolean {
+  return Haptics !== null;
+}

package/src/utils/index.ts

@@ -0,0 +1,28 @@
+export { cn, mergeStyles } from './cn';
+export {
+  isIOS,
+  isAndroid,
+  isWeb,
+  iosVersion,
+  androidApiLevel,
+  isTablet,
+  pixelRatio,
+  roundToNearestPixel,
+  getFontScale,
+} from './platform';
+export {
+  buttonA11y,
+  toggleA11y,
+  linkA11y,
+  imageA11y,
+  headingA11y,
+  type A11yProps,
+} from './accessibility';
+export {
+  haptic,
+  hapticsAvailable,
+  setHapticsEnabled,
+  isHapticsEnabled,
+  hapticPresets,
+  type HapticStyle,
+} from './haptics';

package/src/utils/platform.ts

@@ -0,0 +1,66 @@
+/**
+ * Platform Utilities
+ *
+ * Helpers for platform-specific behavior
+ */
+
+import { Platform, Dimensions, PixelRatio } from 'react-native';
+
+/**
+ * Check if running on iOS
+ */
+export const isIOS = Platform.OS === 'ios';
+
+/**
+ * Check if running on Android
+ */
+export const isAndroid = Platform.OS === 'android';
+
+/**
+ * Check if running on web
+ */
+export const isWeb = Platform.OS === 'web';
+
+/**
+ * Get iOS version (returns 0 on non-iOS)
+ */
+export const iosVersion = isIOS
+  ? parseInt(String(Platform.Version), 10)
+  : 0;
+
+/**
+ * Get Android API level (returns 0 on non-Android)
+ */
+export const androidApiLevel = isAndroid
+  ? (Platform.Version as number)
+  : 0;
+
+/**
+ * Check if device is a tablet (rough heuristic)
+ */
+export function isTablet(): boolean {
+  const { width, height } = Dimensions.get('window');
+  const aspectRatio = Math.max(width, height) / Math.min(width, height);
+  const isLargeScreen = Math.min(width, height) >= 600;
+
+  return isLargeScreen && aspectRatio < 1.6;
+}
+
+/**
+ * Get pixel ratio for crisp rendering
+ */
+export const pixelRatio = PixelRatio.get();
+
+/**
+ * Round to nearest pixel for crisp lines
+ */
+export function roundToNearestPixel(value: number): number {
+  return PixelRatio.roundToNearestPixel(value);
+}
+
+/**
+ * Get safe font scale (clamped for accessibility)
+ */
+export function getFontScale(maxScale = 1.3): number {
+  return Math.min(PixelRatio.getFontScale(), maxScale);
+}