@codyswann/lisa 1.0.0

package/expo/copy-overwrite/.claude/skills/local-state/references/reactive-variables.md

@@ -0,0 +1,446 @@
+# Reactive Variables Reference
+
+## Overview
+
+Reactive variables are Apollo Client 3's mechanism for managing local state outside the GraphQL cache. They enable seamless reactivity without requiring GraphQL syntax and can store any data type.
+
+## Creating Reactive Variables
+
+### Basic Types
+
+```typescript
+import { makeVar } from "@apollo/client";
+
+// Boolean
+export const isLoadingVar = makeVar<boolean>(false);
+
+// String
+export const selectedIdVar = makeVar<string | null>(null);
+
+// Number
+export const countVar = makeVar<number>(0);
+```
+
+### Complex Types
+
+```typescript
+// Interface-based object
+interface IFilterValues {
+  readonly minAge: number;
+  readonly maxAge: number;
+  readonly positions: readonly string[];
+}
+
+const DEFAULT_FILTERS: IFilterValues = {
+  minAge: 18,
+  maxAge: 40,
+  positions: [],
+};
+
+export const filterValuesVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+```
+
+### Record Types for Lookups
+
+```typescript
+// Key-value lookup
+export const selectedPlayersVar = makeVar<Record<string, boolean>>({});
+
+// Complex value lookup
+interface PlayerNote {
+  readonly playerId: string;
+  readonly note: string;
+  readonly updatedAt: string;
+}
+
+export const playerNotesVar = makeVar<Record<string, PlayerNote>>({});
+```
+
+### Array Types
+
+```typescript
+interface Todo {
+  readonly id: string;
+  readonly text: string;
+  readonly completed: boolean;
+}
+
+type Todos = readonly Todo[];
+
+export const todosVar = makeVar<Todos>([]);
+```
+
+## Reading Values
+
+### Direct Read (Non-Reactive)
+
+Call without arguments to read current value. Does NOT trigger component re-renders:
+
+```typescript
+const currentFilters = filterValuesVar();
+const selectedPlayers = selectedPlayersVar();
+```
+
+Use for:
+
+- Event handlers
+- Utility functions
+- Async operations
+- Conditional logic outside JSX
+
+### Reactive Read with Hook
+
+Use `useReactiveVar` for components that should re-render on changes:
+
+```typescript
+import { useReactiveVar } from "@apollo/client";
+
+const FilterDisplay = () => {
+  const filters = useReactiveVar(filterValuesVar);
+
+  return (
+    <View>
+      <Text>Age: {filters.minAge} - {filters.maxAge}</Text>
+      <Text>Positions: {filters.positions.join(", ")}</Text>
+    </View>
+  );
+};
+```
+
+## Updating Values
+
+### Object Updates
+
+Always create new object references:
+
+```typescript
+// Single field update
+filterValuesVar({
+  ...filterValuesVar(),
+  minAge: 21,
+});
+
+// Multiple field update
+filterValuesVar({
+  ...filterValuesVar(),
+  minAge: 21,
+  maxAge: 35,
+});
+
+// Nested object update
+settingsVar({
+  ...settingsVar(),
+  display: {
+    ...settingsVar().display,
+    showGrid: true,
+  },
+});
+```
+
+### Array Updates
+
+```typescript
+// Add item
+todosVar([
+  ...todosVar(),
+  { id: crypto.randomUUID(), text: "New todo", completed: false },
+]);
+
+// Remove item
+todosVar(todosVar().filter(todo => todo.id !== idToRemove));
+
+// Update item
+todosVar(
+  todosVar().map(todo =>
+    todo.id === idToUpdate ? { ...todo, completed: true } : todo
+  )
+);
+
+// Clear all
+todosVar([]);
+```
+
+### Record Updates
+
+```typescript
+// Add/update entry
+selectedPlayersVar({
+  ...selectedPlayersVar(),
+  [playerId]: true,
+});
+
+// Remove entry (using destructuring)
+const { [playerIdToRemove]: _, ...remaining } = selectedPlayersVar();
+selectedPlayersVar(remaining);
+
+// Toggle entry
+const current = selectedPlayersVar();
+selectedPlayersVar({
+  ...current,
+  [playerId]: !current[playerId],
+});
+```
+
+## Custom Hooks Pattern
+
+Encapsulate reactive variable logic in custom hooks for better testability:
+
+```typescript
+import { makeVar, ReactiveVar, useReactiveVar } from "@apollo/client";
+import { useCallback } from "react";
+
+interface IFilterValues {
+  readonly minAge: number;
+  readonly maxAge: number;
+  readonly positions: readonly string[];
+}
+
+const DEFAULT_FILTERS: IFilterValues = {
+  minAge: 18,
+  maxAge: 40,
+  positions: [],
+};
+
+export const filterValuesVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+
+/**
+ * Custom hook for filter operations
+ * Encapsulates all filter state logic
+ */
+export const useFilters = () => {
+  const filters = useReactiveVar(filterValuesVar);
+
+  const setMinAge = useCallback((minAge: number) => {
+    filterValuesVar({ ...filterValuesVar(), minAge });
+  }, []);
+
+  const setMaxAge = useCallback((maxAge: number) => {
+    filterValuesVar({ ...filterValuesVar(), maxAge });
+  }, []);
+
+  const togglePosition = useCallback((position: string) => {
+    const current = filterValuesVar();
+    const hasPosition = current.positions.includes(position);
+    const positions = hasPosition
+      ? current.positions.filter(p => p !== position)
+      : [...current.positions, position];
+    filterValuesVar({ ...current, positions });
+  }, []);
+
+  const resetFilters = useCallback(() => {
+    filterValuesVar(DEFAULT_FILTERS);
+  }, []);
+
+  return {
+    filters,
+    setMinAge,
+    setMaxAge,
+    togglePosition,
+    resetFilters,
+  };
+};
+```
+
+## Dependency Injection for Testing
+
+Pass reactive variables as parameters for testable hooks:
+
+```typescript
+/**
+ * Testable hook with dependency injection
+ * @param filtersVar - Reactive variable (can be mocked in tests)
+ */
+export const useFiltersWithDI = (
+  filtersVar: ReactiveVar<IFilterValues> = filterValuesVar
+) => {
+  const filters = useReactiveVar(filtersVar);
+
+  const setMinAge = useCallback(
+    (minAge: number) => {
+      filtersVar({ ...filtersVar(), minAge });
+    },
+    [filtersVar]
+  );
+
+  return { filters, setMinAge };
+};
+
+// Test usage
+describe("useFiltersWithDI", () => {
+  it("should update minAge", () => {
+    const testVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+    const { result } = renderHook(() => useFiltersWithDI(testVar));
+
+    act(() => {
+      result.current.setMinAge(25);
+    });
+
+    expect(testVar().minAge).toBe(25);
+  });
+});
+```
+
+## Cache Type Policy Integration
+
+Connect reactive variables to GraphQL queries using field policies:
+
+```typescript
+import { InMemoryCache, makeVar } from "@apollo/client";
+import { gql } from "@apollo/client";
+
+// Reactive variable
+export const filterValuesVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+
+// Cache configuration
+export const cache = new InMemoryCache({
+  typePolicies: {
+    Query: {
+      fields: {
+        filterValues: {
+          read() {
+            return filterValuesVar();
+          },
+        },
+      },
+    },
+  },
+});
+
+// Query local state with @client directive
+export const GET_FILTER_VALUES = gql`
+  query GetFilterValues {
+    filterValues @client {
+      minAge
+      maxAge
+      positions
+    }
+  }
+`;
+
+// Use in component
+const FilterComponent = () => {
+  const { data } = useQuery(GET_FILTER_VALUES);
+  // data.filterValues is reactive
+};
+```
+
+## Performance Considerations
+
+### Split Large State
+
+Instead of one large reactive variable, use multiple smaller ones:
+
+```typescript
+// AVOID - single large state
+const appStateVar = makeVar({
+  user: {
+    /* ... */
+  },
+  settings: {
+    /* ... */
+  },
+  filters: {
+    /* ... */
+  },
+  selectedItems: {
+    /* ... */
+  },
+});
+
+// PREFER - separate concerns
+export const userVar = makeVar<User | null>(null);
+export const settingsVar = makeVar<Settings>(DEFAULT_SETTINGS);
+export const filtersVar = makeVar<Filters>(DEFAULT_FILTERS);
+export const selectedItemsVar = makeVar<Record<string, boolean>>({});
+```
+
+### Batch Related Updates
+
+Update multiple fields in a single call:
+
+```typescript
+// CORRECT - single update
+filterValuesVar({
+  ...filterValuesVar(),
+  minAge: 21,
+  maxAge: 35,
+  positions: ["QB", "WR"],
+});
+
+// AVOID - multiple sequential updates
+filterValuesVar({ ...filterValuesVar(), minAge: 21 });
+filterValuesVar({ ...filterValuesVar(), maxAge: 35 });
+filterValuesVar({ ...filterValuesVar(), positions: ["QB", "WR"] });
+```
+
+### Selector Pattern for Complex State
+
+Create selector wrappers to minimize re-renders:
+
+```typescript
+// Store
+export const allPlayersVar = makeVar<Record<string, Player>>({});
+
+// Selector hook - only re-renders when specific player changes
+export const usePlayer = (playerId: string): Player | undefined => {
+  const allPlayers = useReactiveVar(allPlayersVar);
+  return allPlayers[playerId];
+};
+
+// Component only re-renders when its specific player changes
+const PlayerCard = ({ playerId }: { playerId: string }) => {
+  const player = usePlayer(playerId);
+  return player ? <Text>{player.name}</Text> : null;
+};
+```
+
+## TypeScript Best Practices
+
+### Use Readonly Types
+
+Enforce immutability at the type level:
+
+```typescript
+interface IState {
+  readonly items: readonly Item[];
+  readonly metadata: Readonly<Metadata>;
+}
+
+export const stateVar = makeVar<IState>({
+  items: [],
+  metadata: { count: 0 },
+});
+```
+
+### Use Generic Constraints
+
+```typescript
+// Generic updater function
+const updateVar = <T extends Record<string, unknown>>(
+  reactiveVar: ReactiveVar<T>,
+  updates: Partial<T>
+): void => {
+  reactiveVar({ ...reactiveVar(), ...updates });
+};
+
+// Usage
+updateVar(settingsVar, { theme: "dark" });
+```
+
+### Export Types with Variables
+
+```typescript
+// Export both type and variable
+export interface IFilterValues {
+  readonly minAge: number;
+  readonly maxAge: number;
+}
+
+export const filterValuesVar = makeVar<IFilterValues>({
+  minAge: 18,
+  maxAge: 40,
+});
+
+// Re-export type for consumers
+export type { IFilterValues };
+```

package/expo/copy-overwrite/.claude/skills/playwright-selectors/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: playwright-selectors
+description: Best practices for adding testID and aria-label selectors for Playwright E2E testing in Expo web applications. This skill should be used when adding E2E test coverage, creating new components that need test selectors, or reviewing code for testability.
+---
+
+# Playwright Selectors Best Practices
+
+## Overview
+
+This skill provides guidance for adding effective selectors (testID, aria-labels) to Expo/React Native components for Playwright E2E testing. Proper selector strategy ensures tests are reliable, maintainable, and accessible.
+
+## Selector Priority
+
+Choose selectors based on their reliability and accessibility impact, in this priority order:
+
+| Priority | Selector Method | When to Use                               |
+| -------- | --------------- | ----------------------------------------- |
+| 1        | `getByRole`     | Interactive elements with semantic roles  |
+| 2        | `getByText`     | Visible text content                      |
+| 3        | `getByLabel`    | Form elements with labels                 |
+| 4        | `getByTestId`   | Fallback for elements without semantics   |
+
+### getByRole (Preferred)
+
+Use semantic roles when possible - they improve both accessibility and test resilience.
+
+```typescript
+// E2E test - preferred selector
+const submitButton = page.getByRole("button", { name: "Submit" });
+await expect(submitButton).toBeVisible();
+```
+
+### getByTestId (Fallback)
+
+Use testID when semantic selectors are not available, particularly for structural containers.
+
+```typescript
+// E2E test - fallback selector
+const container = page.getByTestId("home:container");
+await expect(container).toBeVisible();
+```
+
+## testID Naming Convention
+
+Use a namespaced pattern with colons as separators: `screen:element`
+
+### Format
+
+```
+{screen}:{element}
+```
+
+- **screen**: lowercase screen/feature name (e.g., `home`, `profile`, `settings`)
+- **element**: lowercase element identifier (e.g., `container`, `title`, `submit-button`)
+
+### Examples
+
+| testID                     | Description                      |
+| -------------------------- | -------------------------------- |
+| `home:container`           | Main container on home screen    |
+| `home:title`               | Title text on home screen        |
+| `profile:avatar`           | User avatar on profile screen    |
+| `settings:dark-mode-toggle`| Dark mode toggle in settings     |
+| `auth:login-button`        | Login button on auth screen      |
+
+### Rules
+
+1. Use lowercase only
+2. Use colons (`:`) to separate screen from element
+3. Use hyphens (`-`) for multi-word elements
+4. Be descriptive but concise
+5. Avoid redundant words (e.g., `home:home-title` should be `home:title`)
+
+## React Native to HTML Mapping
+
+Understanding how testID propagates from React Native to the web is essential.
+
+### How It Works
+
+1. React Native's `testID` prop is for native testing (XCUITest, Espresso)
+2. On web (via react-native-web), `testID` renders as `data-testid` in HTML
+3. Playwright's `getByTestId()` queries `data-testid` by default
+
+```typescript
+// React Native component
+<Box testID="home:container">...</Box>
+
+// Rendered HTML on web
+<div data-testid="home:container">...</div>
+
+// Playwright locator
+page.getByTestId("home:container")
+```
+
+### Gluestack UI Components
+
+Gluestack UI web components (Box, Text, etc.) require explicit testID handling because they use native HTML elements instead of react-native-web components. The web versions have been updated to:
+
+1. Accept a `testID` prop in the TypeScript type
+2. Map `testID` to `data-testid` on the rendered HTML element
+
+```typescript
+// Gluestack Box web implementation
+const Box = ({ testID, ...props }) => (
+  <div data-testid={testID} {...props} />
+);
+```
+
+## When to Add testID
+
+### Add testID To
+
+1. **Interactive elements** that E2E tests will click/interact with
+2. **Key structural containers** for page load verification
+3. **Dynamic content areas** that change based on state
+4. **Form elements** that lack semantic labels
+
+### Do Not Add testID To
+
+1. Every element (over-testing creates maintenance burden)
+2. Elements with good semantic selectors (use getByRole instead)
+3. Decorative elements not needed for testing
+4. Elements inside third-party components (may not propagate)
+
+## Accessibility Best Practices
+
+Prefer semantic selectors and aria-labels over testID when possible.
+
+### aria-label for Testing and Accessibility
+
+When adding labels for testing, use `aria-label` or `accessibilityLabel` to benefit screen reader users too.
+
+```typescript
+// Correct - benefits both testing and accessibility
+<Pressable
+  accessibilityLabel="Close dialog"
+  onPress={handleClose}
+>
+  <XIcon />
+</Pressable>
+
+// E2E test uses accessible name
+await page.getByRole("button", { name: "Close dialog" }).click();
+```
+
+### accessibilityRole for Semantic Elements
+
+Use `accessibilityRole` to provide semantic meaning on web.
+
+```typescript
+// Correct - semantic role for assistive technology
+<Box accessibilityRole="banner" testID="header:container">
+  <Text accessibilityRole="heading">Welcome</Text>
+</Box>
+
+// E2E test can use role
+await expect(page.getByRole("banner")).toBeVisible();
+await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
+```
+
+## Implementation Checklist
+
+When adding E2E test coverage to a component:
+
+- [ ] Identify elements that need selectors for testing
+- [ ] Prefer semantic selectors (role, text, label) when available
+- [ ] Use namespaced testID pattern for elements without semantics
+- [ ] Verify testID propagates to `data-testid` on web (check Gluestack components)
+- [ ] Add accessibility labels where beneficial
+- [ ] Document testIDs in component JSDoc preamble
+
+## Example Component
+
+```typescript
+/**
+ * Profile screen component.
+ *
+ * Test IDs for E2E testing:
+ * - `profile:container` - Main container
+ * - `profile:avatar` - User avatar image
+ * - `profile:name` - User display name
+ *
+ * @module features/profile/screens/Main
+ */
+export const ProfileScreen = () => (
+  <Box testID="profile:container" className="flex-1 p-4">
+    <Image
+      testID="profile:avatar"
+      source={{ uri: user.avatarUrl }}
+      accessibilityLabel={`${user.name}'s profile photo`}
+    />
+    <Text testID="profile:name" accessibilityRole="heading">
+      {user.name}
+    </Text>
+    <Pressable
+      accessibilityLabel="Edit profile"
+      onPress={handleEdit}
+    >
+      <Text>Edit</Text>
+    </Pressable>
+  </Box>
+);
+```
+
+## Corresponding E2E Test
+
+```typescript
+test.describe("Profile Screen", () => {
+  test("displays user information", async ({ page }) => {
+    await page.goto("/profile");
+
+    // Verify structural container
+    await expect(page.getByTestId("profile:container")).toBeVisible();
+
+    // Prefer accessible queries when available
+    await expect(page.getByRole("heading")).toHaveText("John Doe");
+    await expect(page.getByRole("button", { name: "Edit profile" })).toBeVisible();
+
+    // Use testID for elements without semantic roles
+    await expect(page.getByTestId("profile:avatar")).toBeVisible();
+  });
+});
+```