ginskill-init 2.7.0

package/skills/react-native-expo/references/state-management.md

@@ -0,0 +1,209 @@
+# State Management — Zustand v5 + MMKV
+
+## Architecture Overview
+
+- **Server state**: React Query (never duplicate in Zustand)
+- **Client state**: Zustand with MMKV or AsyncStorage persistence
+- **Secure storage**: react-native-keychain (JWT tokens only)
+- **Fast sync storage**: MMKV (non-sensitive persisted state)
+
+## Zustand Store Patterns
+
+### Simple Store
+
+```typescript
+import { create } from "zustand"
+import { persist, createJSONStorage } from "zustand/middleware"
+import { MMKV } from "react-native-mmkv"
+
+const storage = new MMKV()
+const mmkvStorage = {
+  getItem: (name: string) => storage.getString(name) ?? null,
+  setItem: (name: string, value: string) => storage.set(name, value),
+  removeItem: (name: string) => storage.delete(name),
+}
+
+interface UserStore {
+  user: UserRes | null
+  setUser: (user: UserRes | null) => void
+  updateUser: (partial: Partial<UserRes>) => void
+  clearUser: () => void
+  isPremium: () => boolean
+}
+
+export const useUserStore = create<UserStore>()(
+  persist(
+    (set, get) => ({
+      user: null,
+      setUser: (user) => set({ user }),
+      updateUser: (partial) => set({ user: { ...get().user!, ...partial } }),
+      clearUser: () => set({ user: null }),
+      isPremium: () => get().user?.subscription === "premium",
+    }),
+    {
+      name: "user-store",
+      storage: createJSONStorage(() => mmkvStorage),
+      partialize: (state) => ({ user: state.user }),
+    },
+  ),
+)
+```
+
+### Composite Store with Slice Factories
+
+The app uses a composite store pattern:
+
+```typescript
+import { StateCreator } from "zustand"
+
+// Slice factory
+interface StySlice {
+  styBalance: StyBalance | null
+  isCheckInSheetVisible: boolean
+  setStyBalance: (balance: StyBalance | null) => void
+  syncStyBalance: () => Promise<void>
+  hasSty: () => boolean
+}
+
+export const createStySlice: StateCreator<AppStore, [], [], StySlice> = (set, get) => ({
+  styBalance: null,
+  isCheckInSheetVisible: false,
+  setStyBalance: (balance) => set({ styBalance: balance }),
+  syncStyBalance: async () => {
+    try {
+      const balance = await getStyBalance()
+      set({ styBalance: balance })
+    } catch (error) {
+      appLog.error("[Sty] Failed to sync balance:", error)
+    }
+  },
+  hasSty: () => (get().styBalance?.total ?? 0) > 0,
+})
+
+// Composite store (app-store.ts)
+type AppStore = AppState & ChatSlice & StySlice & AdaptySlice
+
+export const useAppStore = create<AppStore>()(
+  persist(
+    (set, get) => ({
+      ...createChatSlice(set, get),
+      ...createStySlice(set, get),
+      ...createAdaptySlice(set, get),
+      isAuthenticated: false,
+      isAppInitialized: false,
+      isHydrated: false,
+      setAuthenticated: (v) => set({ isAuthenticated: v }),
+      logout: () => { clearTokens(); set({ isAuthenticated: false }) },
+      initializeApp: () => set({ isAppInitialized: true }),
+    }),
+    {
+      name: "app-store",
+      storage: createJSONStorage(() => AsyncStorage),
+      partialize: (state) => ({ isAuthenticated: state.isAuthenticated }),
+      onRehydrateStorage: () => () => {
+        useAppStore.setState({ isHydrated: true })
+      },
+    },
+  ),
+)
+```
+
+### Using Stores in Components
+
+**ALWAYS use `useShallow`** when selecting multiple fields:
+
+```typescript
+import { useShallow } from "zustand/react/shallow"
+
+// CORRECT — useShallow prevents unnecessary re-renders
+const { user, setUser } = useUserStore(
+  useShallow((state) => ({ user: state.user, setUser: state.setUser })),
+)
+
+// CORRECT — single primitive selector (no useShallow needed)
+const styBalance = useUserStore((state) => state.styBalance)
+
+// WRONG — creates new object reference every render
+const { user, setUser } = useUserStore((state) => ({
+  user: state.user,
+  setUser: state.setUser,
+}))
+```
+
+### Feature Dialog Stores
+
+Features use dedicated stores for dialog state:
+
+```typescript
+interface ItemDialogsStore {
+  activeDialog: ItemDialogTypeEnum | null
+  selectedItemId: string | null
+  openDialog: (type: ItemDialogTypeEnum, itemId: string) => void
+  closeDialog: () => void
+}
+
+export const useItemDialogsStore = create<ItemDialogsStore>((set) => ({
+  activeDialog: null,
+  selectedItemId: null,
+  openDialog: (type, itemId) => set({ activeDialog: type, selectedItemId: itemId }),
+  closeDialog: () => set({ activeDialog: null, selectedItemId: null }),
+}))
+```
+
+### Hydration Check
+
+```typescript
+// Wait for Zustand hydration before using persisted state
+const isHydrated = useAppStore((s) => s.isHydrated)
+
+// Or use persist API
+const isHydrated = useAppStore.persist.hasHydrated()
+useEffect(() => {
+  const unsub = useAppStore.persist.onFinishHydration(() => { /* ready */ })
+  return unsub
+}, [])
+```
+
+## Existing Stores
+
+| Store | File | Purpose |
+|-------|------|---------|
+| `useAppStore` | `shared/stores/app-store.ts` | Composite: auth + chat + sty + adapty slices |
+| `useUserStore` | `shared/stores/user-store.ts` | User profile, subscription, access level |
+| `useFeedbackStore` | `shared/stores/feedback-store.ts` | Feedback dialog state |
+| `useTryOnStore` | `shared/stores/try-on-store.ts` | Try-on feature state |
+| `useNewItemsStore` | `shared/stores/new-items-store.ts` | New items tracking |
+| `useFullBodyImageStore` | `shared/stores/full-body-image-store.ts` | Full body photo state |
+| `useVersionCheckStore` | `shared/stores/version-check-store.ts` | App version check |
+| `useStylistNameStore` | `shared/stores/stylist-name-store.ts` | AI stylist name |
+| `useDuplicateCheckStore` | `shared/stores/duplicate-check-store.ts` | Duplicate detection |
+| `useUnreadStylistStore` | `shared/stores/unread-stylist-store.ts` | Unread chat badge |
+
+## MMKV Direct Usage
+
+For simple key-value outside Zustand:
+
+```typescript
+import { MMKV } from "react-native-mmkv"
+const storage = new MMKV()
+
+storage.set("user.language", "en")        // String
+storage.set("onboarding.complete", true)  // Boolean
+storage.set("app.launchCount", 5)         // Number
+const lang = storage.getString("user.language")
+storage.delete("key")
+storage.contains("key")
+```
+
+## Best Practices
+
+- **Server state in React Query**, not Zustand — never cache API responses in stores
+- **Use `partialize`** to exclude runtime-only state from persistence
+- **Use `useShallow`** when selecting multiple fields
+- **Single selector for primitives** — no `useShallow` needed
+- **Keep stores small** — split by domain
+- **MMKV for speed** — synchronous, 30-100x faster than AsyncStorage
+- **Keychain for secrets** — JWT tokens only in `react-native-keychain`
+- **Batch state updates** in single `set()` call
+- **Use `getState()`** for reading in async functions (no hook needed)
+- **Atomic updates**: Read + write in single `set()` or use `get()` inside setter

package/skills/react-native-expo/references/ui-patterns.md

@@ -0,0 +1,301 @@
+# UI Patterns — Forms, Bottom Sheets, Components
+
+## Forms — react-hook-form + zod
+
+### Schema + Hook
+
+```typescript
+import { z } from "zod"
+import { useForm, Controller } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+
+const createItemSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  category: z.string().min(1, "Category is required"),
+  brand: z.string().optional(),
+  notes: z.string().max(500).optional(),
+})
+
+type CreateItemForm = z.infer<typeof createItemSchema>
+
+const useItemForm = (defaults?: Partial<CreateItemForm>) =>
+  useForm<CreateItemForm>({
+    resolver: zodResolver(createItemSchema),
+    defaultValues: { name: "", category: "", brand: "", ...defaults },
+  })
+```
+
+### Form Component
+
+```typescript
+const ItemForm = () => {
+  const { control, handleSubmit, formState: { errors } } = useItemForm()
+  const { mutate: createItem, isPending } = useCreateItem()
+
+  return (
+    <View>
+      <Controller
+        control={control}
+        name="name"
+        render={({ field: { onChange, onBlur, value } }) => (
+          <TextInput
+            placeholder="Item name"
+            onChangeText={onChange}     // onChangeText, NOT onChange
+            onBlur={onBlur}
+            value={value}
+          />
+        )}
+      />
+      {errors.name && (
+        <Typography variant="b3" color={Theme.color.error}>
+          {errors.name.message}
+        </Typography>
+      )}
+      <Button title="Save" onPress={handleSubmit((d) => createItem(d))} loading={isPending} />
+    </View>
+  )
+}
+```
+
+### React Native Specifics
+
+- Use `onChangeText` not `onChange` for TextInput
+- Use `Controller` wrapper (RN doesn't support `ref` registration)
+- Stick with **zod v3** syntax — v4 has RN compatibility issues
+- Memoize `onSubmit` with `useCallback` for list forms
+
+## Bottom Sheet — @gorhom/bottom-sheet v5
+
+### Basic Usage
+
+```typescript
+import BottomSheet, { BottomSheetView, BottomSheetBackdrop } from "@gorhom/bottom-sheet"
+
+const MySheet = () => {
+  const ref = useRef<BottomSheet>(null)
+  const snapPoints = useMemo(() => ["25%", "50%", "90%"], [])
+
+  return (
+    <BottomSheet
+      ref={ref}
+      snapPoints={snapPoints}
+      enableDynamicSizing={false}   // Disable when using fixed snap points
+      enablePanDownToClose
+      index={-1}                     // Start closed
+      backdropComponent={BottomSheetBackdrop}
+    >
+      <BottomSheetView>{/* Content */}</BottomSheetView>
+    </BottomSheet>
+  )
+}
+```
+
+### With Scrollable Content
+
+```typescript
+import { BottomSheetScrollView, BottomSheetFlashList } from "@gorhom/bottom-sheet"
+
+// ScrollView
+<BottomSheet snapPoints={["50%", "90%"]}>
+  <BottomSheetScrollView>{/* content */}</BottomSheetScrollView>
+</BottomSheet>
+
+// FlashList
+<BottomSheet snapPoints={["50%", "90%"]}>
+  <BottomSheetFlashList data={items} renderItem={renderItem} estimatedItemSize={60} />
+</BottomSheet>
+```
+
+### Dynamic Sizing (v5 default)
+
+v5 enables dynamic sizing by default. Disable for fixed snap points or limit height:
+```typescript
+<BottomSheet enableDynamicSizing={false} snapPoints={["50%"]} />
+<BottomSheet enableDynamicSizing maxDynamicContentSize={500} />
+```
+
+### ⚠️ CRITICAL: Dynamic Sizing + Scrollable Content
+
+**NEVER** use `enableDynamicSizing={true}` with `BottomSheetScrollView` or `BottomSheetFlashList`.
+Dynamic sizing measures children's intrinsic height via `BottomSheetView`, but scrollable content
+has no fixed intrinsic height → sheet appears truncated (header-only).
+
+```typescript
+// ❌ WRONG — sheet will appear truncated, only showing header
+<BottomSheetWrapper ref={ref} name="my-sheet">
+  <BottomSheetScrollView>{/* list content */}</BottomSheetScrollView>
+</BottomSheetWrapper>
+
+// ✅ CORRECT — disable dynamic sizing, use explicit snap points
+const snapPoints = useMemo(() => ["50%"], [])
+
+<BottomSheetWrapper ref={ref} name="my-sheet" enableDynamicSizing={false} snapPoints={snapPoints}>
+  <BottomSheetScrollView>{/* list content */}</BottomSheetScrollView>
+</BottomSheetWrapper>
+```
+
+The app's `BottomSheetWrapper` defaults to `enableDynamicSizing={true}`. Always override when content is scrollable.
+
+### BottomSheetWrapper (App Component)
+
+Located at `@/shared/components/bottom-sheet`. Wraps `@gorhom/bottom-sheet` BottomSheetModal with:
+- Auto safe-area bottom padding
+- Header component (title + close button + drag handle)
+- Backdrop with 0.5 opacity
+- Patched `present()` that always cleans up first (no stuck states)
+
+```typescript
+import { BottomSheetModal } from "@gorhom/bottom-sheet"
+import { BottomSheetWrapper } from "@/shared/components/bottom-sheet"
+
+const ref = useRef<BottomSheetModal>(null)
+const snapPoints = useMemo(() => ["50%"], [])
+
+<BottomSheetWrapper
+  ref={ref}
+  name="my-sheet"
+  enableDynamicSizing={false}
+  snapPoints={snapPoints}
+  header={{
+    title: "Sheet Title",
+    showCloseButton: true,
+    closeButtonText: "Cancel",
+  }}
+  onDismiss={() => setSheetOpen(false)}
+>
+  {/* Content */}
+</BottomSheetWrapper>
+
+// Open: ref.current?.present()
+// Close: ref.current?.dismiss()
+```
+
+## Shared Components
+
+### Typography
+
+```typescript
+import { Typography } from "@/shared/components"
+
+<Typography variant="h1">Title</Typography>
+<Typography variant="b2" color={Theme.color.textSecondary}>Body</Typography>
+<Typography variant="b3" numberOfLines={2}>Truncated</Typography>
+```
+
+### Button
+
+```typescript
+import { Button } from "@/shared/components"
+
+// Variants: primary (brand+shadow), secondary (neutral), outline, ghost, danger
+// Sizes: small (36px), medium (44px), large (52px)
+<Button title="Save" variant="primary" onPress={handlePress} loading={isPending} />
+<Button title="Cancel" variant="secondary" onPress={handleCancel} />
+<Button title="Delete" variant="danger" onPress={handleDelete} />
+```
+
+### Image (expo-image)
+
+```typescript
+import { Image } from "expo-image"
+
+<Image
+  source={{ uri: imageUrl }}
+  style={{ width: 120, height: 120, borderRadius: Spacing.sm }}
+  contentFit="cover"
+  transition={200}
+  cachePolicy="memory-disk"
+  recyclingKey={item._id}   // Important in lists
+/>
+```
+
+### Loading Skeletons
+
+```typescript
+import { Shimmer } from "@/shared/components"
+
+{isLoading ? (
+  <Shimmer width={200} height={20} borderRadius={4} />
+) : (
+  <Typography variant="b1">{data.name}</Typography>
+)}
+```
+
+Platform-specific: `shimmer.ios.tsx` / `shimmer.android.tsx`
+
+### Toast Messages
+
+```typescript
+import { showSuccessToast, showErrorToast } from "@/shared/components/toast"
+
+showSuccessToast("Success", "Item saved successfully")
+showErrorToast("Error", "Failed to save item")
+```
+
+### Dialogs
+
+```typescript
+// Pattern: Zustand store controls dialog visibility
+const { isOpen, open, close } = useDialogStore(
+  useShallow((s) => ({ isOpen: s.isOpen, open: s.open, close: s.close }))
+)
+
+<Dialog visible={isOpen} onDismiss={close}>
+  <Dialog.Title>Confirm</Dialog.Title>
+  <Dialog.Content><Typography variant="b1">Are you sure?</Typography></Dialog.Content>
+  <Dialog.Actions>
+    <Button title="Cancel" variant="secondary" onPress={close} />
+    <Button title="Delete" variant="danger" onPress={handleDelete} />
+  </Dialog.Actions>
+</Dialog>
+```
+
+### Glass Morphism Components
+
+Available in `@/shared/components/`: `GlassCard`, `GlassButton`, `GlassInput`
+
+## Keyboard Handling
+
+```typescript
+import { KeyboardAwareScrollView } from "react-native-keyboard-controller"
+
+<KeyboardAwareScrollView>{/* Form content */}</KeyboardAwareScrollView>
+```
+
+## Image Picking & Compression
+
+```typescript
+import * as ImagePicker from "expo-image-picker"
+import { compressImage } from "@/shared/utils/compress-image"
+
+const result = await ImagePicker.launchImageLibraryAsync({
+  mediaTypes: ImagePicker.MediaTypeOptions.Images,
+  quality: 0.8,
+  allowsEditing: true,
+  aspect: [1, 1],
+})
+if (!result.canceled) {
+  const compressed = await compressImage(result.assets[0].uri)
+}
+```
+
+## Calendar
+
+```typescript
+import { Calendar } from "@marceloterreiro/flash-calendar"
+
+<Calendar
+  calendarActiveDateRanges={activeDateRanges}
+  onCalendarDayPress={handleDayPress}
+/>
+```
+
+## Popover
+
+```typescript
+import Popover from "react-native-popover-view"
+
+<Popover from={<TouchableOpacity><Icon name="more" /></TouchableOpacity>}>
+  {/* Menu content */}
+</Popover>
+```