@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/expo/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/plugins/src/expo/skills/ops-browser-uat/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ops-browser-uat
+description: Browser-based user acceptance testing via Playwright MCP tools. Logs into the application, navigates through features, and captures visual proof with screenshots.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Browser UAT
+
+Perform browser-based user acceptance testing using Playwright MCP tools.
+
+**Argument**: `$ARGUMENTS` — scenario and environment (e.g., `smoke-test dev`, `login staging`, `player-detail dev`, `custom production /path`)
+
+## Prerequisites
+
+1. **Load Playwright MCP tools** — use `ToolSearch` to search for `playwright browser` and load all browser tools.
+2. **Verify target environment is up** — curl check the frontend URL before launching the browser.
+3. **For localhost** — ensure the frontend is running on port 8081.
+
+## Discovery
+
+Before running any scenario, read these project files to discover configuration:
+
+1. **`e2e/constants.ts`** — environment URLs, test credentials (phone, OTP), timeouts, viewports
+2. **`e2e/selectors.ts`** — all `data-testid` values organized by feature area
+3. **`e2e/fixtures/auth.fixture.ts`** — exact login/logout flow to replicate via MCP tools
+4. **`playwright.config.ts`** — video/trace recording config, test directory
+
+## Authentication Procedure
+
+Replicate the login flow from `e2e/fixtures/auth.fixture.ts` using Playwright MCP tools. Read the file to get the exact steps, which typically follow this pattern:
+
+### Login
+
+1. `browser_navigate` to `{BASE_URL}/signin`
+2. `browser_snapshot` to discover page elements
+3. `browser_fill_form` — fill the phone input (discover placeholder text from auth fixture)
+4. Wait for form validation debounce (typically 500ms)
+5. `browser_click` — click the "Next" button
+6. `browser_wait_for` — wait for URL to contain `confirm-code` (timeout from constants)
+7. `browser_snapshot` to discover OTP input
+8. `browser_fill_form` — fill the OTP input (discover testid from selectors, value from constants)
+9. `browser_wait_for` — wait for URL to NOT contain `confirm-code`
+10. `browser_take_screenshot` — capture login proof
+
+### Dismiss Error Overlay
+
+Expo's development error overlay may appear. Dismiss it:
+
+1. `browser_evaluate` with script:
+   ```javascript
+   document.getElementById('error-overlay')?.remove();
+   document.querySelectorAll('[id*="error"]').forEach(el => el.remove());
+   ```
+2. `browser_press_key` — press "Escape" as backup
+
+### Check if Logged In
+
+```javascript
+// browser_evaluate
+localStorage.getItem("@authData") !== null
+```
+
+### Logout
+
+Discover the menu button and sign-out flow from `e2e/selectors.ts` and `e2e/fixtures/auth.fixture.ts`:
+
+1. `browser_click` — menu button element (discover testid from selectors)
+2. `browser_click` — element with text "Sign Out"
+3. `browser_wait_for` — URL contains `signin`
+
+## Selector Reference
+
+Read `e2e/selectors.ts` to get the complete `data-testid` reference for the project. The selectors object is organized by feature area (auth, nav, home sections, player detail, etc.).
+
+Use `[data-testid="{TESTID}"]` to target elements in Playwright MCP tools.
+
+## Built-in UAT Scenarios
+
+### 1. smoke-test
+
+Full app walkthrough. Read `e2e/selectors.ts` to identify which sections and elements to verify:
+
+1. **Login** (auth procedure above)
+2. **Home screen** — verify key sections exist using selectors from the project
+3. **Feature pages** — navigate to 2-3 key routes and verify content loads
+4. **Logout** → verify redirect to signin
+5. Screenshot at each step
+
+### 2. login
+
+Just the login flow with screenshot proof.
+
+### 3. home-screen
+
+Login → verify all home screen sections have data. Screenshot each section.
+
+### 4. custom
+
+Login → navigate to user-specified URL → interact as instructed → screenshot.
+
+## Proof Recording
+
+At each verification point:
+
+1. `browser_take_screenshot` — visual proof of current state
+2. `browser_console_messages` — check for JavaScript errors
+3. `browser_network_requests` — monitor for failed API calls (4xx, 5xx)
+
+## Output Format
+
+Report UAT results as a table:
+
+| Step | Action | Status | Notes |
+|------|--------|--------|-------|
+| 1 | Navigate to /signin | PASS | Page loaded in 1.2s |
+| 2 | Enter phone number | PASS | Input accepted |
+| 3 | Click Next | PASS | Navigated to /confirm-code |
+| 4 | Enter OTP | PASS | OTP accepted |
+| 5 | Verify home screen | PASS | All sections present |
+| 6 | Logout | PASS | Redirected to /signin |
+
+Include total PASS/FAIL count and any JS errors or failed network requests observed.