@aspect-ops/exon-ui 0.0.1 → 0.0.3

package/dist/utils/haptics.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Haptics Utility - Cross-platform haptic feedback wrapper
+ *
+ * Wraps Capacitor Haptics with graceful web fallback (no-op on web).
+ * Uses optional peer dependency pattern - works without @capacitor/haptics installed.
+ * All functions are async and never throw - errors are caught silently.
+ */
+/**
+ * Triggers impact haptic feedback.
+ *
+ * @param style - Impact intensity: 'light', 'medium', or 'heavy'
+ * @returns Promise that resolves when haptic is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Light tap feedback
+ * await hapticImpact('light');
+ *
+ * // Heavy impact for important actions
+ * await hapticImpact('heavy');
+ * ```
+ */
+export declare function hapticImpact(style: 'light' | 'medium' | 'heavy'): Promise<void>;
+/**
+ * Triggers notification haptic feedback.
+ *
+ * @param type - Notification type: 'success', 'warning', or 'error'
+ * @returns Promise that resolves when haptic is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Success feedback after form submission
+ * await hapticNotification('success');
+ *
+ * // Warning feedback for validation issues
+ * await hapticNotification('warning');
+ *
+ * // Error feedback for failures
+ * await hapticNotification('error');
+ * ```
+ */
+export declare function hapticNotification(type: 'success' | 'warning' | 'error'): Promise<void>;
+/**
+ * Triggers selection change haptic feedback.
+ * Use this for UI selection changes like picker scrolling or toggle switches.
+ *
+ * @returns Promise that resolves when haptic is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Feedback when user changes selection
+ * function onSelectionChange(value: string) {
+ *   await hapticSelection();
+ *   setSelected(value);
+ * }
+ * ```
+ */
+export declare function hapticSelection(): Promise<void>;
+/**
+ * Triggers a simple vibration.
+ *
+ * @param duration - Vibration duration in milliseconds (default: 300ms)
+ * @returns Promise that resolves when vibration is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Default vibration
+ * await hapticVibrate();
+ *
+ * // Custom duration vibration
+ * await hapticVibrate(500);
+ * ```
+ */
+export declare function hapticVibrate(duration?: number): Promise<void>;
+/**
+ * Checks if haptics are available on the current platform.
+ * Useful for conditional UI that depends on haptic support.
+ *
+ * @returns Promise<boolean> - true if haptics are available
+ *
+ * @example
+ * ```typescript
+ * const hasHaptics = await isHapticsAvailable();
+ * if (hasHaptics) {
+ *   showHapticSettings();
+ * }
+ * ```
+ */
+export declare function isHapticsAvailable(): Promise<boolean>;

package/dist/utils/haptics.js

@@ -0,0 +1,198 @@
+/**
+ * Haptics Utility - Cross-platform haptic feedback wrapper
+ *
+ * Wraps Capacitor Haptics with graceful web fallback (no-op on web).
+ * Uses optional peer dependency pattern - works without @capacitor/haptics installed.
+ * All functions are async and never throw - errors are caught silently.
+ */
+// Cached Haptics module reference
+let hapticsModule = null;
+let hapticsLoaded = false;
+let hapticsAvailable = false;
+/**
+ * Checks if we're running in a Capacitor native environment
+ */
+function isCapacitorNative() {
+    if (typeof window === 'undefined')
+        return false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cap = window.Capacitor;
+    return cap?.isNativePlatform?.() ?? false;
+}
+/**
+ * Attempts to load the Capacitor Haptics module.
+ * Only attempts import in Capacitor native environment to avoid Vite build errors.
+ * Caches the result to avoid repeated dynamic imports.
+ */
+async function getHaptics() {
+    if (hapticsLoaded) {
+        return hapticsModule;
+    }
+    // Only attempt to load haptics in native Capacitor environment
+    if (!isCapacitorNative()) {
+        hapticsLoaded = true;
+        hapticsModule = null;
+        hapticsAvailable = false;
+        return null;
+    }
+    try {
+        // Dynamic import with variable to prevent Vite static analysis
+        const modulePath = '@capacitor/haptics';
+        const module = await import(/* @vite-ignore */ modulePath);
+        hapticsModule = module.Haptics;
+        hapticsAvailable = true;
+    }
+    catch {
+        // @capacitor/haptics not installed or import failed
+        hapticsModule = null;
+        hapticsAvailable = false;
+    }
+    hapticsLoaded = true;
+    return hapticsModule;
+}
+/**
+ * Style mapping from simple strings to Capacitor ImpactStyle values
+ */
+const impactStyleMap = {
+    light: 'Light',
+    medium: 'Medium',
+    heavy: 'Heavy'
+};
+/**
+ * Type mapping from simple strings to Capacitor NotificationType values
+ */
+const notificationTypeMap = {
+    success: 'Success',
+    warning: 'Warning',
+    error: 'Error'
+};
+/**
+ * Triggers impact haptic feedback.
+ *
+ * @param style - Impact intensity: 'light', 'medium', or 'heavy'
+ * @returns Promise that resolves when haptic is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Light tap feedback
+ * await hapticImpact('light');
+ *
+ * // Heavy impact for important actions
+ * await hapticImpact('heavy');
+ * ```
+ */
+export async function hapticImpact(style) {
+    try {
+        const haptics = await getHaptics();
+        if (haptics) {
+            await haptics.impact({ style: impactStyleMap[style] });
+        }
+    }
+    catch {
+        // Silently ignore errors - haptics should never break functionality
+    }
+}
+/**
+ * Triggers notification haptic feedback.
+ *
+ * @param type - Notification type: 'success', 'warning', or 'error'
+ * @returns Promise that resolves when haptic is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Success feedback after form submission
+ * await hapticNotification('success');
+ *
+ * // Warning feedback for validation issues
+ * await hapticNotification('warning');
+ *
+ * // Error feedback for failures
+ * await hapticNotification('error');
+ * ```
+ */
+export async function hapticNotification(type) {
+    try {
+        const haptics = await getHaptics();
+        if (haptics) {
+            await haptics.notification({ type: notificationTypeMap[type] });
+        }
+    }
+    catch {
+        // Silently ignore errors - haptics should never break functionality
+    }
+}
+/**
+ * Triggers selection change haptic feedback.
+ * Use this for UI selection changes like picker scrolling or toggle switches.
+ *
+ * @returns Promise that resolves when haptic is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Feedback when user changes selection
+ * function onSelectionChange(value: string) {
+ *   await hapticSelection();
+ *   setSelected(value);
+ * }
+ * ```
+ */
+export async function hapticSelection() {
+    try {
+        const haptics = await getHaptics();
+        if (haptics) {
+            await haptics.selectionChanged();
+        }
+    }
+    catch {
+        // Silently ignore errors - haptics should never break functionality
+    }
+}
+/**
+ * Triggers a simple vibration.
+ *
+ * @param duration - Vibration duration in milliseconds (default: 300ms)
+ * @returns Promise that resolves when vibration is complete (or immediately on web)
+ *
+ * @example
+ * ```typescript
+ * // Default vibration
+ * await hapticVibrate();
+ *
+ * // Custom duration vibration
+ * await hapticVibrate(500);
+ * ```
+ */
+export async function hapticVibrate(duration = 300) {
+    try {
+        const haptics = await getHaptics();
+        if (haptics) {
+            await haptics.vibrate({ duration });
+        }
+    }
+    catch {
+        // Silently ignore errors - haptics should never break functionality
+    }
+}
+/**
+ * Checks if haptics are available on the current platform.
+ * Useful for conditional UI that depends on haptic support.
+ *
+ * @returns Promise<boolean> - true if haptics are available
+ *
+ * @example
+ * ```typescript
+ * const hasHaptics = await isHapticsAvailable();
+ * if (hasHaptics) {
+ *   showHapticSettings();
+ * }
+ * ```
+ */
+export async function isHapticsAvailable() {
+    try {
+        await getHaptics();
+        return hapticsAvailable;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/platform.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Platform Detection Utility
+ * Detects the current platform (iOS, Android, or Web) using Capacitor when available.
+ * Provides graceful fallback when Capacitor is not installed or not running in a native context.
+ */
+/**
+ * Supported platform types
+ */
+export type Platform = 'ios' | 'android' | 'web';
+/**
+ * Initialize platform detection asynchronously
+ * Call this early in your app lifecycle for most accurate detection
+ * @returns Promise that resolves when platform is detected
+ */
+export declare function initPlatform(): Promise<Platform>;
+/**
+ * Get the current platform
+ * Returns immediately with best available detection (may use sync fallback)
+ * For guaranteed accuracy, call initPlatform() first and await it
+ * @returns The detected platform
+ */
+export declare function getPlatform(): Platform;
+/**
+ * Check if running on iOS
+ * @returns true if the current platform is iOS
+ */
+export declare function isIOS(): boolean;
+/**
+ * Check if running on Android
+ * @returns true if the current platform is Android
+ */
+export declare function isAndroid(): boolean;
+/**
+ * Check if running as a native app (iOS or Android)
+ * @returns true if running in a native Capacitor context
+ */
+export declare function isNative(): boolean;
+/**
+ * Check if running on web (browser without native wrapper)
+ * @returns true if running in a standard web browser
+ */
+export declare function isWeb(): boolean;
+/**
+ * Reset platform detection (useful for testing)
+ * @internal
+ */
+export declare function _resetPlatform(): void;

package/dist/utils/platform.js

@@ -0,0 +1,156 @@
+/**
+ * Platform Detection Utility
+ * Detects the current platform (iOS, Android, or Web) using Capacitor when available.
+ * Provides graceful fallback when Capacitor is not installed or not running in a native context.
+ */
+/**
+ * Internal state - initialized lazily on first access
+ */
+let _platform = 'web';
+let _initialized = false;
+/**
+ * Initialize platform detection
+ * Uses dynamic import to gracefully handle cases where @capacitor/core is not installed
+ */
+async function initializePlatform() {
+    if (_initialized)
+        return;
+    try {
+        // Dynamic import to handle cases where Capacitor is not installed
+        const capacitorModule = (await import('@capacitor/core'));
+        const Capacitor = capacitorModule.Capacitor;
+        if (Capacitor && typeof Capacitor.getPlatform === 'function') {
+            const detectedPlatform = Capacitor.getPlatform();
+            if (detectedPlatform === 'ios' ||
+                detectedPlatform === 'android' ||
+                detectedPlatform === 'web') {
+                _platform = detectedPlatform;
+            }
+        }
+    }
+    catch {
+        // Capacitor not available - default to 'web'
+        _platform = 'web';
+    }
+    _initialized = true;
+}
+/**
+ * Synchronous platform detection using user agent as fallback
+ * This is used for immediate platform detection without async initialization
+ */
+function detectPlatformSync() {
+    if (_initialized)
+        return _platform;
+    // Check if running in browser environment
+    if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+        return 'web';
+    }
+    // Try synchronous Capacitor detection first
+    try {
+        // Check for Capacitor global (may be available if loaded synchronously)
+        const win = window;
+        if (win.Capacitor && typeof win.Capacitor.getPlatform === 'function') {
+            const detectedPlatform = win.Capacitor.getPlatform();
+            if (detectedPlatform === 'ios' ||
+                detectedPlatform === 'android' ||
+                detectedPlatform === 'web') {
+                _platform = detectedPlatform;
+                _initialized = true;
+                return _platform;
+            }
+        }
+    }
+    catch {
+        // Capacitor not available synchronously
+    }
+    // Fallback to user agent detection for native webviews
+    const userAgent = navigator.userAgent.toLowerCase();
+    // Check for iOS (iPhone, iPad, iPod)
+    if (/iphone|ipad|ipod/.test(userAgent)) {
+        // Additional check for native iOS app context
+        const isNativeIOS = /capacitor|ionic|cordova/.test(userAgent) ||
+            window.webkit?.messageHandlers !==
+                undefined;
+        if (isNativeIOS) {
+            _platform = 'ios';
+            _initialized = true;
+            return _platform;
+        }
+    }
+    // Check for Android
+    if (/android/.test(userAgent)) {
+        // Additional check for native Android app context
+        const isNativeAndroid = /capacitor|ionic|cordova/.test(userAgent) ||
+            window.AndroidBridge !== undefined;
+        if (isNativeAndroid) {
+            _platform = 'android';
+            _initialized = true;
+            return _platform;
+        }
+    }
+    // Default to web
+    _platform = 'web';
+    _initialized = true;
+    return _platform;
+}
+/**
+ * Initialize platform detection asynchronously
+ * Call this early in your app lifecycle for most accurate detection
+ * @returns Promise that resolves when platform is detected
+ */
+export async function initPlatform() {
+    await initializePlatform();
+    return _platform;
+}
+/**
+ * Get the current platform
+ * Returns immediately with best available detection (may use sync fallback)
+ * For guaranteed accuracy, call initPlatform() first and await it
+ * @returns The detected platform
+ */
+export function getPlatform() {
+    if (!_initialized) {
+        // Use sync detection for immediate response
+        detectPlatformSync();
+        // Also kick off async detection for future calls
+        initializePlatform();
+    }
+    return _platform;
+}
+/**
+ * Check if running on iOS
+ * @returns true if the current platform is iOS
+ */
+export function isIOS() {
+    return getPlatform() === 'ios';
+}
+/**
+ * Check if running on Android
+ * @returns true if the current platform is Android
+ */
+export function isAndroid() {
+    return getPlatform() === 'android';
+}
+/**
+ * Check if running as a native app (iOS or Android)
+ * @returns true if running in a native Capacitor context
+ */
+export function isNative() {
+    const platform = getPlatform();
+    return platform === 'ios' || platform === 'android';
+}
+/**
+ * Check if running on web (browser without native wrapper)
+ * @returns true if running in a standard web browser
+ */
+export function isWeb() {
+    return getPlatform() === 'web';
+}
+/**
+ * Reset platform detection (useful for testing)
+ * @internal
+ */
+export function _resetPlatform() {
+    _platform = 'web';
+    _initialized = false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aspect-ops/exon-ui",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "Reusable Svelte UI components for web and Capacitor mobile apps",
 	"author": "Exon Team",
 	"license": "MIT",