novahiz 0.1.0

package/bundled-skills/expo-router/references/form-sheet.md

@@ -0,0 +1,253 @@
+# Form Sheets in Expo Router
+
+This skill covers implementing form sheets with footers using Expo Router's Stack navigator and react-native-screens.
+
+## Overview
+
+Form sheets are modal presentations that appear as a card sliding up from the bottom of the screen. They're ideal for:
+
+- Quick actions and confirmations
+- Settings panels
+- Login/signup flows
+- Action sheets with custom content
+
+**Requirements:**
+
+- Expo Router Stack navigator
+
+## Basic Usage
+
+### Form Sheet with Footer
+
+Configure the Stack.Screen with transparent backgrounds and sheet presentation:
+
+```tsx
+// app/_layout.tsx
+import { Stack } from "expo-router";
+
+export default function Layout() {
+  return (
+    <Stack>
+      <Stack.Screen name="index" />
+      <Stack.Screen
+        name="about"
+        options={{
+          presentation: "formSheet",
+          sheetAllowedDetents: [0.25],
+          headerTransparent: true,
+          contentStyle: { backgroundColor: "transparent" },
+          sheetGrabberVisible: true,
+        }}
+      >
+        <Stack.Header style={{ backgroundColor: "transparent" }}></Stack.Header>
+      </Stack.Screen>
+    </Stack>
+  );
+}
+```
+
+### Form Sheet Screen Content
+
+> Requires Expo SDK 55 or later.
+
+Use `flex: 1` to allow the content to fill available space, enabling footer positioning:
+
+```tsx
+// app/about.tsx
+import { View, Text, StyleSheet } from "react-native";
+
+export default function AboutSheet() {
+  return (
+    <View style={styles.container}>
+      {/* Main content */}
+      <View style={styles.content}>
+        <Text>Sheet Content</Text>
+      </View>
+
+      {/* Footer - stays at bottom */}
+      <View style={styles.footer}>
+        <Text>Footer Content</Text>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+    padding: 16,
+  },
+  footer: {
+    padding: 16,
+  },
+});
+```
+
+### Formsheet with interactive content below
+
+Use `sheetLargestUndimmedDetentIndex` (zero-indexed) to keep content behind the form sheet interactive — e.g. letting users pan a map beneath it. Setting it to `1` allows interaction at the first two detents but dims on the third.
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+
+export default function Layout() {
+  return (
+    <Stack screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="index" />
+      <Stack.Screen
+        name="info-sheet"
+        options={{
+          presentation: "formSheet",
+          sheetAllowedDetents: [0.2, 0.5, 1.0],
+          sheetLargestUndimmedDetentIndex: 1,
+          /* other options */
+        }}
+      />
+    </Stack>
+  )
+}
+```
+
+## Key Options
+
+| Option                | Type       | Description                                                 |
+| --------------------- | ---------- | ----------------------------------------------------------- |
+| `presentation`        | `string`   | Set to `'formSheet'` for sheet presentation                 |
+| `sheetGrabberVisible` | `boolean`  | Shows the drag handle at the top of the sheet               |
+| `sheetAllowedDetents` | `number[]` | Array of detent heights (0-1 range, e.g., `[0.25]` for 25%) |
+| `headerTransparent`   | `boolean`  | Makes header background transparent                         |
+| `contentStyle`        | `object`   | Style object for the screen content container               |
+| `title`               | `string`   | Screen title (set to `''` for no title)                     |
+
+## Common Detent Values
+
+- `[0.25]` - Quarter sheet (compact actions)
+- `[0.5]` - Half sheet (medium content)
+- `[0.75]` - Three-quarter sheet (detailed forms)
+- `[0.25, 0.5, 1]` - Multiple stops (expandable sheet)
+
+## Complete Example
+
+```tsx
+// _layout.tsx
+import { Stack } from "expo-router";
+
+export default function Layout() {
+  return (
+    <Stack>
+      <Stack.Screen name="index" options={{ title: "Home" }} />
+      <Stack.Screen
+        name="confirm"
+        options={{
+          contentStyle: { backgroundColor: "transparent" },
+          presentation: "formSheet",
+          title: "",
+          sheetGrabberVisible: true,
+          sheetAllowedDetents: [0.25],
+          headerTransparent: true,
+        }}
+      >
+        <Stack.Header style={{ backgroundColor: "transparent" }}>
+          <Stack.Header.Right />
+        </Stack.Header>
+      </Stack.Screen>
+    </Stack>
+  );
+}
+```
+
+```tsx
+// app/confirm.tsx
+import { View, Text, Pressable, StyleSheet } from "react-native";
+import { router } from "expo-router";
+
+export default function ConfirmSheet() {
+  return (
+    <View style={styles.container}>
+      <View style={styles.content}>
+        <Text style={styles.title}>Confirm Action</Text>
+        <Text style={styles.description}>
+          Are you sure you want to proceed?
+        </Text>
+      </View>
+
+      <View style={styles.footer}>
+        <Pressable style={styles.cancelButton} onPress={() => router.back()}>
+          <Text style={styles.cancelText}>Cancel</Text>
+        </Pressable>
+        <Pressable style={styles.confirmButton} onPress={() => router.back()}>
+          <Text style={styles.confirmText}>Confirm</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+    padding: 20,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: "600",
+    marginBottom: 8,
+  },
+  description: {
+    fontSize: 14,
+    color: "#666",
+    textAlign: "center",
+  },
+  footer: {
+    flexDirection: "row",
+    padding: 16,
+    gap: 12,
+  },
+  cancelButton: {
+    flex: 1,
+    padding: 14,
+    borderRadius: 10,
+    backgroundColor: "#f0f0f0",
+    alignItems: "center",
+  },
+  cancelText: {
+    fontSize: 16,
+    fontWeight: "500",
+  },
+  confirmButton: {
+    flex: 1,
+    padding: 14,
+    borderRadius: 10,
+    backgroundColor: "#007AFF",
+    alignItems: "center",
+  },
+  confirmText: {
+    fontSize: 16,
+    fontWeight: "500",
+    color: "white",
+  },
+});
+```
+
+## Troubleshooting
+
+### Content not filling sheet
+
+Make sure the root View uses `flex: 1`:
+
+```tsx
+<View style={{ flex: 1 }}>{/* content */}</View>
+```
+
+### Sheet background showing through
+
+Set `contentStyle: { backgroundColor: 'transparent' }` in options and style your content container with the desired background color instead.

package/bundled-skills/expo-router/references/route-structure.md

@@ -0,0 +1,229 @@
+# Route Structure
+
+## File Conventions
+
+- Routes belong in the `app` directory
+- Use `[]` for dynamic routes, e.g. `[id].tsx`
+- Routes can never be named `(foo).tsx` - use `(foo)/index.tsx` instead
+- Use `(group)` routes to simplify the public URL structure
+- NEVER co-locate components, types, or utilities in the app directory - these should be in separate directories like `components/`, `utils/`, etc.
+- The app directory should only contain route and `_layout` files; every file should export a default component
+- Ensure the app always has a route that matches "/" so the app is never blank
+- ALWAYS use `_layout.tsx` files to define stacks
+
+## Dynamic Routes
+
+Use square brackets for dynamic segments:
+
+```
+app/
+  users/
+    [id].tsx        # Matches /users/123, /users/abc
+    [id]/
+      posts.tsx     # Matches /users/123/posts
+```
+
+### Catch-All Routes
+
+Use `[...slug]` for catch-all routes:
+
+```
+app/
+  docs/
+    [...slug].tsx   # Matches /docs/a, /docs/a/b, /docs/a/b/c
+```
+
+## Query Parameters
+
+Access query parameters with the `useLocalSearchParams` hook:
+
+```tsx
+import { useLocalSearchParams } from "expo-router";
+
+function Page() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+}
+```
+
+For dynamic routes, the parameter name matches the file name:
+
+- `[id].tsx` → `useLocalSearchParams<{ id: string }>()`
+- `[slug].tsx` → `useLocalSearchParams<{ slug: string }>()`
+
+## Pathname
+
+Access the current pathname with the `usePathname` hook:
+
+```tsx
+import { usePathname } from "expo-router";
+
+function Component() {
+  const pathname = usePathname(); // e.g. "/users/123"
+}
+```
+
+## Group Routes
+
+Use parentheses for groups that don't affect the URL:
+
+```
+app/
+  (auth)/
+    login.tsx       # URL: /login
+    register.tsx    # URL: /register
+  (main)/
+    index.tsx       # URL: /
+    settings.tsx    # URL: /settings
+```
+
+Groups are useful for:
+
+- Organizing related routes
+- Applying different layouts to route groups
+- Keeping URLs clean
+
+## Stacks and Tabs Structure
+
+When an app has tabs, the header and title should be set in a Stack that is nested INSIDE each tab. This allows tabs to have their own headers and distinct histories. The root layout should often not have a header.
+
+- Set the 'headerShown' option to false on the tab layout
+- Use (group) routes to simplify the public URL structure
+- You may need to delete or refactor existing routes to fit this structure
+
+Example structure:
+
+```
+app/
+  _layout.tsx — <Tabs />
+  (home)/
+    _layout.tsx — <Stack />
+    index.tsx — <ScrollView />
+  (settings)/
+    _layout.tsx — <Stack />
+    index.tsx — <ScrollView />
+  (home,settings)/
+    info.tsx — <ScrollView /> (shared across tabs)
+```
+
+## Array Routes for Multiple Stacks
+
+Use array routes '(index,settings)' to create multiple stacks. This is useful for tabs that need to share screens across stacks.
+
+```
+app/
+  _layout.tsx — <Tabs />
+  (index,settings)/
+    _layout.tsx — <Stack />
+    index.tsx — <ScrollView />
+    settings.tsx — <ScrollView />
+```
+
+This requires a specialized layout with explicit anchor routes:
+
+```tsx
+// app/(index,settings)/_layout.tsx
+import { useMemo } from "react";
+import Stack from "expo-router/stack";
+
+export const unstable_settings = {
+  index: { anchor: "index" },
+  settings: { anchor: "settings" },
+};
+
+export default function Layout({ segment }: { segment: string }) {
+  const screen = segment.match(/\((.*)\)/)?.[1]!;
+
+  const options = useMemo(() => {
+    switch (screen) {
+      case "index":
+        return { headerRight: () => <></> };
+      default:
+        return {};
+    }
+  }, [screen]);
+
+  return (
+    <Stack>
+      <Stack.Screen name={screen} options={options} />
+    </Stack>
+  );
+}
+```
+
+## Complete App Structure Example
+
+```
+app/
+  _layout.tsx — <NativeTabs />
+  (index,search)/
+    _layout.tsx — <Stack />
+    index.tsx — Main list
+    search.tsx — Search view
+    i/[id].tsx — Detail page
+components/
+  theme.tsx
+  list.tsx
+utils/
+  storage.ts
+  use-search.ts
+```
+
+## Layout Files
+
+Every directory can have a `_layout.tsx` file that wraps all routes in that directory:
+
+```tsx
+// app/_layout.tsx
+import { Stack } from "expo-router/stack";
+
+export default function RootLayout() {
+  return <Stack />;
+}
+```
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name="index">
+        <Label>Home</Label>
+        <Icon sf="house.fill" />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}
+```
+
+## Route Settings
+
+Export `unstable_settings` to configure route behavior:
+
+```tsx
+export const unstable_settings = {
+  anchor: "index",
+};
+```
+
+- `initialRouteName` was renamed to `anchor` in v4
+
+## Not Found Routes
+
+Create a `+not-found.tsx` file to handle unmatched routes:
+
+```tsx
+// app/+not-found.tsx
+import { Link } from "expo-router";
+import { View, Text } from "react-native";
+
+export default function NotFound() {
+  return (
+    <View>
+      <Text>Page not found</Text>
+      <Link href="/">Go home</Link>
+    </View>
+  );
+}
+```

package/bundled-skills/expo-router/references/search.md

@@ -0,0 +1,248 @@
+# Search
+
+## Header Search Bar
+
+Add a search bar to the stack header with `headerSearchBarOptions`:
+
+```tsx
+<Stack.Screen
+  name="index"
+  options={{
+    headerSearchBarOptions: {
+      placeholder: "Search",
+      onChangeText: (event) => console.log(event.nativeEvent.text),
+    },
+  }}
+/>
+```
+
+### Options
+
+```tsx
+headerSearchBarOptions: {
+  // Placeholder text
+  placeholder: "Search items...",
+
+  // Auto-capitalize behavior
+  autoCapitalize: "none",
+
+  // Input type
+  inputType: "text", // "text" | "phone" | "number" | "email"
+
+  // Cancel button text (iOS)
+  cancelButtonText: "Cancel",
+
+  // Hide when scrolling (iOS)
+  hideWhenScrolling: true,
+
+  // Hide navigation bar during search (iOS)
+  hideNavigationBar: true,
+
+  // Obscure background during search (iOS)
+  obscureBackground: true,
+
+  // Placement
+  placement: "automatic", // "automatic" | "inline" | "stacked"
+
+  // Callbacks
+  onChangeText: (event) => {},
+  onSearchButtonPress: (event) => {},
+  onCancelButtonPress: (event) => {},
+  onFocus: () => {},
+  onBlur: () => {},
+}
+```
+
+## useSearch Hook
+
+Reusable hook for search state management:
+
+```tsx
+import { useEffect, useState } from "react";
+import { useNavigation } from "expo-router";
+
+export function useSearch(options: any = {}) {
+  const [search, setSearch] = useState("");
+  const navigation = useNavigation();
+
+  useEffect(() => {
+    navigation.setOptions({
+      headerShown: true,
+      headerSearchBarOptions: {
+        ...options,
+        onChangeText(e: any) {
+          setSearch(e.nativeEvent.text);
+          options.onChangeText?.(e);
+        },
+        onSearchButtonPress(e: any) {
+          setSearch(e.nativeEvent.text);
+          options.onSearchButtonPress?.(e);
+        },
+        onCancelButtonPress(e: any) {
+          setSearch("");
+          options.onCancelButtonPress?.(e);
+        },
+      },
+    });
+  }, [options, navigation]);
+
+  return search;
+}
+```
+
+### Usage
+
+```tsx
+function SearchScreen() {
+  const search = useSearch({ placeholder: "Search items..." });
+
+  const filteredItems = items.filter(item =>
+    item.name.toLowerCase().includes(search.toLowerCase())
+  );
+
+  return (
+    <FlatList
+      data={filteredItems}
+      renderItem={({ item }) => <ItemRow item={item} />}
+    />
+  );
+}
+```
+
+## Filtering Patterns
+
+### Simple Text Filter
+
+```tsx
+const filtered = items.filter(item =>
+  item.name.toLowerCase().includes(search.toLowerCase())
+);
+```
+
+### Multiple Fields
+
+```tsx
+const filtered = items.filter(item => {
+  const query = search.toLowerCase();
+  return (
+    item.name.toLowerCase().includes(query) ||
+    item.description.toLowerCase().includes(query) ||
+    item.tags.some(tag => tag.toLowerCase().includes(query))
+  );
+});
+```
+
+### Debounced Search
+
+For expensive filtering or API calls:
+
+```tsx
+import { useState, useEffect, useMemo } from "react";
+
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}
+
+function SearchScreen() {
+  const search = useSearch();
+  const debouncedSearch = useDebounce(search, 300);
+
+  const filteredItems = useMemo(() =>
+    items.filter(item =>
+      item.name.toLowerCase().includes(debouncedSearch.toLowerCase())
+    ),
+    [debouncedSearch]
+  );
+
+  return <FlatList data={filteredItems} />;
+}
+```
+
+## Search with Native Tabs
+
+When using NativeTabs with a search role, the search bar integrates with the tab bar:
+
+```tsx
+// app/_layout.tsx
+<NativeTabs>
+  <NativeTabs.Trigger name="(home)">
+    <Label>Home</Label>
+    <Icon sf="house.fill" />
+  </NativeTabs.Trigger>
+  <NativeTabs.Trigger name="(search)" role="search">
+    <Label>Search</Label>
+  </NativeTabs.Trigger>
+</NativeTabs>
+```
+
+```tsx
+// app/(search)/_layout.tsx
+<Stack>
+  <Stack.Screen
+    name="index"
+    options={{
+      headerSearchBarOptions: {
+        placeholder: "Search...",
+        onChangeText: (e) => setSearch(e.nativeEvent.text),
+      },
+    }}
+  />
+</Stack>
+```
+
+## Empty States
+
+Show appropriate UI when search returns no results:
+
+```tsx
+function SearchResults({ search, items }) {
+  const filtered = items.filter(/* ... */);
+
+  if (search && filtered.length === 0) {
+    return (
+      <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+        <Text style={{ color: colors.secondaryLabel }}>
+          No results for "{search}"
+        </Text>
+      </View>
+    );
+  }
+
+  return <FlatList data={filtered} />;
+}
+```
+
+## Search Suggestions
+
+Show recent searches or suggestions:
+
+```tsx
+function SearchScreen() {
+  const search = useSearch();
+  const [recentSearches, setRecentSearches] = useState<string[]>([]);
+
+  if (!search && recentSearches.length > 0) {
+    return (
+      <View>
+        <Text style={{ color: colors.secondaryLabel }}>
+          Recent Searches
+        </Text>
+        {recentSearches.map((term) => (
+          <Pressable key={term} onPress={() => /* apply search */}>
+            <Text>{term}</Text>
+          </Pressable>
+        ))}
+      </View>
+    );
+  }
+
+  return <SearchResults search={search} />;
+}
+```