@codyswann/lisa 2.195.3 → 2.195.6

package/plugins/lisa-expo/.codex-plugin/skills/building-native-ui/references/zoom-transitions.md

@@ -0,0 +1,158 @@
+# Apple Zoom Transitions
+
+Fluid zoom transitions for navigating between screens. iOS 18+, Expo SDK 55+, Stack navigator only.
+
+```tsx
+import { Link } from "expo-router";
+```
+
+## Basic Zoom
+
+Use `withAppleZoom` on `Link.Trigger` to zoom the entire trigger element into the destination screen:
+
+```tsx
+<Link href="/photo" asChild>
+  <Link.Trigger withAppleZoom>
+    <Pressable>
+      <Image
+        source={{ uri: "https://example.com/thumb.jpg" }}
+        style={{ width: 120, height: 120, borderRadius: 12 }}
+      />
+    </Pressable>
+  </Link.Trigger>
+</Link>
+```
+
+## Targeted Zoom with `Link.AppleZoom`
+
+Wrap only the element that should animate. Siblings outside `Link.AppleZoom` are not part of the transition:
+
+```tsx
+<Link href="/photo" asChild>
+  <Link.Trigger>
+    <Pressable style={{ alignItems: "center" }}>
+      <Link.AppleZoom>
+        <Image
+          source={{ uri: "https://example.com/thumb.jpg" }}
+          style={{ width: 200, aspectRatio: 4 / 3 }}
+        />
+      </Link.AppleZoom>
+      <Text>Caption text (not zoomed)</Text>
+    </Pressable>
+  </Link.Trigger>
+</Link>
+```
+
+`Link.AppleZoom` accepts only a single child element.
+
+## Destination Target
+
+Use `Link.AppleZoomTarget` on the destination screen to align the zoom animation to a specific element:
+
+```tsx
+// Destination screen (e.g., app/photo.tsx)
+import { Link } from "expo-router";
+
+export default function PhotoScreen() {
+  return (
+    <View style={{ flex: 1 }}>
+      <Link.AppleZoomTarget>
+        <Image
+          source={{ uri: "https://example.com/full.jpg" }}
+          style={{ width: "100%", aspectRatio: 4 / 3 }}
+        />
+      </Link.AppleZoomTarget>
+      <Text>Photo details below</Text>
+    </View>
+  );
+}
+```
+
+Without a target, the zoom animates to fill the entire destination screen.
+
+## Custom Alignment Rectangle
+
+For manual control over where the zoom lands on the destination, use `alignmentRect` instead of `Link.AppleZoomTarget`:
+
+```tsx
+<Link.AppleZoom alignmentRect={{ x: 0, y: 0, width: 200, height: 300 }}>
+  <Image source={{ uri: "https://example.com/thumb.jpg" }} />
+</Link.AppleZoom>
+```
+
+Coordinates are in the destination screen's coordinate space. Prefer `Link.AppleZoomTarget` when possible — use `alignmentRect` only when the target element isn't available as a React component.
+
+## Controlling Dismissal
+
+Zoom screens support interactive dismissal gestures by default (pinch, swipe down when scrolled to top, swipe from leading edge). Use `usePreventZoomTransitionDismissal` on the destination screen to control this.
+
+### Disable all dismissal gestures
+
+```tsx
+import { usePreventZoomTransitionDismissal } from "expo-router";
+
+export default function PhotoScreen() {
+  usePreventZoomTransitionDismissal();
+  return <Image source={{ uri: "https://example.com/full.jpg" }} />;
+}
+```
+
+### Restrict dismissal to a specific area
+
+Use `unstable_dismissalBoundsRect` to prevent conflicts with scrollable content:
+
+```tsx
+usePreventZoomTransitionDismissal({
+  unstable_dismissalBoundsRect: {
+    minX: 0,
+    minY: 0,
+    maxX: 300,
+    maxY: 300,
+  },
+});
+```
+
+This is useful when the destination contains a zoomable scroll view — the system gives that scroll view precedence over the dismiss gesture.
+
+## Combining with Link.Preview
+
+Zoom transitions work alongside long-press previews:
+
+```tsx
+<Link href="/photo" asChild>
+  <Link.Trigger withAppleZoom>
+    <Pressable>
+      <Image
+        source={{ uri: "https://example.com/thumb.jpg" }}
+        style={{ width: 120, height: 120 }}
+      />
+    </Pressable>
+  </Link.Trigger>
+  <Link.Preview />
+</Link>
+```
+
+## Best Practices
+
+**Good use cases:**
+- Thumbnail → full image (gallery, profile photos)
+- Card → detail screen with similar visual content
+- Source and destination with similar aspect ratios
+
+**Avoid:**
+- Skinny full-width list rows as zoom sources — the transition looks unnatural
+- Mismatched aspect ratios between source and destination without `alignmentRect`
+- Using zoom with sheets or popovers — only works in Stack navigator
+- Hiding the navigation bar — known issues with header visibility during transitions
+
+**Tips:**
+- Always provide a close or back button — dismissal gestures are not discoverable
+- If the destination has a zoomable scroll view, use `unstable_dismissalBoundsRect` to avoid gesture conflicts
+- Source view doesn't need to match the tap target — only the `Link.AppleZoom` wrapped element animates
+- When source is unavailable (e.g., scrolled off screen), the transition zooms from the center of the screen
+
+## References
+
+- Expo Router Zoom Transitions: https://docs.expo.dev/router/advanced/zoom-transition/
+- Link.AppleZoom API: https://docs.expo.dev/versions/v55.0.0/sdk/router/#linkapplezoom
+- Apple UIKit Fluid Transitions: https://developer.apple.com/documentation/uikit/enhancing-your-app-with-fluid-transitions

package/plugins/lisa-expo/.codex-plugin/skills/container-view-pattern/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: container-view-pattern
+description: "This skill enforces the…"
+---
+
+# Container/View Pattern
+
+This skill provides guidance and validation for the Container/View component pattern used in this codebase.
+
+## Pattern Overview
+
+The Container/View pattern separates components into two distinct files:
+
+- **Container** (`*Container.tsx`): Handles logic, state, API calls, data fetching, and event handlers
+- **View** (`*View.tsx`): Handles rendering UI only, receiving all data and callbacks as props
+- **Index** (`index.tsx`): Exports the Container as the default component
+
+## Where This Pattern Applies
+
+The Container/View pattern is **required** in these directories:
+
+| Directory                | Applies | Notes                     |
+| ------------------------ | ------- | ------------------------- |
+| `features/*/components/` | Yes     | All feature components    |
+| `features/*/screens/`    | Yes     | All feature screens       |
+| `components/`            | Yes     | Shared components         |
+| `screens/`               | Yes     | Shared screens            |
+| `components/ui/`         | No      | UI primitives (GlueStack) |
+| `components/shared/`     | No      | Simple shared utilities   |
+| `components/icons/`      | No      | Icon components           |
+
+## When to Use This Skill
+
+- Creating a new component in any of the directories above
+- Validating that existing components follow the pattern
+- Refactoring a component to follow the pattern
+- Reviewing code for pattern compliance
+
+## Creating a New Component
+
+### Option 1: Use the Skill Generator Script
+
+Run the skill's generator script for any component type:
+
+```bash
+python3 .claude/skills/container-view-pattern/scripts/create_component.py <type> <name> [feature]
+```
+
+**Component Types:**
+
+| Type              | Command                                                          | Creates in                                      |
+| ----------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
+| Global component  | `create_component.py global-component PlayerCard`                | `components/PlayerCard/`                        |
+| Feature component | `create_component.py feature-component PlayerCard player-kanban` | `features/player-kanban/components/PlayerCard/` |
+| Global screen     | `create_component.py global-screen Settings`                     | `screens/Settings/`                             |
+| Feature screen    | `create_component.py feature-screen Main dashboard`              | `features/dashboard/screens/Main/`              |
+
+
+### Option 2: Manual Creation
+
+Create the following directory structure:
+
+```
+ComponentName/
+├── ComponentNameContainer.tsx
+├── ComponentNameView.tsx
+└── index.tsx
+```
+
+## Container Component Requirements
+
+Container components handle all business logic:
+
+1. **Single View render**: Container must ONLY render its corresponding View component - no other UI elements or components
+2. **State management**: Use `useState`, `useReducer`
+3. **Data fetching**: Use GraphQL hooks, API calls
+4. **Memoization**: Wrap all computed values in `useMemo`
+5. **Event handlers**: Wrap all handlers in `useCallback` with proper dependencies
+6. **Formatting**: All data transformation and formatting logic
+7. **Conditional logic**: Determine what state to pass to View (loading, error, empty flags)
+
+### Container Code Order (enforced by ESLint)
+
+Containers must follow this specific order:
+
+```tsx
+const ExampleContainer = () => {
+  // 1. Variables, state, useMemo, useCallback (same group)
+  const [state, setState] = useState();
+  const computed = useMemo(() => state * 2, [state]);
+  const handleClick = useCallback(() => {}, []);
+
+  // 2. useEffect hooks
+  useEffect(() => {
+    // side effects
+  }, []);
+
+  // 3. Return statement (always last)
+  return <ExampleView />;
+};
+```
+
+### Container Template
+
+```tsx
+import { useCallback, useMemo, useState } from "react";
+import ComponentNameView from "./ComponentNameView";
+
+/**
+ * Props for the ComponentName component.
+ */
+interface ComponentNameProps {
+  readonly id: string;
+}
+
+/**
+ * Container component that manages state and logic for ComponentName.
+ * @param props - Component properties
+ * @param props.id - The unique identifier
+ */
+const ComponentNameContainer = ({ id }: ComponentNameProps) => {
+  // State
+  const [isLoading, setIsLoading] = useState(false);
+
+  // Memoized computed values
+  const formattedData = useMemo(() => {
+    return data?.toUpperCase() ?? "";
+  }, [data]);
+
+  // Event handlers wrapped in useCallback
+  const handleSubmit = useCallback(() => {
+    setIsLoading(true);
+  }, []);
+
+  return (
+    <ComponentNameView
+      formattedData={formattedData}
+      isLoading={isLoading}
+      onSubmit={handleSubmit}
+    />
+  );
+};
+
+export default ComponentNameContainer;
+```
+
+## View Component Requirements
+
+View components are pure presentation:
+
+1. **Arrow function shorthand**: Use `() => (...)` not `() => { return (...); }`
+2. **No return statements**: The component body must be a single JSX expression
+3. **memo wrapper**: Export with `memo()` for performance optimization
+4. **displayName**: Set `ComponentName.displayName = "ComponentName"`
+5. **Readonly props**: All props should be marked as `readonly`
+6. **No hooks**: View should not contain `useState`, `useEffect`, `useMemo`, etc.
+7. **No logic**: All conditional rendering should use ternary expressions in JSX
+
+### View Template
+
+```tsx
+import { memo } from "react";
+
+import { Box } from "@/components/ui/box";
+import { Text } from "@/components/ui/text";
+
+/**
+ * Props for the ComponentNameView component.
+ */
+interface ComponentNameViewProps {
+  readonly formattedData: string;
+  readonly isLoading: boolean;
+  readonly onSubmit: () => void;
+}
+
+/**
+ * View component that renders the ComponentName UI.
+ * @param props - Component properties
+ * @param props.formattedData - Pre-formatted display data
+ * @param props.isLoading - Loading state indicator
+ * @param props.onSubmit - Submit handler callback
+ */
+const ComponentNameView = ({
+  formattedData,
+  isLoading,
+  onSubmit,
+}: ComponentNameViewProps) => (
+  <Box testID="COMPONENT_NAME.CONTAINER">
+    {isLoading ? <Text>Loading...</Text> : <Text>{formattedData}</Text>}
+  </Box>
+);
+
+ComponentNameView.displayName = "ComponentNameView";
+
+export default memo(ComponentNameView);
+```
+
+## Index File
+
+Export the Container as the default:
+
+```tsx
+export { default } from "./ComponentNameContainer";
+```
+
+## Validation
+
+### ESLint Rules
+
+The following ESLint rules enforce the pattern:
+
+| Rule                                              | Description                                   |
+| ------------------------------------------------- | --------------------------------------------- |
+| `component-structure/enforce-component-structure` | Validates directory structure and file naming |
+| `component-structure/no-return-in-view`           | Ensures View uses arrow shorthand             |
+| `component-structure/require-memo-in-view`        | Ensures View uses memo and displayName        |
+| `component-structure/single-component-per-file`   | One component per file                        |
+
+### Manual Validation
+
+Run the validation script to check a component:
+
+```bash
+python3 .claude/skills/container-view-pattern/scripts/validate_component.py <path-to-component-directory>
+```
+
+Run ESLint to check all components:
+
+```bash
+bun run lint
+```
+
+> **Note:** Replace `bun` with your project's package manager (`npm`, `yarn`, `pnpm`) as needed.
+
+## Common Violations
+
+### Container Violations
+
+| Issue                                | Resolution                                                  |
+| ------------------------------------ | ----------------------------------------------------------- |
+| Rendering UI elements besides View   | Container must ONLY return the corresponding View component |
+| Rendering multiple components        | Move all UI to View; Container returns only View            |
+| Missing `useMemo` for objects/arrays | Wrap computed values in `useMemo`                           |
+| Missing `useCallback` for functions  | Wrap handlers in `useCallback`                              |
+| Logic in View component              | Move logic to Container                                     |
+| Inline function props                | Create memoized handler                                     |
+
+### View Violations
+
+| Issue                         | Resolution                                        |
+| ----------------------------- | ------------------------------------------------- |
+| Using block body `{ return }` | Convert to arrow shorthand `() => (...)`          |
+| Missing `memo` wrapper        | Add `export default memo(ComponentView)`          |
+| Missing `displayName`         | Add `ComponentView.displayName = "ComponentView"` |
+| Contains hooks                | Move hooks to Container                           |
+| Contains state                | Move state to Container                           |
+
+## Extracting Helper Functions
+
+When View components exceed ESLint's cognitive complexity threshold (28), extract render helper functions. For simple cases, prefer inline JSX:
+
+```tsx
+/**
+ * Renders the loading skeleton state.
+ * @param props - Helper function properties
+ * @param props.isDark - Whether dark mode is active
+ */
+function renderLoadingState(props: { readonly isDark: boolean }) {
+  const { isDark } = props;
+  return <LoadingSkeleton isDark={isDark} />;
+}
+
+const ComponentView = ({ isLoading, isDark }: Props) => (
+  <Box>{isLoading ? renderLoadingState({ isDark }) : <Content />}</Box>
+);
+```
+
+## Event Handler Naming Convention
+
+- **Container**: Use `handle*` prefix (e.g., `handleSubmit`, `handleClick`)
+- **View props**: Use `on*` prefix (e.g., `onSubmit`, `onClick`)
+
+```tsx
+// Container
+const handleSubmit = useCallback(() => { ... }, []);
+return <ComponentView onSubmit={handleSubmit} />;
+
+// View
+const ComponentView = ({ onSubmit }: Props) => (
+  <Button onPress={onSubmit}>Submit</Button>
+);
+```
+
+## Reference Documentation
+
+For detailed examples and edge cases, read:
+
+- `references/patterns.md` - Common patterns and anti-patterns
+- `references/examples.md` - Complete component examples

package/plugins/lisa-expo/.codex-plugin/skills/container-view-pattern/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Container View Pattern"
+short_description: "This skill enforces the…"
+default_prompt:
+  - "Use $container-view-pattern: This skill enforces the…."