@skyroc/scripts 2.5.1 → 2.5.2

package/templates/admin-root/.agents/skills/uniwind/references/styling-patterns.md

@@ -0,0 +1,237 @@
+## Styling Third-Party Components
+
+### withUniwind (Recommended)
+
+Wrap once at module level, use with `className` everywhere:
+
+```tsx
+import { withUniwind } from 'uniwind';
+import { Image as ExpoImage } from 'expo-image';
+import { BlurView as RNBlurView } from 'expo-blur';
+import { LinearGradient as RNLinearGradient } from 'expo-linear-gradient';
+
+// Module-level wrapping (NEVER inside render functions)
+export const Image = withUniwind(ExpoImage);
+export const BlurView = withUniwind(RNBlurView);
+export const LinearGradient = withUniwind(RNLinearGradient);
+```
+
+`withUniwind` automatically maps:
+- `style` → `className`
+- `{name}Style` → `{name}ClassName`
+- `{name}Color` → `{name}ColorClassName` (with accent- prefix)
+
+For custom prop mappings:
+
+```tsx
+const StyledProgressBar = withUniwind(ProgressBar, {
+  width: {
+    fromClassName: 'widthClassName',
+    styleProperty: 'width',
+  },
+});
+```
+
+**Usage patterns:**
+
+- **Used in one file only** — define the wrapped component in that same file
+- **Used across multiple files** — wrap once in a shared module (e.g., `components/styled.ts`) and re-export
+
+```tsx
+// components/styled.ts
+import { withUniwind } from 'uniwind';
+import { Image as ExpoImage } from 'expo-image';
+export const Image = withUniwind(ExpoImage);
+
+// Then import everywhere:
+import { Image } from '@/components/styled';
+```
+
+**NEVER** call `withUniwind` on the same component in multiple files.
+
+**CRITICAL**: Do NOT use `withUniwind` on components from `react-native` or `react-native-reanimated`. These already have built-in `className` support:
+
+```tsx
+// WRONG — View already supports className natively
+const StyledView = withUniwind(View);        // DO NOT DO THIS
+const StyledText = withUniwind(Text);        // DO NOT DO THIS
+const StyledAnimatedView = withUniwind(Animated.View); // DO NOT DO THIS
+
+// CORRECT — only wrap third-party components
+const StyledExpoImage = withUniwind(ExpoImage);     // expo-image
+const StyledBlurView = withUniwind(BlurView);        // expo-blur
+const StyledMotiView = withUniwind(MotiView);        // moti
+```
+
+### useResolveClassNames
+
+Converts Tailwind class strings to React Native style objects. Use for one-off cases or components that only accept `style`:
+
+```tsx
+import { useResolveClassNames } from 'uniwind';
+
+const headerStyle = useResolveClassNames('bg-primary p-4');
+const cardStyle = useResolveClassNames('bg-card dark:bg-card rounded-lg shadow-sm');
+
+// React Navigation screen options
+<Stack.Navigator screenOptions={{ headerStyle, cardStyle }} />
+```
+
+### Comparison
+
+| Feature | withUniwind | useResolveClassNames |
+|---------|-------------|----------------------|
+| Setup | Once per component | Per usage |
+| Performance | Optimized | Slightly slower |
+| Best for | Reusable components | One-off, navigation config |
+| Syntax | `className="..."` | `style={...}` |
+
+## Dynamic ClassNames
+
+### NEVER do this (Tailwind scans at build time)
+
+```tsx
+// BROKEN — template literal with variable
+<View className={`bg-${color}-500`} />
+<Text className={`text-${size}`} />
+```
+
+### Correct patterns
+
+```tsx
+// Ternary with complete class names
+<View className={isActive ? 'bg-primary' : 'bg-muted'} />
+
+// Mapping object
+const colorMap = {
+  primary: 'bg-blue-500 text-white',
+  danger: 'bg-red-500 text-white',
+  ghost: 'bg-transparent text-foreground',
+};
+<Pressable className={colorMap[variant]} />
+
+// Array join for multiple conditions
+<View className={[
+  'p-4 rounded-lg',
+  isActive && 'bg-primary',
+  isDisabled && 'opacity-50',
+].filter(Boolean).join(' ')} />
+```
+
+## tailwind-variants (tv)
+
+For complex component styling with variants and compound variants:
+
+```tsx
+import { tv } from 'tailwind-variants';
+
+const button = tv({
+  base: 'font-semibold rounded-lg px-4 py-2 items-center justify-center',
+  variants: {
+    color: {
+      primary: 'bg-blue-500 text-white',
+      secondary: 'bg-gray-500 text-white',
+      danger: 'bg-red-500 text-white',
+      ghost: 'bg-transparent text-foreground border border-border',
+    },
+    size: {
+      sm: 'text-sm px-3 py-1.5',
+      md: 'text-base px-4 py-2',
+      lg: 'text-lg px-6 py-3',
+    },
+    disabled: {
+      true: 'opacity-50',
+    },
+  },
+  compoundVariants: [
+    { color: 'primary', size: 'lg', class: 'bg-blue-600' },
+  ],
+  defaultVariants: { color: 'primary', size: 'md' },
+});
+
+<Pressable className={button({ color: 'primary', size: 'lg' })}>
+  <Text className="text-white font-semibold">Click</Text>
+</Pressable>
+```
+
+## cn Utility — Class Deduplication
+
+Uniwind does **NOT** auto-deduplicate conflicting classNames. This means if the same property appears in multiple classes, **both will be applied and the result is unpredictable**. This is especially critical when mixing custom CSS classes with Tailwind utilities.
+
+### Setup
+
+```bash
+npm install tailwind-merge clsx
+```
+
+```ts
+// lib/cn.ts
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+### When cn Is Required
+
+1. **Merging className props** — component accepts external className that may conflict:
+
+```tsx
+import { cn } from '@/lib/cn';
+
+<View className={cn('p-4 bg-white', props.className)} />
+<Text className={cn('text-base', isActive && 'text-primary', disabled && 'opacity-50')} />
+```
+
+2. **CRITICAL: Mixing custom CSS classes with Tailwind utilities** — if your custom CSS class sets a property that a Tailwind utility also sets, you MUST use `cn()` to deduplicate:
+
+```css
+/* global.css */
+.card {
+  background-color: white;
+  border-radius: 12px;
+  padding: 16px;
+}
+```
+
+```tsx
+// WRONG — both .card (padding: 16px) and p-6 (padding: 24px) apply, result is unpredictable
+<View className="card p-6" />
+
+// CORRECT — cn deduplicates, p-6 wins over .card's padding
+<View className={cn('card', 'p-6')} />
+```
+
+3. **tv() output combined with extra classes** — tv already handles its own variants, but if you add more classes on top:
+
+```tsx
+<Pressable className={cn(button({ color: 'primary' }), props.className)} />
+```
+
+### When cn Is NOT Needed
+
+- Static className with no conflicts: `<View className="flex-1 p-4 bg-white" />`
+- Single custom CSS class with no overlapping Tailwind: `<View className="card-shadow mt-4" />` (if card-shadow only sets box-shadow which no Tailwind class also sets)
+
+## Important Utilities and Style Specificity
+
+Uniwind supports Tailwind's important modifier (`!`) for utilities that must override another utility for the same style property.
+
+```tsx
+import { View, Pressable } from 'react-native';
+
+// bg-red-500! has higher priority than bg-blue-500
+<View className="bg-blue-500 bg-red-500!" />;
+
+// Important utilities work with state and platform variants
+<Pressable className="bg-blue-500 active:bg-red-500!" />;
+<View className="pt-4 ios:pt-12! android:pt-8!" />;
+```
+
+Priority rules:
+- Important utility (`bg-red-500!`) overrides non-important utility (`bg-blue-500`) for the same property.
+- Important variants work normally: `active:bg-red-500!`, `ios:pt-12!`, `dark:text-white!`.
+- Inline `style` always wins, even over important className utilities: `<View className="bg-red-500!" style={{ backgroundColor: 'blue' }} />` renders blue.
+- Use `!` sparingly. For reusable components and consumer overrides, prefer `cn()` with `tailwind-merge`.

package/templates/admin-root/.agents/skills/uniwind/references/theming.md

@@ -0,0 +1,309 @@
+## Theming
+
+### Quick Setup (dark: prefix)
+
+Works immediately — no configuration needed:
+
+```tsx
+<View className="bg-white dark:bg-gray-900">
+  <Text className="text-black dark:text-white">Themed</Text>
+</View>
+```
+
+Best for small apps and prototyping. Does not scale to custom themes.
+
+### Scalable Setup (CSS Variables)
+
+Define in `global.css`, use everywhere without `dark:` prefix:
+
+```css
+@layer theme {
+  :root {
+    @variant light {
+      --color-background: #ffffff;
+      --color-foreground: #111827;
+      --color-foreground-secondary: #6b7280;
+      --color-card: #ffffff;
+      --color-border: #e5e7eb;
+      --color-muted: #9ca3af;
+      --color-primary: #3b82f6;
+      --color-danger: #ef4444;
+      --color-success: #10b981;
+    }
+    @variant dark {
+      --color-background: #000000;
+      --color-foreground: #ffffff;
+      --color-foreground-secondary: #9ca3af;
+      --color-card: #1f2937;
+      --color-border: #374151;
+      --color-muted: #6b7280;
+      --color-primary: #3b82f6;
+      --color-danger: #ef4444;
+      --color-success: #10b981;
+    }
+  }
+}
+```
+
+```tsx
+// Auto-adapts to current theme — no dark: prefix needed
+<View className="bg-card border border-border p-4 rounded-lg">
+  <Text className="text-foreground text-lg font-bold">Title</Text>
+  <Text className="text-muted mt-2">Subtitle</Text>
+</View>
+```
+
+Variable naming: `--color-background` → `bg-background`, `text-background`.
+
+**Prefer CSS variables over explicit `dark:` variants** — they're cleaner, maintain easier, and work with custom themes automatically.
+
+### Custom Themes
+
+**Step 1** — Define in `global.css`:
+
+```css
+@layer theme {
+  :root {
+    @variant light { /* ... */ }
+    @variant dark { /* ... */ }
+    @variant ocean {
+      --color-background: #0c4a6e;
+      --color-foreground: #e0f2fe;
+      --color-primary: #06b6d4;
+      --color-card: #0e7490;
+      --color-border: #155e75;
+      /* Must define ALL the same variables as light/dark */
+    }
+  }
+}
+```
+
+**Step 2** — Register in `metro.config.js` (exclude `light`/`dark` — they're automatic):
+
+```js
+module.exports = withUniwindConfig(config, {
+  cssEntryFile: './global.css',
+  extraThemes: ['ocean'],
+});
+```
+
+Restart Metro after adding themes.
+
+**Step 3** — Use:
+
+```tsx
+Uniwind.setTheme('ocean');
+```
+
+### Theme API
+
+```tsx
+import { Uniwind, useUniwind } from 'uniwind';
+
+// Imperative (no re-render)
+Uniwind.setTheme('dark');          // Force dark
+Uniwind.setTheme('light');         // Force light
+Uniwind.setTheme('system');        // Follow device (re-enables adaptive themes)
+Uniwind.setTheme('ocean');         // Custom theme (must be in extraThemes)
+Uniwind.currentTheme;              // Current theme name
+Uniwind.hasAdaptiveThemes;         // true if following system
+
+// Reactive hook (re-renders on change)
+const { theme, hasAdaptiveThemes } = useUniwind();
+```
+
+`Uniwind.setTheme('light')` / `setTheme('dark')` also calls `Appearance.setColorScheme` to sync native components (Alert, Modal, system dialogs).
+
+By default Uniwind uses "system" theme - follows device color scheme. If user wants to override it, just
+call Uniwind.setTheme with desired theme. It can be done above the React component to avoid theme switching at runtime.
+
+### Theme Switcher Example
+
+```tsx
+import { View, Pressable, Text, ScrollView } from 'react-native';
+import { Uniwind, useUniwind } from 'uniwind';
+
+export const ThemeSwitcher = () => {
+  const { theme, hasAdaptiveThemes } = useUniwind();
+  const activeTheme = hasAdaptiveThemes ? 'system' : theme;
+
+  const themes = [
+    { name: 'light', label: 'Light' },
+    { name: 'dark', label: 'Dark' },
+    { name: 'system', label: 'System' },
+  ];
+
+  return (
+    <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+      <View className="flex-row gap-2 p-4">
+        {themes.map((t) => (
+          <Pressable
+            key={t.name}
+            onPress={() => Uniwind.setTheme(t.name)}
+            className={`px-4 py-3 rounded-lg items-center ${
+              activeTheme === t.name ? 'bg-primary' : 'bg-card border border-border'
+            }`}
+          >
+            <Text className={`text-sm ${
+              activeTheme === t.name ? 'text-white' : 'text-foreground'
+            }`}>
+              {t.label}
+            </Text>
+          </Pressable>
+        ))}
+      </View>
+    </ScrollView>
+  );
+};
+```
+
+### ScopedTheme
+
+Apply a different theme to a subtree without changing the global theme:
+
+```tsx
+import { ScopedTheme } from 'uniwind';
+
+<View className="gap-3">
+  <PreviewCard />
+
+  <ScopedTheme theme="dark">
+    <PreviewCard />  {/* Renders with dark theme */}
+  </ScopedTheme>
+
+  <ScopedTheme theme="ocean">
+    <PreviewCard />  {/* Renders with ocean theme */}
+  </ScopedTheme>
+</View>
+```
+
+- Nearest `ScopedTheme` wins (nested scopes supported)
+- Hooks (`useUniwind`, `useResolveClassNames`, `useCSSVariable`) resolve against the nearest scoped theme
+- `withUniwind`-wrapped components inside the scope also resolve scoped theme values
+- Custom themes require registration in `extraThemes`
+
+### LayoutDirection (v1.8.0+)
+
+Scope RTL/LTR variants to a subtree without changing global device RTL state:
+
+```tsx
+import { LayoutDirection } from 'uniwind';
+
+<View className="gap-3">
+  <Text className="ltr:text-left rtl:text-right">Uses global RTL state</Text>
+
+  <LayoutDirection rtl>
+    <Text className="ltr:text-left rtl:text-right">Forced RTL subtree</Text>
+  </LayoutDirection>
+
+  <LayoutDirection rtl={false}>
+    <Text className="ltr:text-left rtl:text-right">Forced LTR subtree</Text>
+  </LayoutDirection>
+</View>
+```
+
+- Available from `uniwind@1.8.0`.
+- `rtl` prop: `true` forces RTL, `false` forces LTR.
+- Omit `rtl` to inherit parent `LayoutDirection`; outside any parent it falls back to global RTL state.
+- Nearest `LayoutDirection` wins (nested scopes supported).
+- Prefer `LayoutDirection` over inline `style={{ direction: 'rtl' }}` for `rtl:`/`ltr:` variant scoping.
+- Hooks (`useResolveClassNames`, `useCSSVariable`) and `withUniwind`-wrapped components inside the scope resolve against the nearest layout direction.
+
+### useCSSVariable
+
+Access CSS variable values in JavaScript:
+
+```tsx
+import { useCSSVariable } from 'uniwind';
+
+const primaryColor = useCSSVariable('--color-primary');
+const spacing = useCSSVariable('--spacing-4');
+
+// Multiple variables at once
+const [bg, fg] = useCSSVariable(['--color-background', '--color-foreground']) as [string, string]
+```
+
+Use for: animations, chart libraries, third-party component configs, calculations with design tokens.
+
+It's required to cast the result of `useCSSVariable` as it can return: string | number | undefined.
+Uniwind doesn't know if given variable exist and what type it is, so it returns union type.
+
+### getCSSVariable
+
+Read CSS variable values outside of React (event handlers, async callbacks, utility modules, worklets). Available in Uniwind 1.6.4+.
+
+```ts
+import { Uniwind } from 'uniwind';
+
+const primary = Uniwind.getCSSVariable('--color-primary');
+const [bg, fg] = Uniwind.getCSSVariable(['--color-background', '--color-foreground']) as [string, string];
+```
+
+Same value rules as `useCSSVariable` (variable must be used in a `className` or declared in `@theme static`). Same return type: `string | number | undefined`. Cast as needed.
+
+Not reactive — value is read once. For reactive values inside components use `useCSSVariable`. Use `getCSSVariable` for one-shot reads (onPress handlers, utility functions, native module configs).
+
+### Runtime CSS Variable Updates
+
+Update theme variables at runtime (e.g., user-selected brand colors or API-driven themes):
+
+```tsx
+Uniwind.updateCSSVariables('light', {
+  '--color-primary': '#ff6600',
+  '--color-background': '#fafafa',
+});
+```
+
+Updates are theme-specific and take effect immediately.
+
+### @theme static
+
+For JS-only values not used in classNames:
+
+```css
+@theme static {
+  --chart-line-width: 2;
+  --chart-dot-radius: 4;
+  --animation-duration: 300;
+}
+```
+
+Access via `useCSSVariable('--chart-line-width')`. Use for: chart configs, animation durations, native module values.
+
+### OKLCH Colors support
+
+Perceptually uniform color format — wider gamut, consistent lightness:
+
+```css
+@layer theme {
+  :root {
+    @variant light {
+      --color-primary: oklch(0.5 0.2 240);
+      --color-background: oklch(1 0 0);
+    }
+    @variant dark {
+      --color-primary: oklch(0.6 0.2 240);
+      --color-background: oklch(0.13 0.004 17.69);
+    }
+  }
+}
+```
+
+### Display P3 Colors support
+
+Wide-gamut color format for devices that support the P3 color space (most modern iPhones and Macs). Uniwind parses `color(display-p3 ...)` values and converts them for native use:
+
+```css
+@layer theme {
+  :root {
+    @variant light {
+      --color-primary: color(display-p3 0.2 0.4 1);
+      --color-accent: color(display-p3 1 0.3 0.3);
+    }
+    @variant dark {
+      --color-primary: color(display-p3 0.3 0.5 1);
+      --color-accent: color(display-p3 1 0.4 0.4);
+    }
+  }
+}
+```