@rubix0270/arboris 1.0.2 → 1.0.4

package/prisma/skills/react-native-patterns/SKILL.md

@@ -1,326 +0,0 @@
----
-name: react-native-patterns
-description: React Native and Expo app patterns — Expo Router navigation, state separation (server/client/route/form), TanStack Query data fetching with Zod, performant lists, NativeWind/StyleSheet styling, native APIs, and secure storage. Use when building or editing React Native / Expo screens, components, navigation, or data layers.
-origin: ECC
----
-
-# React Native / Expo Patterns
-
-Practical patterns for building production React Native apps with Expo. Covers navigation, state, data fetching, lists, styling, and native APIs. Pairs with the `rules/react-native/` ruleset: rules say *what* to enforce, this skill shows *how*.
-
-Libraries named below (NativeWind, Zustand/Jotai, TanStack Query) are common, well-established options shown for illustration — the patterns matter more than the specific package, and any equivalent works. Zod is used for validation to stay consistent with ECC's existing `typescript/` rules.
-
-These patterns assume the managed Expo workflow (Expo Router, EAS, `expo-*` modules) on the New Architecture (the default in recent Expo SDKs, mandatory from SDK 55+). They do NOT assume the browser DOM — React Native has no `<div>`, no URL bar, and no web data-fetching defaults.
-
-## When to Activate
-
-Use this skill when:
-
-- Building or editing React Native / Expo screens, components, or navigation
-- Setting up routing with Expo Router (file-based `app/` directory)
-- Deciding where state belongs (server cache vs client store vs route params vs form)
-- Wiring data fetching with TanStack Query and validating responses with Zod
-- Rendering long or heavy lists
-- Choosing or applying a styling approach (NativeWind or StyleSheet)
-- Accessing native device APIs (camera, location, notifications) or secure storage
-- Reviewing RN code for mobile-specific issues
-
-Do NOT use the web/React-DOM patterns here — URL-as-state, `<div>`, and SWR-for-browser do not apply to React Native.
-
-## Core Concepts
-
-### Project structure (Expo Router)
-
-File-based routing under `app/`. Keep route files thin: they read and validate params, then delegate to a screen component that lives in `components/` or `features/`.
-
-```
-app/
-  _layout.tsx          # root stack
-  (tabs)/
-    _layout.tsx        # tab navigator
-    index.tsx          # Home
-  user/[id].tsx        # dynamic route
-components/
-features/
-  user/UserProfile.tsx
-```
-
-### Navigation: validate route params
-
-Deep links and dynamic routes deliver untrusted strings. Validate them with Zod before use.
-
-```tsx
-// app/user/[id].tsx
-import { useLocalSearchParams, router } from 'expo-router'
-import { z } from 'zod'
-import { UserProfile } from '@/features/user/UserProfile'
-
-const Params = z.object({ id: z.string().uuid() })
-
-export default function UserRoute() {
-  const parsed = Params.safeParse(useLocalSearchParams())
-  if (!parsed.success) {
-    router.replace('/not-found')
-    return null
-  }
-  return <UserProfile userId={parsed.data.id} />
-}
-```
-
-### State: keep concerns separate
-
-Do not duplicate server data into a client store. Each concern has its own home.
-
-| Concern | Common choices |
-|---------|------|
-| Server state (remote data) | a server-cache library (TanStack Query, SWR) |
-| Client/UI state | a lightweight store (Zustand, Jotai) or Context |
-| Route/navigation state | Expo Router params |
-| Form state | a form library (e.g. React Hook Form) + schema validation |
-| Secrets / tokens | `expo-secure-store` |
-| Non-secret persistence | `AsyncStorage` / MMKV |
-
-Prefer local `useState` until state genuinely needs sharing.
-
-### Data fetching: a cache library + Zod
-
-Use a server-cache library (TanStack Query, SWR) instead of fetch-in-`useEffect`. Validate at the boundary and infer types from the schema. Handle loading, error, and empty states explicitly. (Example uses TanStack Query.)
-
-```tsx
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { z } from 'zod'
-
-const User = z.object({ id: z.string(), email: z.string().email() })
-type User = z.infer<typeof User>
-
-export function useUser(id: string) {
-  return useQuery({
-    queryKey: ['user', id],
-    queryFn: async (): Promise<User> => User.parse(await api.getUser(id)),
-  })
-}
-
-export function useUpdateEmail(id: string) {
-  const qc = useQueryClient()
-  return useMutation({
-    mutationFn: (email: string) => api.updateEmail(id, email),
-    onSuccess: () => qc.invalidateQueries({ queryKey: ['user', id] }),
-  })
-}
-```
-
-### Lists: virtualize, never map a big array in a ScrollView
-
-```tsx
-import { FlatList } from 'react-native'
-
-<FlatList
-  data={items}
-  keyExtractor={(item) => item.id}
-  renderItem={renderItem}          // memoized
-  initialNumToRender={10}
-  windowSize={5}
-/>
-```
-
-Use `FlashList` (Shopify) for large or heterogeneous lists.
-
-### Styling: pick one system
-
-`StyleSheet.create()` is the framework-native option; utility-class libraries (e.g. NativeWind) are a common alternative. Choose one and stay consistent. Never build style objects inline in JSX on hot paths.
-
-```tsx
-// NativeWind
-<View className="p-4 rounded-2xl bg-white">
-  <Text className="text-base font-semibold">Hello</Text>
-</View>
-
-// StyleSheet
-const styles = StyleSheet.create({ card: { padding: 16, borderRadius: 16, backgroundColor: '#fff' } })
-<View style={styles.card}>...</View>
-```
-
-### Native APIs: wrap in hooks, clean up effects
-
-Keep Expo SDK calls and subscriptions inside `use*` hooks, not in JSX. Always clean up.
-
-```tsx
-import { useEffect, useState } from 'react'
-import * as Location from 'expo-location'
-
-type LocationState =
-  | { status: 'loading' }
-  | { status: 'denied' }
-  | { status: 'granted'; coords: Location.LocationObjectCoords }
-
-export function useCurrentLocation() {
-  // Track status, not just coords — so the UI can tell "still loading" apart
-  // from "permission denied" and show an actionable message.
-  const [state, setState] = useState<LocationState>({ status: 'loading' })
-
-  useEffect(() => {
-    let active = true
-    ;(async () => {
-      const { status } = await Location.requestForegroundPermissionsAsync()
-      if (status !== 'granted') {
-        if (active) setState({ status: 'denied' })
-        return
-      }
-      const pos = await Location.getCurrentPositionAsync({})
-      if (active) setState({ status: 'granted', coords: pos.coords })
-    })()
-    return () => { active = false }   // ignore stale result after unmount
-  }, [])
-
-  return state
-}
-```
-
-### Secure storage for tokens
-
-```tsx
-import * as SecureStore from 'expo-secure-store'
-
-await SecureStore.setItemAsync('auth_token', token)   // Keychain / Keystore
-const token = await SecureStore.getItemAsync('auth_token')
-```
-
-## Code Examples
-
-### A full screen: route → query → list → states
-
-```tsx
-// app/(tabs)/orders.tsx
-import { memo, useCallback } from 'react'
-import { FlatList, Text, View } from 'react-native'
-import { useQuery } from '@tanstack/react-query'
-import { z } from 'zod'
-
-const OrderSchema = z.object({ id: z.string(), total: z.number(), status: z.string() })
-const OrdersSchema = z.array(OrderSchema)
-type Order = z.infer<typeof OrderSchema>
-
-function useOrders() {
-  return useQuery({
-    queryKey: ['orders'],
-    queryFn: async () => OrdersSchema.parse(await api.listOrders()),
-  })
-}
-
-// Memoized so its reference is stable across renders (see the lists guidance).
-const OrderRow = memo(function OrderRow({ item }: { item: Order }) {
-  return (
-    <View className="px-4 py-3 border-b border-neutral-200">
-      <Text className="font-medium">#{item.id}</Text>
-      <Text className="text-neutral-500">{item.status} · ${item.total}</Text>
-    </View>
-  )
-})
-
-export default function OrdersScreen() {
-  const { data, isLoading, isError, refetch, isRefetching } = useOrders()
-  const renderItem = useCallback(({ item }: { item: Order }) => <OrderRow item={item} />, [])
-
-  if (isLoading) return <Centered><Text>Loading…</Text></Centered>
-  if (isError) return <Centered><Text accessibilityRole="alert">Could not load orders.</Text></Centered>
-  if (!data?.length) return <Centered><Text>No orders yet.</Text></Centered>
-
-  return (
-    <FlatList
-      data={data}
-      keyExtractor={(o) => o.id}
-      onRefresh={refetch}
-      refreshing={isRefetching}
-      renderItem={renderItem}
-    />
-  )
-}
-```
-
-### A form: React Hook Form + Zod resolver
-
-```tsx
-import { useForm, Controller } from 'react-hook-form'
-import { zodResolver } from '@hookform/resolvers/zod'
-import { z } from 'zod'
-import { TextInput, Button, Text } from 'react-native'
-
-const Schema = z.object({ email: z.string().email('Invalid email') })
-type FormValues = z.infer<typeof Schema>
-
-export function EmailForm({ onSubmit }: { onSubmit: (v: FormValues) => void }) {
-  const { control, handleSubmit, formState: { errors } } = useForm<FormValues>({
-    resolver: zodResolver(Schema),
-    defaultValues: { email: '' },
-  })
-
-  return (
-    <>
-      <Controller
-        control={control}
-        name="email"
-        render={({ field: { value, onChange, onBlur } }) => (
-          <TextInput
-            value={value}
-            onChangeText={onChange}
-            onBlur={onBlur}
-            autoCapitalize="none"
-            keyboardType="email-address"
-            accessibilityLabel="Email address"
-          />
-        )}
-      />
-      {errors.email && <Text accessibilityRole="alert">{errors.email.message}</Text>}
-      <Button title="Save" onPress={handleSubmit(onSubmit)} />
-    </>
-  )
-}
-```
-
-## Anti-Patterns
-
-```tsx
-// WRONG: large array mapped inside a ScrollView (no virtualization, janky, high memory)
-<ScrollView>{items.map((i) => <Row key={i.id} item={i} />)}</ScrollView>
-// RIGHT: FlatList / FlashList
-
-// WRONG: server data copied into a client store (two sources of truth, stale data)
-const useStore = create((set) => ({ users: [], setUsers: (u) => set({ users: u }) }))
-useEffect(() => { getUsers().then(setUsers) }, [])
-// RIGHT: useQuery owns server state; derive what you need
-
-// WRONG: tokens in AsyncStorage (not encrypted)
-await AsyncStorage.setItem('auth_token', token)
-// RIGHT: expo-secure-store
-
-// WRONG: trusting deep-link params
-const { id } = useLocalSearchParams(); fetchUser(id)
-// RIGHT: validate with Zod before use
-
-// WRONG: inline style object recreated every render on a hot path
-<View style={{ padding: 16, backgroundColor: '#fff' }} />
-// RIGHT: StyleSheet.create at module scope, or NativeWind className
-
-// WRONG: real secret shipped in the bundle
-const STRIPE_SECRET = 'sk_live_...'
-// RIGHT: keep privileged calls server-side; ship only public keys protected by backend rules
-```
-
-## Best Practices
-
-- Keep route files thin; put logic in screen components and `use*` hooks.
-- Validate every external input (API responses, route params, push payloads) with Zod.
-- Let TanStack Query own server state; keep client stores small.
-- Always render loading, error, and empty states — never just a spinner with no fallback.
-- Virtualize lists; memoize `renderItem`; provide a stable `keyExtractor`.
-- Use `react-native-reanimated` for animation (UI thread); avoid heavy work on the JS thread.
-- Store tokens in `expo-secure-store`; never trust the client for authorization.
-- Respect safe areas, Dynamic Type, and accessibility roles/labels from the start.
-- Confirm New Architecture compatibility for every native dependency before release.
-
-## Related Skills
-
-- `frontend-patterns` — React/Next.js (web) patterns; useful for shared React concepts, but DOM-specific.
-- `coding-standards` — TypeScript/JavaScript idioms that apply to RN code.
-- `tdd-workflow`, `e2e-testing` — testing process (use Jest + React Native Testing Library, Maestro/Detox for RN).
-- `security-review` — general security checklist that complements the RN bundle/secret guidance above.

package/prisma/skills/react-patterns/SKILL.md

@@ -1,342 +0,0 @@
----
-name: react-patterns
-description: React 18/19 patterns including hooks discipline, server/client component boundaries, Suspense + error boundaries, form actions, data fetching, state management decision trees, and accessibility-first composition. Use when writing or reviewing React components.
-metadata:
-  origin: ECC
----
-
-# React Patterns
-
-Idiomatic React 18/19 patterns for building robust, accessible, performant component trees.
-
-## When to Activate
-
-- Writing or modifying React function components, custom hooks, or component trees
-- Reviewing JSX/TSX files
-- Designing state shape or component composition
-- Migrating class components or older `forwardRef`/`useEffect`-heavy code
-- Choosing between local state, lifted state, context, and external stores
-- Working with Server Components / Client Components (Next.js App Router, RSC)
-- Implementing forms with React 19 actions or controlled inputs
-- Wiring data fetching with TanStack Query / SWR / RSC
-
-## Core Principles
-
-### 1. Render is a Pure Function of Props and State
-
-```tsx
-// Good: derive during render
-function Cart({ items }: { items: CartItem[] }) {
-  const total = items.reduce((sum, i) => sum + i.price * i.qty, 0);
-  return <span>{formatMoney(total)}</span>;
-}
-
-// Bad: derived state stored separately
-function Cart({ items }: { items: CartItem[] }) {
-  const [total, setTotal] = useState(0);
-  useEffect(() => {
-    setTotal(items.reduce((sum, i) => sum + i.price * i.qty, 0));
-  }, [items]);
-  return <span>{formatMoney(total)}</span>;
-}
-```
-
-Derived state in `useEffect` adds a render cycle, can desync, and obscures the data flow.
-
-### 2. Side Effects Outside Render
-
-Effects, mutations, network calls, and subscriptions live in event handlers or `useEffect` — never in the render body.
-
-### 3. Composition Over Inheritance
-
-React has no inheritance model for components. Compose with `children`, render props, or component props.
-
-## Hooks Discipline
-
-See [rules/react/hooks.md](../../rules/react/hooks.md) for the full ruleset. Highlights:
-
-- Top-level only, never conditional
-- Cleanup every subscription, interval, listener
-- Functional updater (`setX(prev => prev + 1)`) when new state depends on old
-- Default position: do not memoize — add `useMemo`/`useCallback` only when a profiler or a dependency chain proves it matters
-- Extract a custom hook only when the same hook sequence appears in 2+ components
-
-## State Location Decision Tree
-
-```
-Used by one component?
-  -> useState inside it
-
-Used by parent + a few descendants?
-  -> lift to nearest common ancestor
-
-Used across distant branches AND low-frequency reads (theme, auth, locale)?
-  -> React Context
-
-High-frequency updates shared across the tree?
-  -> external store (Zustand, Jotai, Redux Toolkit)
-
-Derived from a server?
-  -> server-state library (TanStack Query, SWR, RSC fetch)
-```
-
-Most pages do not need context or a global store. Resist abstraction until duplicated lifting becomes painful.
-
-## Server / Client Components (RSC)
-
-```tsx
-// Server Component - default, async, never ships JS for itself
-export default async function ProductPage({ params }: { params: { id: string } }) {
-  const product = await db.product.findUnique({ where: { id: params.id } });
-  if (!product) notFound();
-  return <ProductView product={product} />;
-}
-
-// Client Component - opt in with "use client"
-"use client";
-export function AddToCartButton({ productId }: { productId: string }) {
-  const [pending, startTransition] = useTransition();
-  return (
-    <button
-      disabled={pending}
-      onClick={() => startTransition(() => addToCart(productId))}
-    >
-      {pending ? "Adding..." : "Add to cart"}
-    </button>
-  );
-}
-```
-
-Boundaries:
-
-- Server -> Client: pass serializable props or `children`
-- Client -> Server: invoke Server Actions via `<form action={...}>` or imperatively from event handlers
-- Never `import` a Server Component from a Client Component file — compose them via `children` instead
-
-## Suspense + Error Boundaries
-
-```tsx
-<ErrorBoundary fallback={<ErrorView />}>
-  <Suspense fallback={<UserSkeleton />}>
-    <UserDetail id={id} />
-  </Suspense>
-</ErrorBoundary>
-```
-
-- Place Suspense boundaries close to the data, not at the route root — progressively reveal content
-- Error Boundary remains a class API; use `react-error-boundary` for a hook-friendly wrapper
-- A boundary catches errors thrown during render, lifecycle, and constructors of its children — NOT in event handlers or async code
-
-## Forms
-
-### React 19 form actions (preferred for new code)
-
-```tsx
-"use client";
-import { useActionState } from "react";
-
-const initial = { error: null as string | null };
-
-async function updateUserAction(_prev: typeof initial, formData: FormData) {
-  "use server";
-  const parsed = UserSchema.safeParse(Object.fromEntries(formData));
-  if (!parsed.success) return { error: "Invalid input" };
-  await db.user.update({ where: { id: parsed.data.id }, data: parsed.data });
-  return { error: null };
-}
-
-export function UserForm() {
-  const [state, formAction, pending] = useActionState(updateUserAction, initial);
-  return (
-    <form action={formAction}>
-      <input name="name" required />
-      <button type="submit" disabled={pending}>Save</button>
-      {state.error && <p role="alert">{state.error}</p>}
-    </form>
-  );
-}
-```
-
-### Controlled inputs
-
-Use controlled when the value drives other UI, formats on every keystroke, or implements real-time validation.
-
-### Complex forms
-
-For multi-step forms, dynamic field arrays, or cross-field validation: use a library (React Hook Form, TanStack Form). Roll-your-own state management for forms past trivial complexity is a maintenance trap.
-
-## Data Fetching Decision Matrix
-
-| Need | Tool |
-|---|---|
-| Per-request data in Next.js App Router | RSC `await fetch()` |
-| Client-side cache + mutations + invalidation | TanStack Query |
-| Lightweight client cache + revalidation | SWR |
-| Real-time subscriptions | Server-Sent Events, WebSockets, or the lib's subscription API |
-| One-off fire-and-forget | `fetch()` in an event handler |
-
-Avoid `useEffect` + `fetch` for application data — race conditions, no cache, no retry, no Suspense integration.
-
-## Composition Recipes
-
-### Slot via `children`
-
-```tsx
-<Layout>
-  <Header />
-  <Main>{content}</Main>
-</Layout>
-```
-
-### Named slots
-
-```tsx
-<Page header={<Nav />} sidebar={<Filters />}>
-  <Results />
-</Page>
-```
-
-### Compound components (shared state via Context)
-
-```tsx
-<Tabs defaultValue="profile">
-  <Tabs.List>
-    <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
-    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Panel value="profile"><Profile /></Tabs.Panel>
-  <Tabs.Panel value="settings"><Settings /></Tabs.Panel>
-</Tabs>
-```
-
-### Render prop / function-as-child
-
-Useful when the parent needs to pass parameters to the rendered output:
-
-```tsx
-<DataLoader id={id}>
-  {({ data, isLoading }) => isLoading ? <Spinner /> : <UserCard user={data} />}
-</DataLoader>
-```
-
-Modern alternative: a hook (`useData(id)`) returning the same shape — usually cleaner.
-
-## Performance
-
-### When `React.memo` Actually Helps
-
-Wrap a component in `React.memo` only when:
-
-1. It re-renders frequently
-2. Its props are usually the same between renders
-3. Its render is measurably expensive
-
-`React.memo` adds an equality check on every render. If props differ on most renders, the check is pure overhead.
-
-### Avoiding Render Cascades
-
-- Lift state down rather than up where possible
-- Split context: one context per concern, so a change to `themeContext` does not re-render auth consumers
-- Use `useSyncExternalStore` for external state libraries — required for safe concurrent rendering
-
-### Lists
-
-- Provide stable `key` props (database id, not array index)
-- Virtualize long lists with `@tanstack/react-virtual` or `react-window` once visible item count exceeds ~50 with non-trivial rows
-
-## Accessibility-First Composition
-
-- Always render semantic HTML (`<button>`, `<a>`, `<nav>`, `<main>`) before reaching for `role` attributes
-- Every interactive element must be reachable by keyboard
-- Form inputs need labels — `<label htmlFor>` or `aria-label` if visually labeled by an icon
-- Manage focus on route changes and modal open/close
-- Run `axe` in component tests (see [skills/react-testing](../react-testing/SKILL.md))
-- Cross-link: [skills/accessibility/SKILL.md](../accessibility/SKILL.md) covers WCAG criteria and pattern libraries
-
-## Routing
-
-This skill is router-agnostic. The patterns above work with React Router, TanStack Router, Next.js App Router, Remix Router. Router-specific patterns (loaders, actions, nested layouts) follow the router's documentation — those are framework concerns layered on top of React core.
-
-## Out of Scope (Pointer Sections)
-
-- **Next.js specifics**: App Router data loading, Route Handlers, Middleware, Parallel Routes — separate concern, use Next.js docs
-- **React Native**: Platform-specific patterns differ enough to warrant a separate `react-native-patterns` skill (not present yet)
-- **Remix**: Loader/action conventions overlap with RSC but follow Remix docs
-
-## Related
-
-- Rules: [rules/react/](../../rules/react/) — coding-style, hooks, patterns, security, testing
-- Skills: [react-performance](../react-performance/SKILL.md) for the Vercel-derived performance ruleset, [frontend-patterns](../frontend-patterns/SKILL.md) for cross-framework UI concerns, [accessibility](../accessibility/SKILL.md), [angular-developer](../angular-developer/SKILL.md) for framework comparison
-- Agents: `react-reviewer` for code review, `react-build-resolver` for build/bundler errors
-- Commands: `/react-review`, `/react-build`, `/react-test`
-
-## Examples
-
-### Custom hook for debounced search
-
-```tsx
-function useDebounce<T>(value: T, delay = 300): T {
-  const [debounced, setDebounced] = useState(value);
-  useEffect(() => {
-    const id = setTimeout(() => setDebounced(value), delay);
-    return () => clearTimeout(id);
-  }, [value, delay]);
-  return debounced;
-}
-
-function SearchBox() {
-  const [query, setQuery] = useState("");
-  const debounced = useDebounce(query, 300);
-  const { data } = useQuery({
-    queryKey: ["search", debounced],
-    queryFn: () => searchApi(debounced),
-    enabled: debounced.length > 0,
-  });
-  return (
-    <>
-      <input value={query} onChange={(e) => setQuery(e.target.value)} />
-      <Results items={data ?? []} />
-    </>
-  );
-}
-```
-
-### Optimistic UI with React 19 `useOptimistic`
-
-```tsx
-"use client";
-import { useOptimistic } from "react";
-
-export function MessageList({ messages }: { messages: Message[] }) {
-  const [optimistic, addOptimistic] = useOptimistic(
-    messages,
-    (state, newMessage: Message) => [...state, newMessage],
-  );
-
-  async function send(formData: FormData) {
-    const text = String(formData.get("text"));
-    addOptimistic({ id: "pending", text, sender: "me" });
-    await saveMessage(text);
-  }
-
-  return (
-    <>
-      <ul>{optimistic.map((m) => <li key={m.id}>{m.text}</li>)}</ul>
-      <form action={send}>
-        <input name="text" />
-        <button type="submit">Send</button>
-      </form>
-    </>
-  );
-}
-```
-
-### Splitting context to avoid render cascades
-
-```tsx
-// Two contexts: one rarely changes, one frequently
-const ThemeContext = createContext<Theme>("light");
-const NotificationsContext = createContext<Notification[]>([]);
-
-// A component that only consumes ThemeContext does NOT re-render when notifications change
-```