@shaykec/bridge 0.4.25 → 0.4.27

package/modules/react-fundamentals/resources.md

@@ -0,0 +1,42 @@
+# React — Resources
+
+## Videos
+
+- [React in 100 Seconds](https://www.youtube.com/watch?v=Tn6-PIqc4UM) — Fireship. Quick conceptual overview.
+- [React Hooks Course](https://www.youtube.com/watch?v=6LVm2j0yTiU) — Web Dev Simplified. Deep dive on useState, useEffect, and more.
+- [Complete React Course](https://www.youtube.com/watch?v=Rh3tobg7hZo) — freeCodeCamp. Full beginner track.
+
+## Articles and Readings
+
+- [React Docs — Learn React](https://react.dev/learn) — Official tutorial. Start here for fundamentals.
+- [A Complete Guide to useEffect](https://overreacted.io/a-complete-guide-to-useeffect/) — Dan Abramov. Canonical reference for understanding effects.
+
+## Books
+
+- **React in Action** by Mark Thomas — Practical patterns and real-world examples.
+- **Learning React** by Alex Banks & Eve Porcello — Clear, modern introduction.
+
+## Tools and Playgrounds
+
+- [CodeSandbox](https://codesandbox.io) — Online React playground, no setup.
+- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/) — TypeScript + React patterns.
+- [React DevTools](https://react.dev/learn/react-developer-tools) — Browser extension for inspecting components and state.
+- [StackBlitz](https://stackblitz.com/) — Instant full-stack React environment in the browser.
+
+## Podcasts
+
+- [Syntax.fm](https://syntax.fm/) — Wes Bos & Scott Tolinski. Frequent React/web dev episodes.
+- [React Podcast](https://spec.fm/podcasts/reactpodcast) — Interviews with React core team and community.
+- [JS Party](https://changelog.com/jsparty) — Weekly panel show covering JavaScript and React ecosystem news.
+
+## Interactive and Visual
+
+- [React Visualized (react.gg)](https://react.gg/) — Visual, animated explanations of React concepts.
+- [useHooks](https://usehooks.com/) — Visual catalog of reusable React hooks with code.
+- [React Lifecycle Diagram](https://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/) — Interactive diagram of component lifecycle phases.
+
+## Courses
+
+- [React — Official Tutorial](https://react.dev/learn/tutorial-tic-tac-toe) — Build tic-tac-toe step by step, from the React team.
+- [freeCodeCamp — Front End Libraries](https://www.freecodecamp.org/learn/front-end-development-libraries/) — Free certification covering React fundamentals.
+- [Epic React (Kent C. Dodds)](https://epicreact.dev/) — Comprehensive paid workshop series on React patterns.

package/modules/react-fundamentals/walkthrough.md

@@ -0,0 +1,89 @@
+# React Walkthrough — Learn by Doing
+
+## Step 1: Your First Component
+
+Let's create a simple React component.
+
+**Embed:** https://react.dev/learn/your-first-component
+
+<!-- hint:code language="jsx" highlight="1,3" -->
+
+**Task:** Write a functional component called `Greeting` that accepts a `name` prop and renders "Hello, {name}!".
+
+**Question:** What do you think happens when you pass a prop that the component doesn't use? Would it cause an error?
+
+**Checkpoint:** The user has a working Greeting component and understands that unused props are simply ignored.
+
+---
+
+## Step 2: Adding State — Counter
+
+Now let's make something interactive with `useState`.
+
+**Embed:** https://react.dev/reference/react/useState
+
+<!-- hint:card type="concept" title="useState triggers re-renders — setState causes React to re-run your component" -->
+
+**Task:** Create a `Counter` component with a number state that starts at 0. Add a button that increments it when clicked.
+
+**Question:** When you click the button, what actually triggers the number on screen to change? Trace the flow from click to DOM update in your mind.
+
+**Checkpoint:** The user has a working counter and can explain that `setCount` triggers a re-render with the new value.
+
+---
+
+## Step 3: Counter Refinement
+
+Let's extend the counter.
+
+**Task:** Add a second button that decrements the count. Add a "Reset" button that sets it back to 0. Prevent the count from going below 0.
+
+**Question:** Why might you choose to clamp the value inside the click handler rather than in the render?
+
+**Checkpoint:** The user has increment, decrement, and reset, and understands validation in handlers.
+
+---
+
+## Step 4: useEffect Introduction
+
+**Embed:** https://react.dev/reference/react/useEffect
+
+<!-- hint:diagram mermaid-type="flowchart" topic="React render cycle: render → commit → effect" -->
+
+**Task:** Use `useEffect` to update the browser tab title to show the current count (e.g., "Count: 3").
+
+**Question:** What happens if you omit the dependency array from `useEffect`? What if you use an empty array `[]`?
+
+**Checkpoint:** The user understands dependency arrays — empty = run once, omitted = run every render.
+
+---
+
+## Step 5: Conditional Rendering
+
+**Task:** In your counter, show "Count is zero" when the count is 0, and the normal count display otherwise. Maybe add a celebratory message when count reaches 10.
+
+**Question:** When would you use `&&` vs a ternary for conditional rendering? What are the tradeoffs?
+
+**Checkpoint:** The user can use both patterns and explain when each makes sense.
+
+---
+
+## Step 6: Todo List — Adding Items
+
+**Task:** Build the start of a todo list. Use `useState` with an array of items. Add an input and a button to append a new todo. Render the list with `map`.
+
+**Question:** Why is it important to give each list item a stable `key`? What could go wrong if you use the array index as the key when items can be reordered or deleted?
+
+**Checkpoint:** The user has a list with keys and understands key stability.
+
+---
+
+## Step 7: Todo List — Toggling and Filtering
+
+<!-- hint:celebrate -->
+
+**Task:** Add a checkbox to each todo to mark it complete (strikethrough completed items). Add a filter: "All", "Active", "Completed". Use conditional rendering and `filter()`.
+
+**Question:** Where should the filtered list be computed — in state, or derived at render time? What's the difference?
+
+**Checkpoint:** The user understands derived state vs stored state — filters are typically derived.

package/modules/react-fundamentals/workshop.yaml

@@ -0,0 +1,112 @@
+# React Fundamentals — Interactive Workshop Scenarios
+# Build components with useState, lists, and useEffect.
+
+scenarios:
+  - id: counter-component
+    title: "Build a Counter with useState"
+    difficulty: beginner
+    xp: 25
+    setup:
+      - "mkdir -p counter && cd counter && npm init -y && npm install react react-dom"
+    files:
+      - name: Counter.jsx
+        content: |
+          import React from "react";
+
+          export default function Counter() {
+            return (
+              <div>
+                <p>Count: 0</p>
+                <button>Increment</button>
+              </div>
+            );
+          }
+        language: javascript
+        readonly: false
+    task: "Add state for the count using useState. Initialize it to 0. Make the Increment button update the count when clicked. Display the current count in the paragraph."
+    validations:
+      - label: "Counter uses useState and increments"
+        check: file-changed
+        pattern: "useState|setCount|onClick"
+    hints:
+      - "Import useState: import { useState } from 'react';"
+      - "Add state: const [count, setCount] = useState(0);"
+      - "The button needs onClick={() => setCount(count + 1)} and the paragraph should show {count}."
+    agent_prompts:
+      on_start: "Right now the count is hardcoded as 0. What would need to change for the number to update when the user clicks?"
+
+  - id: todo-list
+    title: "Build a Todo List with State Management"
+    difficulty: intermediate
+    xp: 35
+    setup:
+      - "mkdir -p todo-list && cd todo-list && npm init -y && npm install react react-dom"
+    files:
+      - name: TodoApp.jsx
+        content: |
+          import React, { useState } from "react";
+
+          export default function TodoApp() {
+            const [todos, setTodos] = useState([]);
+            const [input, setInput] = useState("");
+
+            return (
+              <div>
+                <input
+                  value={input}
+                  onChange={(e) => setInput(e.target.value)}
+                  placeholder="Add a todo"
+                />
+                <button>Add</button>
+                <ul>
+                  {/* Todo items will go here */}
+                </ul>
+              </div>
+            );
+          }
+        language: javascript
+        readonly: false
+    task: "Implement add (append new todo on Add click), remove (delete a todo by id or index), and toggle (mark todo complete/incomplete). Each todo should have id, text, and done. Display todos with checkboxes and a way to remove each."
+    validations:
+      - label: "Todo add, remove, and toggle implemented"
+        check: file-changed
+        pattern: "setTodos|add|toggle|remove"
+    hints:
+      - "Use a unique id for each todo — Date.now() or crypto.randomUUID() works."
+      - "To add: setTodos([...todos, { id, text: input, done: false }]) then clear input."
+      - "To toggle: map over todos and flip done for the matching id. To remove: filter out by id."
+    agent_prompts:
+      on_start: "You have an array of todos and an input. What happens when the user clicks Add? What shape should each todo item have?"
+
+  - id: api-fetch
+    title: "Fetch Data with useEffect"
+    difficulty: intermediate
+    xp: 35
+    setup:
+      - "mkdir -p api-fetch && cd api-fetch && npm init -y && npm install react react-dom"
+    files:
+      - name: UserList.jsx
+        content: |
+          import React, { useState, useEffect } from "react";
+
+          export default function UserList() {
+            return (
+              <div>
+                <h2>Users</h2>
+                <p>Loading...</p>
+              </div>
+            );
+          }
+        language: javascript
+        readonly: false
+    task: "Fetch users from https://jsonplaceholder.typicode.com/users using useEffect. Store them in state. Show a loading state while fetching, an error message if the request fails, and render the list of user names when successful."
+    validations:
+      - label: "useEffect fetch with loading and error states"
+        check: file-changed
+        pattern: "useEffect|fetch|loading|error"
+    hints:
+      - "useEffect(() => { fetch(url).then(...) }, []) — empty deps = run once on mount."
+      - "Use state for users, loading, and error. Set loading true before fetch, false after."
+      - "fetch().then(res => res.json()).then(data => setUsers(data)).catch(err => setError(err.message))."
+    agent_prompts:
+      on_start: "The data comes from a server. When does that request need to run? What should the UI show before the data arrives?"

package/modules/react-native-fundamentals/content.md

@@ -0,0 +1,141 @@
+# React Native — Cross-Platform Mobile from a Web Mindset
+
+<!-- hint:slides topic="React Native architecture: bridge vs new architecture, core components vs web, platform differences, and navigation" slides="5" -->
+
+## What is React Native?
+
+React Native lets you build native mobile apps (iOS and Android) using JavaScript and React. You write components; RN renders them as native views (not web views).
+
+## Core Components
+
+React Native uses different primitives than the web:
+
+| Component | Purpose | Web Analogy |
+|-----------|---------|-------------|
+| `View` | Container, layout | `<div>` |
+| `Text` | Display text | `<p>`, `<span>` |
+| `ScrollView` | Scrollable container | Overflow scroll |
+| `FlatList` | Virtualized list | Virtual list |
+| `Image` | Images | `<img>` |
+| `TextInput` | User input | `<input>` |
+| `TouchableOpacity` | Pressable area | `<button>` |
+
+**Rule:** All text must be inside `<Text>`. You cannot put text directly in `<View>`.
+
+```jsx
+<View>
+  <Text>Hello, world!</Text>
+</View>
+```
+
+## StyleSheet
+
+Use `StyleSheet.create()` for styles. Properties are camelCase; no CSS classes:
+
+```jsx
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 16,
+    backgroundColor: '#fff',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+  },
+});
+```
+
+Flexbox is the default layout. Use `flex: 1` to fill space. `flexDirection` defaults to `column` (not `row`).
+
+## FlatList
+
+For long lists, use `FlatList` (virtualized) instead of mapping over an array:
+
+```jsx
+<FlatList
+  data={items}
+  keyExtractor={(item) => item.id}
+  renderItem={({ item }) => <ItemRow item={item} />}
+/>
+```
+
+`FlatList` only renders visible items + buffer — essential for performance.
+
+## Navigation (React Navigation)
+
+React Navigation is the standard for screen navigation:
+
+```jsx
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+
+const Stack = createNativeStackNavigator();
+
+function App() {
+  return (
+    <NavigationContainer>
+      <Stack.Navigator>
+        <Stack.Screen name="Home" component={HomeScreen} />
+        <Stack.Screen name="Details" component={DetailsScreen} />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+Navigate with `navigation.navigate('Details', { id: 1 })`. Access params via `route.params`.
+
+## Platform Differences
+
+Use `Platform.OS` or `Platform.select()`:
+
+```jsx
+import { Platform } from 'react-native';
+
+const padding = Platform.select({ ios: 20, android: 16 });
+// Or: Platform.OS === 'ios' ? 20 : 16
+```
+
+Some components behave differently (e.g., `TextInput`, shadows). Test on both platforms.
+
+## Expo vs Bare
+
+| | Expo | Bare (React Native CLI) |
+|---|-----|------------------------|
+| Setup | Fast, no Xcode/Android Studio needed to start | Full native setup |
+| Native modules | Limited to Expo SDK + config plugins | Full access |
+| Build | EAS Build (cloud) or local | Xcode, Android Studio |
+| Use case | Prototypes, most apps | Heavy native customization |
+
+## Architecture: How It Works
+
+React Native bridges JavaScript and native code:
+
+```mermaid
+flowchart LR
+    subgraph JS
+        A[JS Thread]
+    end
+    subgraph Bridge
+        B[Bridge]
+    end
+    subgraph Native
+        C[Native Thread]
+    end
+    A <-->|Serialized messages| B
+    B <-->|Native calls| C
+```
+
+- **JS Thread:** Runs your React code, handles logic
+- **Bridge:** Serializes commands (e.g., "create View", "set style")
+- **Native Thread:** Renders actual UI, handles touch events
+
+The bridge can be a bottleneck. New Architecture (Fabric, TurboModules) reduces this.
+
+## Common Gotchas
+
+- **No div/span:** Use `View` and `Text` only
+- **No className:** Use `style` prop with StyleSheet
+- **Pixel density:** Use `Dimensions.get('window')` or layout APIs for responsive sizing
+- **Keyboard:** Use `KeyboardAvoidingView` for forms

package/modules/react-native-fundamentals/exercises.md

@@ -0,0 +1,79 @@
+# React Native Exercises
+
+## Exercise 1: Profile Card
+
+**Task:** Create a `ProfileCard` component with a circular avatar placeholder (View with borderRadius), name, and a short bio. Use StyleSheet and Flexbox for layout.
+
+**Validation:**
+- [ ] Card has consistent padding and spacing
+- [ ] Avatar is circular (width/height equal, borderRadius half of that)
+- [ ] Layout works in portrait orientation
+
+**Hints:**
+1. `borderRadius: 50` with equal width/height makes a circle
+2. Use `alignItems: 'center'` for centered content
+3. `Image` with a URI or a colored View for avatar placeholder
+
+---
+
+## Exercise 2: Form with TextInput
+
+**Task:** Create a simple form: name and email inputs, plus a submit button. Use controlled components (state drives input values). Log the values on submit.
+
+**Validation:**
+- [ ] Inputs are controlled (value + onChange)
+- [ ] Submit logs the current values
+- [ ] Keyboard doesn't obscure inputs (use KeyboardAvoidingView)
+
+**Hints:**
+1. `TextInput` uses `value` and `onChangeText`
+2. `KeyboardAvoidingView` with `behavior="padding"` (iOS) or `"height"` (Android)
+3. Wrap in `ScrollView` if content is tall
+
+---
+
+## Exercise 3: Searchable List
+
+**Task:** Create a FlatList of 20+ items. Add a TextInput above it for search. Filter the list as the user types (case-insensitive). Use `useMemo` or a derived array for the filtered data.
+
+**Validation:**
+- [ ] Typing filters the list in real time
+- [ ] FlatList only receives filtered data
+- [ ] No lag when list is large
+
+**Hints:**
+1. Store search term in state, derive filtered list
+2. `items.filter(i => i.name.toLowerCase().includes(search.toLowerCase()))`
+3. Consider `useMemo` if filtering is expensive
+
+---
+
+## Exercise 4: Tab Navigator
+
+**Task:** Add a bottom tab navigator with 3 tabs (e.g., Home, Search, Profile). Each tab shows a simple screen with different content. Use `createBottomTabNavigator`.
+
+**Validation:**
+- [ ] Tabs switch correctly
+- [ ] Each tab has distinct content
+- [ ] Tab bar is visible and usable
+
+**Hints:**
+1. `@react-navigation/bottom-tabs` for tab navigator
+2. Nest inside your existing NavigationContainer
+3. Optionally add icons with a vector icon library
+
+---
+
+## Exercise 5: Pull-to-Refresh
+
+**Task:** Add pull-to-refresh to a FlatList. When pulled, show a loading indicator and "refresh" the list (e.g., shuffle or refetch simulated data). Use `refreshControl` with `RefreshControl`.
+
+**Validation:**
+- [ ] Pulling triggers refresh
+- [ ] Loading state is visible during refresh
+- [ ] List updates after refresh completes
+
+**Hints:**
+1. `RefreshControl` from `react-native` with `refreshing` and `onRefresh`
+2. Use `useState` for `refreshing`; set true on pull, false when done
+3. Simulate async with `setTimeout`

package/modules/react-native-fundamentals/module.yaml

@@ -0,0 +1,42 @@
+slug: react-native-fundamentals
+title: "React Native — Cross-Platform Mobile from a Web Mindset"
+version: 1.0.0
+description: "Build iOS and Android apps with React — components, navigation, and platform differences."
+category: frameworks
+tags: [react-native, mobile, ios, android, cross-platform, typescript]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 20
+  guided: 60
+
+prerequisites: [react-fundamentals]
+related: [typescript-fundamentals]
+
+triggers:
+  - "How do I build a mobile app with React Native?"
+  - "What's the difference between React and React Native?"
+  - "How do I navigate between screens in React Native?"
+  - "How does React Native work under the hood?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-architecture]
+  quiz-types: [quiz-drag-order, quiz-timed-choice]
+  playground: javascript
+  slides: true
+
+sources:
+  - url: "https://reactnative.dev"
+    label: "React Native Docs"
+    type: docs
+  - url: "https://docs.expo.dev"
+    label: "Expo Docs"
+    type: docs

package/modules/react-native-fundamentals/quick-ref.md

@@ -0,0 +1,60 @@
+# React Native Quick Reference
+
+## Core Components
+
+| Component | Use For |
+|-----------|---------|
+| `View` | Containers, layout |
+| `Text` | All text content |
+| `ScrollView` | Scrollable content (finite) |
+| `FlatList` | Long lists (virtualized) |
+| `Image` | Images (source: `{uri}` or `require()`) |
+| `TextInput` | User input |
+| `TouchableOpacity` | Pressable with opacity feedback |
+
+## StyleSheet
+
+```jsx
+const styles = StyleSheet.create({
+  box: { flex: 1, padding: 16 },
+});
+<View style={styles.box} />
+```
+
+- Flexbox default: `flexDirection: 'column'`
+- `flex: 1` fills available space
+- No units for numbers (density-independent pixels)
+
+## Navigation
+
+| Method | Purpose |
+|--------|---------|
+| `navigation.navigate('Screen', { id: 1 })` | Go to screen with params |
+| `navigation.goBack()` | Go back |
+| `route.params` | Access params in destination |
+
+## Platform
+
+```jsx
+import { Platform } from 'react-native';
+Platform.OS // 'ios' | 'android'
+Platform.select({ ios: 20, android: 16 })
+```
+
+## FlatList Props
+
+| Prop | Purpose |
+|------|---------|
+| `data` | Array of items |
+| `keyExtractor` | (item) => item.id |
+| `renderItem` | ({ item }) => <Row item={item} /> |
+| `ListHeaderComponent` | Header content |
+| `refreshControl` | Pull-to-refresh |
+
+## Decision: ScrollView vs FlatList
+
+| Use ScrollView when | Use FlatList when |
+|---------------------|-------------------|
+| Few items (< 20) | Many items (20+) |
+| Content is mixed (not just list) | Homogeneous list |
+| Need nested scroll (careful) | Standard list UI |

package/modules/react-native-fundamentals/quiz.md

@@ -0,0 +1,61 @@
+# React Native Quiz
+
+## Question 1
+
+Can you put a string directly inside a `View` component?
+
+A) Yes, it renders as text
+B) No, all text must be inside a `Text` component
+C) Yes on iOS, no on Android
+D) Only if you use a special prop
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: React Native requires all text to be wrapped in a Text component. Putting a string directly in a View will throw an error. This is different from the web where text can be direct children of divs. -->
+
+## Question 2
+
+What is the main performance advantage of FlatList over ScrollView with a mapped array?
+
+A) FlatList uses less memory
+B) FlatList only renders visible items (virtualization)
+C) FlatList has built-in caching
+D) ScrollView is slower on Android only
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: FlatList virtualizes the list — it only mounts components for items near the viewport, plus a small buffer. ScrollView with map() renders every item at once, which can cause performance issues with hundreds of items. -->
+
+## Question 3
+
+How do you pass data when navigating to another screen with React Navigation?
+
+A) Through global state only
+B) As the second argument to navigate: `navigate('Screen', { id: 1 })`
+C) Through a shared context
+D) By mutating the navigator's state
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: navigation.navigate('ScreenName', { param1: value1 }) passes params to the destination screen. The destination receives them via route.params. -->
+
+## Question 4
+
+What does the React Native Bridge do?
+
+A) Connects to a remote server
+B) Serializes messages between the JS thread and native thread
+C) Manages React state
+D) Handles touch events only
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The Bridge is the communication layer between the JavaScript thread (where your React code runs) and the native thread (where UI is rendered). Commands are serialized and sent across it. -->
+
+## Question 5
+
+When would you choose Expo over a bare React Native project?
+
+A) When you need maximum native customization
+B) When you want fast setup and don't need custom native code
+C) Only for iOS
+D) Expo is deprecated
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Expo offers fast setup, over-the-air updates, and a managed workflow. Choose it when you don't need custom native modules. Use bare RN when you need full native control. -->

package/modules/react-native-fundamentals/resources.md

@@ -0,0 +1,24 @@
+# React Native — Resources
+
+## Videos
+
+- [React Native in 100 Seconds](https://www.youtube.com/watch?v=gvkqT_Uoahw) — Fireship. Quick overview.
+- [React Native Tutorial](https://www.youtube.com/watch?v=obH0Ze_Rosc) — freeCodeCamp. Full beginner course.
+- [Expo Crash Course](https://www.youtube.com/watch?v=5QlE6o-iYcE) — Traversy Media. Getting started with Expo.
+
+## Articles and Readings
+
+- [React Native Docs](https://reactnative.dev/docs/getting-started) — Official docs. Start here.
+- [React Navigation Docs](https://reactnavigation.org/docs/getting-started) — Navigation patterns and setup.
+- [Expo Documentation](https://docs.expo.dev) — Expo-specific guides and APIs.
+
+## Books
+
+- **React Native in Action** by Nader Dabit — Comprehensive RN coverage with practical projects.
+- **Fullstack React Native** by Devin Abbott et al. — From basics to advanced patterns.
+
+## Tools and Playgrounds
+
+- [Expo Snack](https://snack.expo.dev) — Run RN in the browser, no local setup.
+- [React Native Directory](https://reactnative.directory) — Find and evaluate libraries.
+- [Flipper](https://fbflipper.com) — Debug RN apps (network, layout, logs).