@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/expo/skills/container-view-pattern/scripts/validate_component.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+"""
+Validation script for Container/View pattern components.
+
+This script validates that a component directory follows the Container/View pattern:
+- Has ComponentNameContainer.tsx
+- Has ComponentNameView.tsx
+- Has index.tsx with correct export
+- View uses memo() wrapper
+- View has displayName
+- View uses arrow function shorthand
+
+Usage:
+    python3 validate_component.py <path-to-component-directory>
+
+Example:
+    python3 validate_component.py features/player-kanban/components/AddColumnButton
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def validate_component(component_path: str) -> tuple[bool, list[str]]:
+    """
+    Validate a component directory follows Container/View pattern.
+
+    Args:
+        component_path: Path to the component directory
+
+    Returns:
+        Tuple of (is_valid, list of error messages)
+    """
+    errors = []
+    component_dir = Path(component_path)
+
+    if not component_dir.is_dir():
+        return False, [f"Path is not a directory: {component_path}"]
+
+    component_name = component_dir.name
+
+    # Check required files exist
+    container_file = component_dir / f"{component_name}Container.tsx"
+    view_file = component_dir / f"{component_name}View.tsx"
+    index_file = component_dir / "index.tsx"
+
+    if not container_file.exists():
+        # Check for .jsx variant
+        container_jsx = component_dir / f"{component_name}Container.jsx"
+        if not container_jsx.exists():
+            errors.append(f"Missing Container file: {component_name}Container.tsx")
+        else:
+            container_file = container_jsx
+
+    if not view_file.exists():
+        # Check for .jsx variant
+        view_jsx = component_dir / f"{component_name}View.jsx"
+        if not view_jsx.exists():
+            errors.append(f"Missing View file: {component_name}View.tsx")
+        else:
+            view_file = view_jsx
+
+    if not index_file.exists():
+        index_jsx = component_dir / "index.jsx"
+        if not index_jsx.exists():
+            errors.append("Missing index.tsx file")
+        else:
+            index_file = index_jsx
+
+    # Validate index.tsx exports Container
+    if index_file.exists():
+        index_content = index_file.read_text()
+        export_pattern = rf"export\s*{{\s*default\s*}}\s*from\s*['\"]\./{component_name}Container['\"]"
+        if not re.search(export_pattern, index_content):
+            errors.append(f"index.tsx should export {component_name}Container as default")
+
+    # Validate View file
+    if view_file.exists():
+        view_content = view_file.read_text()
+
+        # Check for memo wrapper
+        memo_pattern = r"export\s+default\s+memo\s*\("
+        if not re.search(memo_pattern, view_content):
+            errors.append("View component should be wrapped with memo()")
+
+        # Check for displayName
+        display_name_pattern = rf"{component_name}View\.displayName\s*="
+        if not re.search(display_name_pattern, view_content):
+            errors.append(f"View should have displayName: {component_name}View.displayName = \"{component_name}View\"")
+
+        # Check for block body (return statement) in main component
+        # This is a simplified check - ESLint does the full validation
+        block_body_pattern = rf"const\s+{component_name}View\s*=\s*\([^)]*\)\s*=>\s*{{"
+        if re.search(block_body_pattern, view_content):
+            errors.append("View should use arrow function shorthand: () => (...) instead of () => { return (...) }")
+
+        # Check for hooks in View (they should be in Container)
+        hook_patterns = [
+            r"\buse[A-Z]\w+\s*\(",  # General hook pattern
+            r"\buseState\s*\(",
+            r"\buseEffect\s*\(",
+            r"\buseMemo\s*\(",
+            r"\buseCallback\s*\(",
+            r"\buseReducer\s*\(",
+            r"\buseContext\s*\(",
+        ]
+
+        for hook_pattern in hook_patterns:
+            # Exclude memo import check
+            if hook_pattern == r"\buse[A-Z]\w+\s*\(":
+                # More specific check to avoid false positives
+                if re.search(r"\buseState\s*\(", view_content):
+                    errors.append("View should not contain useState - move to Container")
+                    break
+                if re.search(r"\buseEffect\s*\(", view_content):
+                    errors.append("View should not contain useEffect - move to Container")
+                    break
+                if re.search(r"\buseMemo\s*\(", view_content):
+                    errors.append("View should not contain useMemo - move to Container")
+                    break
+                if re.search(r"\buseCallback\s*\(", view_content):
+                    errors.append("View should not contain useCallback - move to Container")
+                    break
+
+    # Validate Container file
+    if container_file.exists():
+        container_content = container_file.read_text()
+
+        # Check that Container imports View
+        import_view_pattern = rf"import\s+{component_name}View\s+from\s*['\"]\./{component_name}View['\"]"
+        if not re.search(import_view_pattern, container_content):
+            errors.append(f"Container should import {component_name}View")
+
+        # Check that Container returns View
+        return_view_pattern = rf"<{component_name}View"
+        if not re.search(return_view_pattern, container_content):
+            errors.append(f"Container should return <{component_name}View />")
+
+        # Check that Container ONLY renders View (no other JSX elements)
+        # Find all JSX tags in Container (excluding the View)
+        all_jsx_pattern = r"<([A-Z][a-zA-Z0-9]*)"
+        jsx_matches = re.findall(all_jsx_pattern, container_content)
+        other_components = [m for m in jsx_matches if m != f"{component_name}View"]
+        if other_components:
+            errors.append(
+                f"Container should ONLY render {component_name}View, but found: {', '.join(set(other_components))}"
+            )
+
+    # Check for extra files
+    allowed_files = {
+        f"{component_name}Container.tsx",
+        f"{component_name}Container.jsx",
+        f"{component_name}View.tsx",
+        f"{component_name}View.jsx",
+        "index.tsx",
+        "index.jsx",
+        "index.ts",
+        "__tests__",  # Allow test directory
+    }
+
+    # Also allow platform-specific variants
+    allowed_patterns = [
+        rf"^{component_name}Container\.[^.]+\.(tsx|jsx)$",
+        rf"^{component_name}View\.[^.]+\.(tsx|jsx)$",
+    ]
+
+    for item in component_dir.iterdir():
+        if item.name not in allowed_files:
+            is_allowed = False
+            for pattern in allowed_patterns:
+                if re.match(pattern, item.name):
+                    is_allowed = True
+                    break
+            if not is_allowed and item.is_file():
+                errors.append(f"Unexpected file in component directory: {item.name}")
+
+    return len(errors) == 0, errors
+
+
+def main():
+    """Main entry point for the validation script."""
+    if len(sys.argv) < 2:
+        print("Usage: python3 validate_component.py <path-to-component-directory>")
+        print("Example: python3 validate_component.py features/player-kanban/components/AddColumnButton")
+        sys.exit(1)
+
+    component_path = sys.argv[1]
+
+    print(f"Validating component: {component_path}")
+    print("-" * 50)
+
+    is_valid, errors = validate_component(component_path)
+
+    if is_valid:
+        print("Component follows Container/View pattern")
+        sys.exit(0)
+    else:
+        print("Validation errors found:")
+        for error in errors:
+            print(f"  - {error}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,268 @@
+---
+name: cross-platform-compatibility
+description: This skill enforces cross-platform compatibility best practices for Expo apps targeting iOS, Android, and web. It should be used when creating new features, components, or screens to ensure they work correctly on all platforms. Use this skill when writing platform-specific code, using Platform.OS checks, creating platform-specific files (.web.tsx, .native.tsx, .ios.tsx, .android.tsx), or reviewing code for cross-platform issues.
+---
+
+# Cross-Platform Compatibility
+
+This skill provides guidance for writing code that works correctly on iOS, Android, and web platforms in Expo applications.
+
+## Core Principle
+
+Every feature must work on **all three platforms** (iOS, Android, web) unless explicitly documented otherwise. Test on all platforms before considering a feature complete.
+
+## Platform-Specific Approaches
+
+There are two primary ways to handle platform differences:
+
+### 1. Platform Module (Runtime Checks)
+
+Use `Platform.OS` for small, inline differences within a single component.
+
+```tsx
+import { Platform } from "react-native";
+
+// Simple conditional
+if (Platform.OS === "web") {
+  // Web-specific code
+}
+
+// Platform.select for multiple platforms
+const styles = StyleSheet.create({
+  container: {
+    ...Platform.select({
+      ios: { shadowColor: "#000" },
+      android: { elevation: 4 },
+      web: { boxShadow: "0 2px 4px rgba(0,0,0,0.1)" },
+    }),
+  },
+});
+```
+
+### 2. Platform-Specific File Extensions
+
+Use file extensions when entire components or modules differ significantly between platforms.
+
+| Extension      | Platforms     | Use Case                        |
+| -------------- | ------------- | ------------------------------- |
+| `.web.tsx`     | Web only      | Web-specific implementation     |
+| `.native.tsx`  | iOS + Android | Shared native implementation    |
+| `.ios.tsx`     | iOS only      | iOS-specific implementation     |
+| `.android.tsx` | Android only  | Android-specific implementation |
+
+**Resolution Priority**: Metro bundler resolves in this order:
+
+1. `.ios.tsx` / `.android.tsx` (most specific)
+2. `.native.tsx` (native platforms)
+3. `.web.tsx` (web platform)
+4. `.tsx` (universal fallback)
+
+## Decision Tree: When to Use Each Approach
+
+```
+Need platform-specific behavior?
+├── Small differences (styles, one-liner logic)?
+│   └── Use Platform.OS or Platform.select()
+├── Moderate differences (conditional rendering blocks)?
+│   └── Use Platform.OS with clear separation
+└── Significant differences (entire component logic)?
+    └── Use platform-specific file extensions
+```
+
+### Use Platform.OS When:
+
+- Differences are 1-5 lines of code
+- Only styles differ between platforms
+- Logic is mostly shared with minor variations
+- You need to check platform at runtime dynamically
+
+### Use File Extensions When:
+
+- Components have fundamentally different implementations
+- Different libraries are needed per platform (e.g., `dom-to-image` for web vs `react-native-view-shot` for native)
+- Layout structure differs significantly
+- You want cleaner separation of concerns
+
+## File Extension Rules
+
+### Within `app/` Directory (Expo Router)
+
+Platform-specific extensions in the `app/` directory **require a base version** for route universality:
+
+```
+app/
+├── _layout.tsx          # Required base version
+├── _layout.web.tsx      # Optional web override
+├── index.tsx            # Required base version
+├── about.tsx            # Required base version
+└── about.web.tsx        # Optional web override
+```
+
+### Outside `app/` Directory
+
+Platform-specific files outside `app/` do not require a base version:
+
+```
+components/
+├── DatePicker/
+│   ├── DatePickerContainer.tsx      # Container (shared logic)
+│   ├── DatePickerView.tsx           # Default view
+│   ├── DatePickerView.web.tsx       # Web-specific view
+│   └── index.tsx                    # Exports container
+```
+
+### Re-exporting Pattern
+
+To use platform-specific components in routes:
+
+```tsx
+// components/about/index.tsx (or about.native.tsx + about.web.tsx)
+// Platform-specific implementations
+
+// app/about.tsx
+export { default } from "../components/about";
+```
+
+## Common Cross-Platform Issues
+
+### 1. Web-Incompatible APIs
+
+These APIs require Platform.OS checks or alternatives on web:
+
+| API                               | Issue on Web      | Solution                         |
+| --------------------------------- | ----------------- | -------------------------------- |
+| `MediaLibrary.saveToLibraryAsync` | Not supported     | Use download link on web         |
+| `Share.share()`                   | Limited support   | Use Web Share API or clipboard   |
+| `Haptics.*`                       | Not supported     | Skip or use CSS animations       |
+| `captureRef()`                    | Not supported     | Use `dom-to-image` on web        |
+| `Linking.openURL()`               | Works but differs | Consider `window.open()` for web |
+
+### 2. Style Differences
+
+```tsx
+// Platform-specific shadows
+const shadowStyles = Platform.select({
+  ios: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.25,
+    shadowRadius: 3.84,
+  },
+  android: {
+    elevation: 5,
+  },
+  web: {
+    boxShadow: "0 2px 4px rgba(0,0,0,0.25)",
+  },
+});
+```
+
+### 3. Layout Differences
+
+- Bottom tabs work differently on web vs native
+- Drawer navigation may need different treatment
+- Touch vs mouse interactions differ
+
+### 4. Gesture Handling
+
+```tsx
+// Web may need different gesture handlers
+const gestureConfig = Platform.select({
+  web: { enabled: false }, // Disable on web if using mouse
+  default: { enabled: true },
+});
+```
+
+## Implementation Patterns
+
+### Pattern 1: Platform-Specific Hook
+
+```tsx
+// hooks/useSaveImage.ts
+import { Platform } from "react-native";
+
+/**
+ * Hook for saving images with platform-specific implementations.
+ */
+export const useSaveImage = () => {
+  const saveImage = useCallback(async (imageRef: React.RefObject<View>) => {
+    if (Platform.OS === "web") {
+      // Web implementation using dom-to-image
+      const dataUrl = await domtoimage.toJpeg(imageRef.current);
+      const link = document.createElement("a");
+      link.download = "image.jpeg";
+      link.href = dataUrl;
+      link.click();
+    } else {
+      // Native implementation using view-shot
+      const uri = await captureRef(imageRef);
+      await MediaLibrary.saveToLibraryAsync(uri);
+    }
+  }, []);
+
+  return { saveImage };
+};
+```
+
+### Pattern 2: Platform-Specific Component Files
+
+```tsx
+// components/Modal/ModalView.native.tsx
+import { Modal as RNModal } from "react-native";
+
+const ModalView = ({ visible, children }: ModalViewProps) => (
+  <RNModal visible={visible} animationType="slide">
+    {children}
+  </RNModal>
+);
+
+// components/Modal/ModalView.web.tsx
+const ModalView = ({ visible, children }: ModalViewProps) =>
+  visible ? (
+    <div className="modal-overlay">
+      <div className="modal-content">{children}</div>
+    </div>
+  ) : null;
+```
+
+### Pattern 3: Conditional Feature Loading
+
+```tsx
+// Only import heavy libraries on platforms that need them
+const loadPlatformModule = async () => {
+  if (Platform.OS === "web") {
+    return await import("dom-to-image");
+  }
+  return await import("react-native-view-shot");
+};
+```
+
+## Validation Checklist
+
+Before submitting code, verify:
+
+- [ ] Component renders correctly on iOS
+- [ ] Component renders correctly on Android
+- [ ] Component renders correctly on web
+- [ ] Platform-specific files in `app/` have base versions
+- [ ] All Platform.OS checks handle all three platforms (or use `default`)
+- [ ] No web-incompatible APIs are called without Platform checks
+- [ ] Styles work on all platforms (shadows, layouts)
+- [ ] Touch/gesture handlers work on all platforms
+- [ ] No hardcoded platform assumptions
+
+## Running Validation
+
+To validate cross-platform compliance:
+
+```bash
+python3 .claude/skills/cross-platform-compatibility/scripts/validate_cross_platform.py [path]
+```
+
+## Reference Documentation
+
+For detailed patterns and examples:
+
+- `references/platform-api.md` - Platform module API reference
+- `references/file-extensions.md` - File extension patterns and resolution
+- `references/common-issues.md` - Platform-specific issues and solutions