@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/expo/skills/cross-platform-compatibility/references/file-extensions.md

@@ -0,0 +1,340 @@
+# Platform-Specific File Extensions
+
+This reference documents Metro bundler's platform-specific file extension resolution for Expo/React Native projects.
+
+## Table of Contents
+
+- [Available Extensions](#available-extensions)
+- [Resolution Order](#resolution-order)
+- [Usage in app/ Directory](#usage-in-app-directory)
+- [Usage Outside app/ Directory](#usage-outside-app-directory)
+- [Patterns and Examples](#patterns-and-examples)
+- [TypeScript Considerations](#typescript-considerations)
+
+## Available Extensions
+
+| Extension      | Platforms     | Description                  |
+| -------------- | ------------- | ---------------------------- |
+| `.ios.tsx`     | iOS only      | iPhone and iPad              |
+| `.android.tsx` | Android only  | Android phones and tablets   |
+| `.native.tsx`  | iOS + Android | Shared native implementation |
+| `.web.tsx`     | Web only      | Browser environments         |
+| `.tsx`         | All platforms | Universal fallback           |
+
+## Resolution Order
+
+Metro resolves files in this priority order:
+
+### For iOS Build:
+
+1. `Component.ios.tsx`
+2. `Component.native.tsx`
+3. `Component.tsx`
+
+### For Android Build:
+
+1. `Component.android.tsx`
+2. `Component.native.tsx`
+3. `Component.tsx`
+
+### For Web Build:
+
+1. `Component.web.tsx`
+2. `Component.tsx`
+
+**Note:** `.native.tsx` is NOT resolved on web. Web only looks for `.web.tsx` or the base `.tsx`.
+
+## Usage in app/ Directory
+
+### Requirement: Base Version Required
+
+Platform-specific files in Expo Router's `app/` directory **must have a corresponding base version** to ensure route universality for deep linking.
+
+```
+app/
+├── _layout.tsx          ✅ Required base
+├── _layout.web.tsx      ✅ Web override
+├── index.tsx            ✅ Required base
+├── settings.tsx         ✅ Required base
+├── settings.native.tsx  ✅ Native override
+└── about.web.tsx        ❌ Missing base! Will cause issues
+```
+
+### Valid Combinations
+
+```
+# Layout with web override
+_layout.tsx + _layout.web.tsx          ✅
+
+# Screen with native override
+profile.tsx + profile.native.tsx       ✅
+
+# Screen with all platforms
+dashboard.tsx                          ✅ (base only)
+dashboard.tsx + dashboard.web.tsx      ✅
+dashboard.tsx + dashboard.ios.tsx + dashboard.android.tsx  ✅
+```
+
+### Invalid Combinations
+
+```
+# Missing base file
+_layout.web.tsx (no _layout.tsx)       ❌
+
+# Orphaned platform file
+settings.ios.tsx (no settings.tsx)     ❌
+```
+
+## Usage Outside app/ Directory
+
+Files outside the `app/` directory have more flexibility and do not require base versions.
+
+### Components Directory
+
+```
+components/
+├── Button/
+│   ├── ButtonContainer.tsx      # Shared container logic
+│   ├── ButtonView.tsx           # Default/fallback view
+│   ├── ButtonView.web.tsx       # Web-specific view
+│   └── index.tsx                # Exports container
+│
+├── DatePicker/
+│   ├── DatePickerContainer.tsx
+│   ├── DatePickerView.native.tsx  # iOS + Android
+│   ├── DatePickerView.web.tsx     # Web
+│   └── index.tsx
+│
+└── Camera/
+    ├── CameraContainer.tsx
+    ├── CameraView.ios.tsx         # iOS only
+    ├── CameraView.android.tsx     # Android only
+    ├── CameraView.web.tsx         # Web only
+    └── index.tsx
+```
+
+### Hooks Directory
+
+```
+hooks/
+├── useCamera.ts           # Shared hook interface
+├── useCamera.native.ts    # Native implementation
+├── useCamera.web.ts       # Web implementation
+│
+├── useHaptics.ts          # Base (may be no-op on web)
+└── useHaptics.native.ts   # Native with haptic feedback
+```
+
+### Utils Directory
+
+```
+utils/
+├── storage.ts             # Interface
+├── storage.native.ts      # AsyncStorage implementation
+└── storage.web.ts         # localStorage implementation
+```
+
+## Patterns and Examples
+
+### Pattern 1: Re-export from app/ Directory
+
+When you need platform-specific routes, create the implementation outside `app/` and re-export:
+
+```tsx
+// components/about/index.tsx
+// Platform-specific implementations live here
+
+// components/about/AboutScreen.tsx
+export const AboutScreen = () => <CommonAboutContent />;
+
+// components/about/AboutScreen.web.tsx
+export const AboutScreen = () => <WebSpecificAboutContent />;
+
+// app/about.tsx
+export { AboutScreen as default } from "@/components/about/AboutScreen";
+```
+
+### Pattern 2: Shared Container, Platform Views
+
+Following the Container/View pattern with platform-specific views:
+
+```tsx
+// components/FileUploader/FileUploaderContainer.tsx
+import FileUploaderView from "./FileUploaderView";
+
+const FileUploaderContainer = () => {
+  const [file, setFile] = useState<File | null>(null);
+
+  const handleUpload = useCallback(async () => {
+    // Shared upload logic
+  }, [file]);
+
+  return <FileUploaderView file={file} onUpload={handleUpload} />;
+};
+
+// components/FileUploader/FileUploaderView.native.tsx
+const FileUploaderView = ({ file, onUpload }: Props) => (
+  <TouchableOpacity onPress={onUpload}>
+    <Text>Upload from Device</Text>
+  </TouchableOpacity>
+);
+
+// components/FileUploader/FileUploaderView.web.tsx
+const FileUploaderView = ({ file, onUpload }: Props) => (
+  <input type="file" onChange={onUpload} />
+);
+```
+
+### Pattern 3: Platform-Specific Hooks
+
+```tsx
+// hooks/useClipboard.ts (interface/types)
+export interface UseClipboardResult {
+  readonly copy: (text: string) => Promise<void>;
+  readonly paste: () => Promise<string>;
+}
+
+// hooks/useClipboard.native.ts
+import * as Clipboard from "expo-clipboard";
+
+export const useClipboard = (): UseClipboardResult => ({
+  copy: async text => await Clipboard.setStringAsync(text),
+  paste: async () => await Clipboard.getStringAsync(),
+});
+
+// hooks/useClipboard.web.ts
+export const useClipboard = (): UseClipboardResult => ({
+  copy: async text => await navigator.clipboard.writeText(text),
+  paste: async () => await navigator.clipboard.readText(),
+});
+```
+
+### Pattern 4: Conditional Feature Files
+
+```tsx
+// features/ar-viewer/index.ts (base export)
+export { ARViewer } from "./ARViewer";
+
+// features/ar-viewer/ARViewer.tsx (fallback)
+export const ARViewer = () => <Text>AR is not supported on this platform</Text>;
+
+// features/ar-viewer/ARViewer.native.tsx
+import { ARView } from "react-native-ar";
+
+export const ARViewer = () => <ARView />;
+```
+
+## TypeScript Considerations
+
+### Shared Type Definitions
+
+Create a shared types file that all platform versions import:
+
+```tsx
+// components/Modal/types.ts
+export interface ModalProps {
+  readonly visible: boolean;
+  readonly onClose: () => void;
+  readonly children: React.ReactNode;
+}
+
+// components/Modal/ModalView.native.tsx
+import type { ModalProps } from "./types";
+
+const ModalView = ({ visible, onClose, children }: ModalProps) => (
+  // Native implementation
+);
+
+// components/Modal/ModalView.web.tsx
+import type { ModalProps } from "./types";
+
+const ModalView = ({ visible, onClose, children }: ModalProps) => (
+  // Web implementation
+);
+```
+
+### Module Declaration for Web APIs
+
+When using web-only libraries:
+
+```tsx
+// types/dom-to-image.d.ts
+declare module "dom-to-image" {
+  export function toJpeg(
+    node: HTMLElement | null,
+    options?: { quality?: number; width?: number; height?: number }
+  ): Promise<string>;
+
+  export function toPng(
+    node: HTMLElement | null,
+    options?: { width?: number; height?: number }
+  ): Promise<string>;
+}
+```
+
+### Platform-Specific Type Guards
+
+```tsx
+// types/platform.ts
+
+/**
+ * Type for web-specific window properties.
+ */
+declare global {
+  interface Window {
+    // Add web-specific properties
+  }
+}
+
+/**
+ * Ensures code only runs on web.
+ */
+export const assertWeb = (): void => {
+  if (Platform.OS !== "web") {
+    throw new Error("This code should only run on web");
+  }
+};
+```
+
+## Common Mistakes
+
+### 1. Missing Base File in app/
+
+```
+❌ app/settings.web.tsx (without app/settings.tsx)
+```
+
+**Fix:** Always create base file first, then add platform overrides.
+
+### 2. Expecting .native.tsx on Web
+
+```tsx
+// components/Button.native.tsx exists
+// Expecting it to work on web - it won't!
+```
+
+**Fix:** Either create `.web.tsx` or ensure `.tsx` base exists.
+
+### 3. Inconsistent Exports
+
+```tsx
+// Button.native.tsx
+export const Button = () => {};
+
+// Button.web.tsx
+export default function Button() {} // Different export style!
+```
+
+**Fix:** Use consistent export patterns across all platform versions.
+
+### 4. Different Props Between Platforms
+
+```tsx
+// Modal.native.tsx
+const Modal = ({ visible, animationType }: Props) => {};
+
+// Modal.web.tsx
+const Modal = ({ isOpen }: Props) => {}; // Different prop names!
+```
+
+**Fix:** Use shared type definitions to ensure consistent interfaces.

package/plugins/src/expo/skills/cross-platform-compatibility/references/platform-api.md

@@ -0,0 +1,276 @@
+# Platform Module API Reference
+
+This reference documents the React Native Platform module for cross-platform development.
+
+## Table of Contents
+
+- [Platform.OS](#platformos)
+- [Platform.select()](#platformselect)
+- [Platform.Version](#platformversion)
+- [Platform.isPad / Platform.isTV](#platformispad--platformistv)
+- [Best Practices](#best-practices)
+
+## Platform.OS
+
+Returns the current platform as a string.
+
+```tsx
+import { Platform } from "react-native";
+
+// Values: "ios" | "android" | "web" | "windows" | "macos"
+const currentPlatform = Platform.OS;
+```
+
+### Usage Patterns
+
+**Simple Conditional:**
+
+```tsx
+if (Platform.OS === "web") {
+  // Web-only code
+}
+```
+
+**Ternary Expression:**
+
+```tsx
+const buttonText = Platform.OS === "ios" ? "Done" : "OK";
+```
+
+**Switch Statement (for complex logic):**
+
+```tsx
+switch (Platform.OS) {
+  case "ios":
+    return handleIOS();
+  case "android":
+    return handleAndroid();
+  case "web":
+    return handleWeb();
+  default:
+    return handleDefault();
+}
+```
+
+## Platform.select()
+
+Returns platform-specific values from an object. Preferred for style objects and configuration.
+
+```tsx
+import { Platform, StyleSheet } from "react-native";
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    ...Platform.select({
+      ios: {
+        backgroundColor: "systemBackground",
+      },
+      android: {
+        backgroundColor: "#FFFFFF",
+      },
+      web: {
+        backgroundColor: "#FAFAFA",
+      },
+      default: {
+        backgroundColor: "#FFFFFF",
+      },
+    }),
+  },
+});
+```
+
+### Key Features
+
+- **default key**: Used when no platform-specific value matches
+- **native key**: Shorthand for iOS + Android (not web)
+- **Returns undefined**: If platform not found and no default
+
+```tsx
+// Using 'native' for iOS + Android
+Platform.select({
+  native: { padding: 20 },
+  web: { padding: 16 },
+});
+
+// Using 'default' as fallback
+Platform.select({
+  ios: "iOS specific",
+  default: "Everything else",
+});
+```
+
+## Platform.Version
+
+Returns the platform version.
+
+```tsx
+// iOS: Returns iOS version number (e.g., 17.0)
+// Android: Returns API level (e.g., 33)
+// Web: Returns undefined
+
+if (Platform.OS === "android" && Platform.Version >= 33) {
+  // Android 13+ specific code
+}
+
+if (Platform.OS === "ios" && parseInt(Platform.Version, 10) >= 17) {
+  // iOS 17+ specific code
+}
+```
+
+## Platform.isPad / Platform.isTV
+
+Boolean values for device type detection (iOS only).
+
+```tsx
+if (Platform.OS === "ios" && Platform.isPad) {
+  // iPad-specific layout
+}
+
+if (Platform.OS === "ios" && Platform.isTV) {
+  // Apple TV specific code
+}
+```
+
+## Best Practices
+
+### 1. Always Handle All Platforms
+
+```tsx
+// BAD: Only checks for web, undefined behavior on other platforms
+if (Platform.OS === "web") {
+  doWebThing();
+}
+// What happens on iOS/Android?
+
+// GOOD: Explicit handling or default
+if (Platform.OS === "web") {
+  doWebThing();
+} else {
+  doNativeThing();
+}
+
+// BETTER: Use Platform.select with default
+const behavior = Platform.select({
+  web: doWebThing,
+  default: doNativeThing,
+});
+```
+
+### 2. Prefer Platform.select for Objects
+
+```tsx
+// BAD: Verbose conditionals
+const shadowStyle =
+  Platform.OS === "ios"
+    ? { shadowColor: "#000" }
+    : Platform.OS === "android"
+      ? { elevation: 4 }
+      : { boxShadow: "0 2px 4px rgba(0,0,0,0.1)" };
+
+// GOOD: Clean Platform.select
+const shadowStyle = Platform.select({
+  ios: { shadowColor: "#000", shadowOpacity: 0.25 },
+  android: { elevation: 4 },
+  web: { boxShadow: "0 2px 4px rgba(0,0,0,0.1)" },
+});
+```
+
+### 3. Use Type Guards for TypeScript
+
+```tsx
+/**
+ * Type guard for web platform.
+ */
+const isWeb = Platform.OS === "web";
+
+/**
+ * Type guard for native platforms.
+ */
+const isNative = Platform.OS === "ios" || Platform.OS === "android";
+
+// Usage
+if (isWeb) {
+  // TypeScript knows this is web context
+}
+```
+
+### 4. Extract Platform Logic to Utilities
+
+```tsx
+// utils/platform.ts
+
+/**
+ * Checks if the current platform is web.
+ */
+export const isWeb = () => Platform.OS === "web";
+
+/**
+ * Checks if the current platform is native (iOS or Android).
+ */
+export const isNative = () => Platform.OS === "ios" || Platform.OS === "android";
+
+/**
+ * Checks if the current platform is iOS.
+ */
+export const isIOS = () => Platform.OS === "ios";
+
+/**
+ * Checks if the current platform is Android.
+ */
+export const isAndroid = () => Platform.OS === "android";
+
+/**
+ * Returns platform-specific value.
+ */
+export const platformValue = <T>(config: {
+  readonly ios?: T;
+  readonly android?: T;
+  readonly web?: T;
+  readonly native?: T;
+  readonly default?: T;
+}): T | undefined => Platform.select(config);
+```
+
+### 5. Avoid Nested Platform Checks
+
+```tsx
+// BAD: Nested and hard to read
+if (Platform.OS === "ios") {
+  if (Platform.Version >= 17) {
+    // ...
+  }
+} else if (Platform.OS === "android") {
+  if (Platform.Version >= 33) {
+    // ...
+  }
+}
+
+// GOOD: Extract to named functions
+const supportsNewFeature = () => {
+  if (Platform.OS === "ios") return parseInt(Platform.Version, 10) >= 17;
+  if (Platform.OS === "android") return Platform.Version >= 33;
+  return true; // Web always supports
+};
+
+if (supportsNewFeature()) {
+  // ...
+}
+```
+
+### 6. Document Platform-Specific Behavior
+
+```tsx
+/**
+ * Saves an image to the device.
+ *
+ * @remarks
+ * - iOS/Android: Saves to device media library
+ * - Web: Triggers browser download
+ *
+ * @param imageRef - Reference to the view to capture
+ */
+const saveImage = async (imageRef: React.RefObject<View>) => {
+  // Implementation
+};
+```