@idealyst/components 1.0.83 → 1.0.84

package/CLAUDE.md

@@ -1,236 +1,203 @@
-# @idealyst/components - LLM Documentation
-
-This file provides comprehensive component documentation for LLMs working with the @idealyst/components library.
-
-## Library Overview
-
-@idealyst/components is a cross-platform React/React Native component library with:
-- 14 core components organized into 7 categories
-- Theme-based styling with Unistyles
-- Intent-based color system (primary, neutral, success, error, warning)
-- Cross-platform compatibility (React & React Native)
-- TypeScript support
-
-## Component Categories
-
-### Layout Components
-- **View**: Container with spacing system (`spacing="xs|sm|md|lg|xl|xxl"`)
-- **Screen**: Full-screen container (`background="primary|secondary|tertiary|inverse"`, `safeArea`, `padding`)
-- **Divider**: Content separator (`orientation="horizontal|vertical"`, `spacing`, `intent`)
-
-### Typography
-- **Text**: Styled text (`size="small|medium|large|xlarge"`, `weight="light|normal|medium|semibold|bold"`, `color`, `intent`, `align`)
-
-### Form Components
-- **Button**: Interactive button (`variant="contained|outlined|text"`, `intent="primary|neutral|success|error|warning"`, `size="small|medium|large"`)
-- **Input**: Text input (`label`, `placeholder`, `error`, `helperText`, `multiline`, `secureTextEntry`)
-- **Checkbox**: Form checkbox (`checked`, `onCheckedChange`, `label`, `disabled`, `intent`)
-
-### Display Components
-- **Card**: Content container (`variant="default|outlined|elevated|filled"`, `padding`, `radius`, `clickable`, `intent`)
-- **Badge**: Status indicator (`variant="filled|outlined|dot"`, `color`, `size="small|medium|large"`)
-- **Avatar**: Profile picture (`src`, `fallback`, `size="small|medium|large|xlarge"`, `shape="circle|square"`)
-
-### Utility Components
-- **Icon**: Icon display (`name`, `size`, `color`, `intent`)
-- **SVGImage**: SVG rendering (`source`, `width`, `height`, `size`, `color`, `intent`)
-
-### Overlay Components
-- **Dialog**: Modal dialog (`open`, `onOpenChange`, `title`, `size="small|medium|large"`, `variant="default"`, `showCloseButton`, `closeOnBackdropClick`, `closeOnEscapeKey`)
-- **Popover**: Contextual overlay (`open`, `onOpenChange`, `anchor`, `placement="top|bottom|left|right"`, `offset`, `closeOnClickOutside`, `closeOnEscapeKey`, `showArrow`)
-
-## Intent System
-
-All components use a consistent intent-based color system:
-- `primary`: Main brand actions
-- `neutral`: Secondary actions  
-- `success`: Positive actions (save, confirm)
-- `error`: Destructive actions (delete, cancel)
-- `warning`: Caution actions
-
-## Common Patterns
-
-### Basic Layout
-```tsx
-<Screen background="primary" safeArea>
-  <View spacing="lg">
-    <Text size="xlarge" weight="bold">Title</Text>
-    <Text>Content</Text>
-  </View>
-</Screen>
+# Components Package - Style System Refactoring
+
+## Current Task: Converting to Static Style Pattern
+
+We are systematically converting all component style files from dynamic functions to static styles with proper variants and compound variants.
+
+## The Correct Pattern (Reference: Button.styles.tsx)
+
+### 1. Style File Structure
+
+```typescript
+import { StyleSheet } from 'react-native-unistyles';
+import { Theme, Intent, CompoundVariants } from '@idealyst/theme';
+import { buildSizeVariants } from '../utils/buildSizeVariants';
+
+// Export the Variants type for component use
+export type ButtonVariants = {
+    size: ButtonSize;
+    intent: ButtonIntent;
+    type: ButtonType;
+    disabled: boolean;
+}
+
+// Create intent variants dynamically from theme (NO HARDCODED ARRAYS)
+function createIntentVariants(theme: Theme) {
+    const variants: any = {};
+    for (const intent in theme.intents) {
+        variants[intent] = {};
+    }
+    return variants;
+}
+
+// Create type variants (structure only)
+function createTypeVariants(theme: Theme) {
+    return {
+        contained: {
+            borderWidth: 0,
+        },
+        outlined: {
+            borderWidth: 2,
+            borderStyle: 'solid' as const,
+        },
+    } as const;
+}
+
+// Create compound variants for multi-variant combinations
+function createButtonCompoundVariants(theme: Theme) {
+    const compoundVariants: CompoundVariants<keyof ButtonVariants> = [];
+
+    for (const intent in theme.intents) {
+        const intentValue = theme.intents[intent as Intent];
+
+        compoundVariants.push({
+            intent,
+            type: 'contained',
+            styles: {
+                backgroundColor: intentValue.primary,
+                color: intentValue.contrast,
+            },
+        });
+    }
+
+    return compoundVariants;
+}
+
+// Export styles - NO explicit return type annotation
+export const buttonStyles = StyleSheet.create((theme: Theme) => {
+    return {
+        button: {
+            alignItems: 'center',
+            variants: {
+                size: buildSizeVariants(theme, 'button', ...),
+                intent: createIntentVariants(theme),
+                type: createTypeVariants(theme),
+                disabled: { true: {}, false: {} },
+            },
+            compoundVariants: createButtonCompoundVariants(theme),
+        },
+    };
+});
 ```
 
-### Form Layout
-```tsx
-<View spacing="md">
-  <Input label="Email" value={email} onChangeText={setEmail} />
-  <Button variant="contained" intent="primary" onPress={submit}>Submit</Button>
-</View>
+### 2. Component Implementation
+
+```typescript
+import React, { forwardRef, ComponentRef } from 'react';
+import { TouchableOpacity } from 'react-native';
+import { buttonStyles } from './Button.styles';
+import type { ButtonProps } from './types';
+
+const Button = forwardRef<ComponentRef<typeof TouchableOpacity>, ButtonProps>((props, ref) => {
+    const { size = 'md', intent = 'primary', type = 'contained', disabled = false } = props;
+
+    // Apply variants (intent is now a proper variant)
+    buttonStyles.useVariants({
+        size,
+        intent,
+        type,
+        disabled,
+    });
+
+    return (
+        <TouchableOpacity
+            ref={ref}
+            style={[buttonStyles.button, style]}  // Static style, no function call
+        >
+            <Text style={buttonStyles.text}>{children}</Text>
+        </TouchableOpacity>
+    );
+});
 ```
 
-### SVG Usage
-```tsx
-import MyIcon from './assets/icon.svg';
-
-<SVGImage source={MyIcon} size={24} intent="primary" />
-<SVGImage source={{ uri: "https://cdn.jsdelivr.net/npm/simple-icons@v9/icons/react.svg" }} size={32} color="#61dafb" />
-```
-
-### Card with Content
-```tsx
-<Card variant="outlined" clickable onPress={handlePress}>
-  <View spacing="sm">
-    <Text weight="bold">Title</Text>
-    <Text size="small" color="secondary">Subtitle</Text>
-  </View>
-</Card>
-```
-
-### Dialog Usage
-```tsx
-const [dialogOpen, setDialogOpen] = useState(false);
-
-<Dialog
-  open={dialogOpen}
-  onOpenChange={setDialogOpen}
-  title="Confirm Action"
-  size="medium"
->
-  <View spacing="md">
-    <Text>Are you sure you want to proceed?</Text>
-    <View style={{ flexDirection: 'row', gap: 8 }}>
-      <Button variant="outlined" onPress={() => setDialogOpen(false)}>
-        Cancel
-      </Button>
-      <Button variant="contained" intent="primary" onPress={handleConfirm}>
-        Confirm
-      </Button>
-    </View>
-  </View>
-</Dialog>
-```
-
-### Popover Usage
-```tsx
-const [popoverOpen, setPopoverOpen] = useState(false);
-const buttonRef = useRef<HTMLDivElement>(null);
-
-<div ref={buttonRef} style={{ display: 'inline-block' }}>
-  <Button onPress={() => setPopoverOpen(true)}>
-    Show Menu
-  </Button>
-</div>
-<Popover
-  open={popoverOpen}
-  onOpenChange={setPopoverOpen}
-  anchor={buttonRef}
-  placement="bottom-start"
-  showArrow
->
-  <View spacing="sm">
-    <Button variant="text" onPress={handleAction}>Action 1</Button>
-    <Button variant="text" onPress={handleAction}>Action 2</Button>
-  </View>
-</Popover>
-```
-
-## Styling Guidelines
-
-1. **Use variants over manual styles** - Components provide semantic variants
-2. **Manual styles override variants** - Style prop takes precedence
-3. **Consistent spacing** - Use View spacing prop for consistent gaps
-4. **Intent-based colors** - Use intent props for semantic meaning
-5. **Cross-platform compatibility** - All components work on React and React Native
-
-## Import Patterns
-
-```tsx
-// Individual imports (recommended)
-import { Button, Text, View, Dialog, Popover } from '@idealyst/components';
-
-// Documentation access
-import { componentDocs, getComponentDocs } from '@idealyst/components/docs';
-
-// Examples
-import { ButtonExamples, DialogExamples, PopoverExamples } from '@idealyst/components/examples';
-```
-
-## Key Props Reference
-
-### Universal Props (most components)
-- `style`: Additional custom styles
-- `testID`: Test identifier
-- `disabled`: Disable interaction
-
-### Layout Props
-- `spacing`: Gap between children (`View`)
-- `padding`: Internal padding (`Screen`, `Card`)
-- `background`: Background color variant (`Screen`)
-
-### Styling Props
-- `variant`: Visual style variant
-- `intent`: Color scheme/semantic meaning
-- `size`: Component size
-- `color`: Color override
-
-### Interactive Props
-- `onPress`: Press handler (`Button`, `Card`, `Checkbox`)
-- `clickable`: Enable interaction (`Card`)
-- `checked`: Checkbox state
-- `value`/`onChangeText`: Input state
-
-## Accessibility Features
-
-- Proper ARIA roles and labels
-- Keyboard navigation support
-- Screen reader compatibility
-- Focus management
-- Touch target sizing (minimum 44px)
-
-## Documentation Access for LLMs
-
-### File-Based Documentation Access
-All documentation is available as markdown files in the package:
-
-```bash
-# Quick overview - START HERE
-CLAUDE.md
-
-# Complete library overview with component table
-README.md
-
-# Detailed documentation for each component
-src/Avatar/README.md
-src/Badge/README.md  
-src/Button/README.md
-src/Card/README.md
-src/Checkbox/README.md
-src/Dialog/README.md
-src/Divider/README.md
-src/Icon/README.md
-src/Input/README.md
-src/Popover/README.md
-src/Screen/README.md
-src/Text/README.md
-src/View/README.md
-```
-
-### Documentation Structure
-Each component has a detailed README.md file with:
-- Complete API reference with props table
-- Usage examples and common patterns
-- Best practices and accessibility guidelines
-- Cross-platform considerations
-- Feature overview
-
-## Best Practices for LLMs
-
-1. **Start with CLAUDE.md** for quick component overview and patterns
-2. **Read individual README files** for detailed component documentation
-3. **Always use intent props** for semantic meaning
-4. **Prefer component variants** over manual styling
-5. **Use View spacing** for consistent layouts
-6. **Provide proper labels** for form components
-7. **Consider accessibility** in component usage
-8. **Test cross-platform** compatibility
-9. **Use TypeScript** for better development experience
+## Key Rules
+
+### ✅ DO:
+- Export `XVariants` type from style files
+- Use `CompoundVariants<keyof XVariants>` for compound variants (NOT with extra `[]`)
+- Get intents dynamically: `for (const intent in theme.intents)`
+- Use `as const` for literal values in variant definitions
+- Use `ComponentRef<typeof Component>` for ref types
+- Use static styles: `buttonStyles.button` (NOT `buttonStyles.button()`)
+- Pass all variants to `useVariants()` including intent
+
+### ❌ DON'T:
+- Add explicit return types to `StyleSheet.create()` - let Unistyles infer
+- Use dynamic style functions: `buttonStyles.button({ intent })` ❌
+- Hardcode intent arrays: `['primary', 'success', 'error']` ❌
+- Use deprecated ref types: `React.ElementRef` ❌
+- Add extra `[]` to CompoundVariants: `CompoundVariants<V>[]` ❌
+- Use `any` casts on refs: `ref as any` ❌
+
+## Common Issues to Check
+
+### 1. Invalid Imports in Style Files
+**CRITICAL**: Check style files for invalid/circular imports that break TypeScript:
+- ❌ Don't import from sibling component directories
+- ❌ Don't import component types into style files (creates circular deps)
+- ✅ Only import from: `@idealyst/theme`, `react-native-unistyles`, local utils
+- ✅ Safe: Import from `./types` IF types.ts only imports from external packages (no circular dep)
+  - Example: Input.styles.tsx imports from ./types.ts (which only imports from react-native, @idealyst/theme)
+
+### 2. Border Style Values
+- ❌ `borderStyle: 'none'` is INVALID (causes Unistyles errors)
+- ✅ Either omit `borderStyle` or set `borderWidth: 0`
+
+### 3. Compound Variants Type
+- ❌ `const compoundVariants: CompoundVariants<keyof XVariants>[] = [];`
+- ✅ `const compoundVariants: CompoundVariants<keyof XVariants> = [];`
+- (CompoundVariants is already an array type)
+
+## Progress Tracking
+
+### ✅ Completed
+- [x] Button.styles.tsx + Button.native.tsx + Button.web.tsx
+- [x] Chip.styles.tsx + Chip.native.tsx
+- [x] Card.styles.tsx + Card.native.tsx
+- [x] Alert.styles.tsx + Alert.native.tsx
+- [x] Input.styles.tsx
+- [x] Accordion.styles.tsx (already static)
+
+### 🔄 Needs Review/Update
+Check these files for:
+1. Invalid imports in .styles.tsx files
+2. Dynamic style function calls in .native.tsx/.web.tsx
+3. Deprecated ref types
+
+Priority files (have dynamic functions or need checking):
+- [ ] Badge.styles.tsx (uses `color` param - may need to stay dynamic)
+- [ ] Switch.styles.tsx (has dynamic functions with intent)
+- [ ] TextArea.styles.tsx
+- [ ] Checkbox.styles.tsx
+- [ ] RadioButton.styles.tsx
+- [ ] Select.styles.tsx
+- [ ] Progress.styles.tsx
+- [ ] Dialog.styles.tsx
+- [ ] Menu.styles.tsx / MenuItem.styles.tsx
+
+Already static (just verify):
+- [ ] Divider.styles.tsx
+- [ ] Text.styles.tsx
+- [ ] View.styles.tsx
+- [ ] Icon.styles.tsx
+
+### Special Cases
+- **Badge**: Uses `color` prop which isn't a fixed set - may need dynamic styles
+- **Switch**: Uses transform calculations - may need partial dynamic approach
+- **Icon**: Uses dynamic color from `color` or `intent` props
+
+## Testing Checklist
+
+Before marking a component as complete:
+1. [ ] No TypeScript errors in .styles.tsx file
+2. [ ] No invalid imports in .styles.tsx
+3. [ ] Component uses static styles (no function calls)
+4. [ ] Component passes all variants to `useVariants()`
+5. [ ] Ref types use `ComponentRef<typeof X>`
+6. [ ] All variant combinations work correctly
+7. [ ] No `ref as any` casts
+
+## Reference Files
+- **Main Reference**: `src/Button/Button.styles.tsx` and `src/Button/Button.native.tsx`
+- **Theme Types**: `@idealyst/theme/src/styles.ts`
+- **Compound Variants Example**: See Button's `createButtonCompoundVariants`

package/README.md

@@ -53,7 +53,7 @@ export default function App() {
   return (
     <Screen background="primary">
       <View spacing="lg" style={{ flex: 1, justifyContent: 'center' }}>
-        <Text size="large" weight="bold" align="center">
+        <Text size="lg" weight="bold" align="center">
           Welcome to Idealyst Components
         </Text>
         <Button
@@ -125,7 +125,7 @@ import { Screen, View, Text, Button } from '@idealyst/components';
 
 <Screen background="primary" safeArea>
   <View spacing="lg">
-    <Text size="xlarge" weight="bold">Welcome</Text>
+    <Text size="xl" weight="bold">Welcome</Text>
     <Text>Get started with your app</Text>
     <Button variant="contained" intent="primary" onPress={() => {}}>
       Get Started
@@ -139,7 +139,7 @@ import { Screen, View, Text, Button } from '@idealyst/components';
 import { View, Text, Input, Checkbox, Button } from '@idealyst/components';
 
 <View spacing="md">
-  <Text size="large" weight="bold">Sign Up</Text>
+  <Text size="lg" weight="bold">Sign Up</Text>
   <Input label="Email" value={email} onChangeText={setEmail} />
   <Input label="Password" value={password} onChangeText={setPassword} secureTextEntry />
   <Checkbox checked={agreed} onCheckedChange={setAgreed} label="I agree to terms" />
@@ -155,7 +155,7 @@ import { SVGImage, View, Text } from '@idealyst/components';
 import LogoIcon from './assets/logo.svg';
 
 <View spacing="md">
-  <Text size="large" weight="bold">My App</Text>
+  <Text size="lg" weight="bold">My App</Text>
   
   {/* Imported SVG */}
   <SVGImage source={LogoIcon} size={40} intent="primary" />
@@ -180,7 +180,7 @@ import { View, Card, Text, Avatar, Badge } from '@idealyst/components';
         <Avatar src={item.avatar} fallback={item.initials} />
         <View spacing="xs" style={{ flex: 1 }}>
           <Text weight="bold">{item.title}</Text>
-          <Text size="small" color="secondary">{item.subtitle}</Text>
+          <Text size="sm" color="secondary">{item.subtitle}</Text>
         </View>
         {item.badge && <Badge color="red">{item.badge}</Badge>}
       </View>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/components",
-  "version": "1.0.83",
+  "version": "1.0.84",
   "description": "Shared component library for React and React Native",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/components#readme",
   "readme": "README.md",
@@ -41,7 +41,7 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/theme": "^1.0.83",
+    "@idealyst/theme": "^1.0.84",
     "@mdi/js": ">=7.0.0",
     "@mdi/react": ">=1.0.0",
     "@react-native-vector-icons/common": ">=12.0.0",
@@ -51,6 +51,8 @@
     "react-native": ">=0.60.0",
     "react-native-edge-to-edge": "*",
     "react-native-nitro-modules": "*",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-safe-area-context": ">=5.0.0",
     "react-native-unistyles": ">=3.0.0"
   },
   "peerDependenciesMeta": {
@@ -75,6 +77,12 @@
     "react-native-nitro-modules": {
       "optional": true
     },
+    "react-native-reanimated": {
+      "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
+    },
     "react-native-unistyles": {
       "optional": true
     },
@@ -83,7 +91,17 @@
     }
   },
   "devDependencies": {
+    "@idealyst/theme": "^1.0.84",
+    "@mdi/react": "^1.6.1",
     "@types/react": "^19.1.0",
+    "react": "^19.1.0",
+    "react-native": "^0.80.1",
+    "react-native-gesture-handler": "^2.29.0",
+    "react-native-reanimated": "^4.1.3",
+    "react-native-safe-area-context": "^5.6.1",
+    "react-native-svg": "^15.14.0",
+    "react-native-unistyles": "^3.0.10",
+    "react-native-vector-icons": "^10.3.0",
     "typescript": "^5.0.0"
   },
   "files": [