@idealyst/components 1.0.39 → 1.0.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/CLAUDE.md +173 -0
  2. package/LLM-ACCESS-GUIDE.md +143 -0
  3. package/README.md +66 -145
  4. package/package.json +7 -3
  5. package/src/Avatar/README.md +139 -0
  6. package/src/Badge/README.md +170 -0
  7. package/src/Button/README.md +262 -0
  8. package/src/Card/README.md +258 -0
  9. package/src/Checkbox/README.md +102 -0
  10. package/src/Divider/README.md +108 -0
  11. package/src/Icon/README.md +81 -0
  12. package/src/Input/README.md +100 -0
  13. package/src/Screen/README.md +86 -0
  14. package/src/Text/README.md +94 -0
  15. package/src/View/README.md +107 -0
  16. package/src/index.ts +1 -1
package/CLAUDE.md ADDED
@@ -0,0 +1,173 @@
1
+ # @idealyst/components - LLM Documentation
2
+
3
+ This file provides comprehensive component documentation for LLMs working with the @idealyst/components library.
4
+
5
+ ## Library Overview
6
+
7
+ @idealyst/components is a cross-platform React/React Native component library with:
8
+ - 11 core components organized into 5 categories
9
+ - Theme-based styling with Unistyles
10
+ - Intent-based color system (primary, neutral, success, error, warning)
11
+ - Cross-platform compatibility (React & React Native)
12
+ - TypeScript support
13
+
14
+ ## Component Categories
15
+
16
+ ### Layout Components
17
+ - **View**: Container with spacing system (`spacing="xs|sm|md|lg|xl|xxl"`)
18
+ - **Screen**: Full-screen container (`background="primary|secondary|tertiary|inverse"`, `safeArea`, `padding`)
19
+ - **Divider**: Content separator (`orientation="horizontal|vertical"`, `spacing`, `intent`)
20
+
21
+ ### Typography
22
+ - **Text**: Styled text (`size="small|medium|large|xlarge"`, `weight="light|normal|medium|semibold|bold"`, `color`, `intent`, `align`)
23
+
24
+ ### Form Components
25
+ - **Button**: Interactive button (`variant="contained|outlined|text"`, `intent="primary|neutral|success|error|warning"`, `size="small|medium|large"`)
26
+ - **Input**: Text input (`label`, `placeholder`, `error`, `helperText`, `multiline`, `secureTextEntry`)
27
+ - **Checkbox**: Form checkbox (`checked`, `onCheckedChange`, `label`, `disabled`, `intent`)
28
+
29
+ ### Display Components
30
+ - **Card**: Content container (`variant="default|outlined|elevated|filled"`, `padding`, `radius`, `clickable`, `intent`)
31
+ - **Badge**: Status indicator (`variant="filled|outlined|dot"`, `color`, `size="small|medium|large"`)
32
+ - **Avatar**: Profile picture (`src`, `fallback`, `size="small|medium|large|xlarge"`, `shape="circle|square"`)
33
+
34
+ ### Utility Components
35
+ - **Icon**: Icon display (`name`, `size`, `color`, `intent`)
36
+
37
+ ## Intent System
38
+
39
+ All components use a consistent intent-based color system:
40
+ - `primary`: Main brand actions
41
+ - `neutral`: Secondary actions
42
+ - `success`: Positive actions (save, confirm)
43
+ - `error`: Destructive actions (delete, cancel)
44
+ - `warning`: Caution actions
45
+
46
+ ## Common Patterns
47
+
48
+ ### Basic Layout
49
+ ```tsx
50
+ <Screen background="primary" safeArea>
51
+ <View spacing="lg">
52
+ <Text size="xlarge" weight="bold">Title</Text>
53
+ <Text>Content</Text>
54
+ </View>
55
+ </Screen>
56
+ ```
57
+
58
+ ### Form Layout
59
+ ```tsx
60
+ <View spacing="md">
61
+ <Input label="Email" value={email} onChangeText={setEmail} />
62
+ <Button variant="contained" intent="primary" onPress={submit}>Submit</Button>
63
+ </View>
64
+ ```
65
+
66
+ ### Card with Content
67
+ ```tsx
68
+ <Card variant="outlined" clickable onPress={handlePress}>
69
+ <View spacing="sm">
70
+ <Text weight="bold">Title</Text>
71
+ <Text size="small" color="secondary">Subtitle</Text>
72
+ </View>
73
+ </Card>
74
+ ```
75
+
76
+ ## Styling Guidelines
77
+
78
+ 1. **Use variants over manual styles** - Components provide semantic variants
79
+ 2. **Manual styles override variants** - Style prop takes precedence
80
+ 3. **Consistent spacing** - Use View spacing prop for consistent gaps
81
+ 4. **Intent-based colors** - Use intent props for semantic meaning
82
+ 5. **Cross-platform compatibility** - All components work on React and React Native
83
+
84
+ ## Import Patterns
85
+
86
+ ```tsx
87
+ // Individual imports (recommended)
88
+ import { Button, Text, View } from '@idealyst/components';
89
+
90
+ // Documentation access
91
+ import { componentDocs, getComponentDocs } from '@idealyst/components/docs';
92
+
93
+ // Examples
94
+ import { ButtonExamples } from '@idealyst/components/examples';
95
+ ```
96
+
97
+ ## Key Props Reference
98
+
99
+ ### Universal Props (most components)
100
+ - `style`: Additional custom styles
101
+ - `testID`: Test identifier
102
+ - `disabled`: Disable interaction
103
+
104
+ ### Layout Props
105
+ - `spacing`: Gap between children (`View`)
106
+ - `padding`: Internal padding (`Screen`, `Card`)
107
+ - `background`: Background color variant (`Screen`)
108
+
109
+ ### Styling Props
110
+ - `variant`: Visual style variant
111
+ - `intent`: Color scheme/semantic meaning
112
+ - `size`: Component size
113
+ - `color`: Color override
114
+
115
+ ### Interactive Props
116
+ - `onPress`: Press handler (`Button`, `Card`, `Checkbox`)
117
+ - `clickable`: Enable interaction (`Card`)
118
+ - `checked`: Checkbox state
119
+ - `value`/`onChangeText`: Input state
120
+
121
+ ## Accessibility Features
122
+
123
+ - Proper ARIA roles and labels
124
+ - Keyboard navigation support
125
+ - Screen reader compatibility
126
+ - Focus management
127
+ - Touch target sizing (minimum 44px)
128
+
129
+ ## Documentation Access for LLMs
130
+
131
+ ### File-Based Documentation Access
132
+ All documentation is available as markdown files in the package:
133
+
134
+ ```bash
135
+ # Quick overview - START HERE
136
+ CLAUDE.md
137
+
138
+ # Complete library overview with component table
139
+ README.md
140
+
141
+ # Detailed documentation for each component
142
+ src/Avatar/README.md
143
+ src/Badge/README.md
144
+ src/Button/README.md
145
+ src/Card/README.md
146
+ src/Checkbox/README.md
147
+ src/Divider/README.md
148
+ src/Icon/README.md
149
+ src/Input/README.md
150
+ src/Screen/README.md
151
+ src/Text/README.md
152
+ src/View/README.md
153
+ ```
154
+
155
+ ### Documentation Structure
156
+ Each component has a detailed README.md file with:
157
+ - Complete API reference with props table
158
+ - Usage examples and common patterns
159
+ - Best practices and accessibility guidelines
160
+ - Cross-platform considerations
161
+ - Feature overview
162
+
163
+ ## Best Practices for LLMs
164
+
165
+ 1. **Start with CLAUDE.md** for quick component overview and patterns
166
+ 2. **Read individual README files** for detailed component documentation
167
+ 3. **Always use intent props** for semantic meaning
168
+ 4. **Prefer component variants** over manual styling
169
+ 5. **Use View spacing** for consistent layouts
170
+ 6. **Provide proper labels** for form components
171
+ 7. **Consider accessibility** in component usage
172
+ 8. **Test cross-platform** compatibility
173
+ 9. **Use TypeScript** for better development experience
package/LLM-ACCESS-GUIDE.md ADDED
@@ -0,0 +1,143 @@
1
+ # LLM Documentation Access Guide
2
+
3
+ This guide explains exactly how LLMs can access @idealyst/components documentation in real-world scenarios.
4
+
5
+ ## Scenario 1: Working in a Project with the Package Installed
6
+
7
+ When helping a developer who has `@idealyst/components` installed in their project:
8
+
9
+ ### Quick Overview
10
+ ```bash
11
+ # Read the main documentation file
12
+ cat node_modules/@idealyst/components/CLAUDE.md
13
+ ```
14
+ This gives you everything in one file - all components, patterns, and usage examples.
15
+
16
+ ### Specific Component Details
17
+ ```bash
18
+ # For detailed Button documentation
19
+ cat node_modules/@idealyst/components/src/Button/README.md
20
+
21
+ # For detailed Card documentation
22
+ cat node_modules/@idealyst/components/src/Card/README.md
23
+
24
+ # And so on for each component...
25
+ ```
26
+
27
+ ### Component Discovery
28
+ ```bash
29
+ # See all available components
30
+ ls node_modules/@idealyst/components/src/*/README.md
31
+
32
+ # Will show:
33
+ # node_modules/@idealyst/components/src/Avatar/README.md
34
+ # node_modules/@idealyst/components/src/Badge/README.md
35
+ # node_modules/@idealyst/components/src/Button/README.md
36
+ # ... etc
37
+ ```
38
+
39
+ ## Scenario 2: Repository/GitHub Access
40
+
41
+ When working with the source repository or GitHub:
42
+
43
+ ### Main Documentation
44
+ - `packages/components/README.md` - Complete overview with component table
45
+ - `packages/components/CLAUDE.md` - LLM-optimized quick reference
46
+
47
+ ### Individual Component Docs
48
+ - `packages/components/src/Avatar/README.md`
49
+ - `packages/components/src/Button/README.md`
50
+ - `packages/components/src/Card/README.md`
51
+ - ... etc for all 11 components
52
+
53
+ ## Scenario 3: Package Manager Info
54
+
55
+ ```bash
56
+ # View package information
57
+ npm info @idealyst/components
58
+
59
+ # View package README
60
+ npm docs @idealyst/components
61
+
62
+ # Download and examine (if needed)
63
+ npm pack @idealyst/components
64
+ tar -tf idealyst-components-*.tgz | grep README
65
+ ```
66
+
67
+ ## Scenario 4: Examples and Live Code
68
+
69
+ For working examples and demonstrations:
70
+
71
+ ```bash
72
+ # Import component examples
73
+ import { ButtonExamples, CardExamples } from '@idealyst/components/examples';
74
+
75
+ # Or read example source code
76
+ cat node_modules/@idealyst/components/src/examples/ButtonExamples.tsx
77
+ cat node_modules/@idealyst/components/src/examples/CardExamples.tsx
78
+ ```
79
+
80
+ ## Recommended LLM Workflow
81
+
82
+ ### Step 1: Quick Reference
83
+ Start with `CLAUDE.md` for:
84
+ - All component names and categories
85
+ - Common usage patterns
86
+ - Intent system explanation
87
+ - Quick examples
88
+
89
+ ### Step 2: Specific Component Help
90
+ When user asks about a specific component:
91
+ 1. Read `src/ComponentName/README.md` for complete details
92
+ 2. Use the detailed props table, examples, and best practices
93
+
94
+ ### Step 3: Component Discovery
95
+ When user asks "what components are available for X":
96
+ 1. Check the component table in main README.md
97
+ 2. Use component categories (layout, form, display, etc.)
98
+ 3. Read individual component descriptions
99
+
100
+ ## File Locations Summary
101
+
102
+ ```
103
+ @idealyst/components/
104
+ ├── README.md # Complete overview + component table
105
+ ├── CLAUDE.md # LLM quick reference (START HERE)
106
+ ├── src/
107
+ │ ├── Avatar/README.md # Detailed Avatar docs
108
+ │ ├── Badge/README.md # Detailed Badge docs
109
+ │ ├── Button/README.md # Detailed Button docs
110
+ │ ├── Card/README.md # Detailed Card docs
111
+ │ ├── Checkbox/README.md # Detailed Checkbox docs
112
+ │ ├── Divider/README.md # Detailed Divider docs
113
+ │ ├── Icon/README.md # Detailed Icon docs
114
+ │ ├── Input/README.md # Detailed Input docs
115
+ │ ├── Screen/README.md # Detailed Screen docs
116
+ │ ├── Text/README.md # Detailed Text docs
117
+ │ └── View/README.md # Detailed View docs
118
+ ```
119
+
120
+ ## Pro Tips for LLMs
121
+
122
+ 1. **Always start with `CLAUDE.md`** - it has everything you need for 90% of questions
123
+ 2. **Component table in main README** - perfect for "what components are available" questions
124
+ 3. **Individual README files** - use when user needs specific component details
125
+ 4. **Check the examples/** folder - contains working code examples for all components
126
+ 5. **Intent system is key** - primary, neutral, success, error, warning are used across all components
127
+
128
+ ## Quick Command Reference
129
+
130
+ ```bash
131
+ # Essential reads for any LLM session
132
+ cat CLAUDE.md # Complete LLM reference
133
+ cat README.md # Overview + component table
134
+
135
+ # Specific component help
136
+ cat src/Button/README.md # Button documentation
137
+ cat src/Card/README.md # Card documentation
138
+
139
+ # Discovery
140
+ ls src/*/README.md # List all component docs
141
+ ```
142
+
143
+ This approach ensures LLMs have clear, practical access to all documentation without cluttering the main component API.
package/README.md CHANGED
@@ -65,175 +65,96 @@ export default function App() {
65
65
 
66
66
  ## Available Components
67
67
 
68
- ### Layout Components
69
-
70
- #### View
71
- A flexible container component with built-in spacing and styling options.
72
-
73
- ```tsx
74
- import { View } from '@idealyst/components';
75
-
76
- <View spacing="md" style={{ padding: 16 }}>
77
- {/* Content */}
78
- </View>
79
- ```
80
-
81
- **Props:**
82
- - `spacing`: `"xs" | "sm" | "md" | "lg" | "xl" | "xxl"`
83
- - Standard View props (style, children, etc.)
84
-
85
- #### Screen
86
- A full-screen container component that grows to fit the parent completely with theme-based backgrounds and padding.
87
-
88
- ```tsx
89
- import { Screen } from '@idealyst/components';
90
-
91
- <Screen background="primary" padding="lg" safeArea={true}>
92
- {/* Your app content */}
93
- </Screen>
94
- ```
68
+ The library includes 10 core components organized by category. Each component has detailed documentation in its respective folder.
95
69
 
96
- **Props:**
97
- - `background`: `"primary" | "secondary" | "tertiary" | "inverse"` - Background color variant
98
- - `padding`: `"none" | "sm" | "md" | "lg" | "xl"` - Screen padding (default: "md")
99
- - `safeArea`: `boolean` - Enable safe area padding for mobile devices (default: false)
100
- - `style`: Additional styles
101
- - `testID`: Test identifier
102
-
103
- #### Divider
104
- A separator component with customizable styling and spacing.
105
-
106
- ```tsx
107
- import { Divider } from '@idealyst/components';
108
-
109
- <Divider spacing="medium" intent="primary">
110
- <Text>Section Title</Text>
111
- </Divider>
112
- ```
70
+ ### Layout Components
113
71
 
114
- **Props:**
115
- - `spacing`: `"small" | "medium" | "large"`
116
- - `intent`: `"primary" | "secondary" | "neutral"`
117
- - `children`: Optional content to display in the divider
72
+ | Component | Description | Documentation |
73
+ |-----------|-------------|---------------|
74
+ | **[View](src/View/README.md)** | Flexible container with built-in spacing system | [View Docs](src/View/README.md) |
75
+ | **[Screen](src/Screen/README.md)** | Full-screen container with safe area support | [Screen Docs](src/Screen/README.md) |
76
+ | **[Divider](src/Divider/README.md)** | Separator for content sections | [Divider Docs](src/Divider/README.md) |
118
77
 
119
78
  ### Typography
120
79
 
121
- #### Text
122
- A versatile text component with comprehensive styling options.
123
-
124
- ```tsx
125
- import { Text } from '@idealyst/components';
126
-
127
- <Text
128
- size="large"
129
- weight="bold"
130
- color="primary"
131
- align="center"
132
- >
133
- Hello World
134
- </Text>
135
- ```
136
-
137
- **Props:**
138
- - `size`: `"small" | "medium" | "large" | "xlarge"`
139
- - `weight`: `"light" | "normal" | "medium" | "semibold" | "bold"`
140
- - `color`: `"primary" | "secondary" | "success" | "warning" | "error"`
141
- - `align`: `"left" | "center" | "right"`
80
+ | Component | Description | Documentation |
81
+ |-----------|-------------|---------------|
82
+ | **[Text](src/Text/README.md)** | Versatile text with extensive styling options | [Text Docs](src/Text/README.md) |
142
83
 
143
84
  ### Form Components
144
85
 
145
- #### Button
146
- A customizable button component with multiple variants and intents.
147
-
148
- ```tsx
149
- import { Button } from '@idealyst/components';
150
-
151
- <Button
152
- variant="contained"
153
- intent="primary"
154
- size="medium"
155
- onPress={() => console.log('Pressed!')}
156
- >
157
- Click Me
158
- </Button>
159
- ```
160
-
161
- **Props:**
162
- - `variant`: `"contained" | "outlined" | "text"`
163
- - `intent`: `"primary" | "neutral" | "success" | "error" | "warning"`
164
- - `size`: `"small" | "medium" | "large"`
165
- - `disabled`: `boolean`
166
- - `onPress`: `() => void`
86
+ | Component | Description | Documentation |
87
+ |-----------|-------------|---------------|
88
+ | **[Button](src/Button/README.md)** | Customizable button with variants and intents | [Button Docs](src/Button/README.md) |
89
+ | **[Input](src/Input/README.md)** | Text input with validation and styling | [Input Docs](src/Input/README.md) |
90
+ | **[Checkbox](src/Checkbox/README.md)** | Checkbox with label support | [Checkbox Docs](src/Checkbox/README.md) |
167
91
 
168
- #### Input
169
- A text input component with consistent styling.
170
-
171
- ```tsx
172
- import { Input } from '@idealyst/components';
173
-
174
- <Input
175
- placeholder="Enter your name"
176
- value={value}
177
- onChangeText={setValue}
178
- />
179
- ```
180
-
181
- #### Checkbox
182
- A checkbox component with customizable styling.
92
+ ### Display Components
183
93
 
184
- ```tsx
185
- import { Checkbox } from '@idealyst/components';
94
+ | Component | Description | Documentation |
95
+ |-----------|-------------|---------------|
96
+ | **[Card](src/Card/README.md)** | Container for grouped content | [Card Docs](src/Card/README.md) |
97
+ | **[Badge](src/Badge/README.md)** | Status indicators and count displays | [Badge Docs](src/Badge/README.md) |
98
+ | **[Avatar](src/Avatar/README.md)** | User profile pictures with fallback | [Avatar Docs](src/Avatar/README.md) |
186
99
 
187
- <Checkbox
188
- checked={isChecked}
189
- onPress={() => setIsChecked(!isChecked)}
190
- label="Agree to terms"
191
- />
192
- ```
100
+ ### Utility Components
193
101
 
194
- ### Display Components
102
+ | Component | Description | Documentation |
103
+ |-----------|-------------|---------------|
104
+ | **[Icon](src/Icon/README.md)** | Icon library with extensive options | [Icon Docs](src/Icon/README.md) |
195
105
 
196
- #### Card
197
- A container component for displaying content in a card format.
106
+ ## Quick Usage Examples
198
107
 
108
+ ### Basic Layout
199
109
  ```tsx
200
- import { Card } from '@idealyst/components';
110
+ import { Screen, View, Text, Button } from '@idealyst/components';
201
111
 
202
- <Card>
203
- <Text size="large" weight="bold">Card Title</Text>
204
- <Text>Card content goes here</Text>
205
- </Card>
112
+ <Screen background="primary" safeArea>
113
+ <View spacing="lg">
114
+ <Text size="xlarge" weight="bold">Welcome</Text>
115
+ <Text>Get started with your app</Text>
116
+ <Button variant="contained" intent="primary" onPress={() => {}}>
117
+ Get Started
118
+ </Button>
119
+ </View>
120
+ </Screen>
206
121
  ```
207
122
 
208
- #### Badge
209
- A small component for displaying status or count information.
210
-
123
+ ### Form Example
211
124
  ```tsx
212
- import { Badge } from '@idealyst/components';
213
-
214
- <Badge count={5} intent="error">
215
- <Text>Notifications</Text>
216
- </Badge>
125
+ import { View, Text, Input, Checkbox, Button } from '@idealyst/components';
126
+
127
+ <View spacing="md">
128
+ <Text size="large" weight="bold">Sign Up</Text>
129
+ <Input label="Email" value={email} onChangeText={setEmail} />
130
+ <Input label="Password" value={password} onChangeText={setPassword} secureTextEntry />
131
+ <Checkbox checked={agreed} onCheckedChange={setAgreed} label="I agree to terms" />
132
+ <Button variant="contained" intent="primary" onPress={handleSubmit}>
133
+ Create Account
134
+ </Button>
135
+ </View>
217
136
  ```
218
137
 
219
- #### Avatar
220
- A component for displaying user avatars or profile pictures.
221
-
138
+ ### Card Grid
222
139
  ```tsx
223
- import { Avatar } from '@idealyst/components';
224
-
225
- <Avatar
226
- source={{ uri: 'https://example.com/avatar.jpg' }}
227
- size="medium"
228
- fallback="JD"
229
- />
140
+ import { View, Card, Text, Avatar, Badge } from '@idealyst/components';
141
+
142
+ <View spacing="md">
143
+ {items.map(item => (
144
+ <Card key={item.id} clickable onPress={() => navigate(item)}>
145
+ <View spacing="sm" style={{ flexDirection: 'row', alignItems: 'center' }}>
146
+ <Avatar src={item.avatar} fallback={item.initials} />
147
+ <View spacing="xs" style={{ flex: 1 }}>
148
+ <Text weight="bold">{item.title}</Text>
149
+ <Text size="small" color="secondary">{item.subtitle}</Text>
150
+ </View>
151
+ {item.badge && <Badge color="red">{item.badge}</Badge>}
152
+ </View>
153
+ </Card>
154
+ ))}
155
+ </View>
230
156
  ```
231
157
 
232
- **Props:**
233
- - `source`: Image source object
234
- - `size`: `"small" | "medium" | "large"`
235
- - `fallback`: Text to display when image fails to load
236
-
237
158
  ## Theme System
238
159
 
239
160
  The library includes a comprehensive theme system with light and dark mode support.
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@idealyst/components",
3
- "version": "1.0.39",
3
+ "version": "1.0.40",
4
4
  "description": "Shared component library for React and React Native",
5
+ "documentation": "https://github.com/your-username/idealyst-framework/tree/main/packages/components#readme",
5
6
  "main": "src/index.ts",
6
7
  "module": "src/index.ts",
7
8
  "types": "src/index.ts",
@@ -39,7 +40,7 @@
39
40
  "publish:npm": "npm publish"
40
41
  },
41
42
  "peerDependencies": {
42
- "@idealyst/theme": "^1.0.39",
43
+ "@idealyst/theme": "^1.0.40",
43
44
  "@mdi/js": "^7.4.47",
44
45
  "@mdi/react": "^1.6.1",
45
46
  "@react-native-vector-icons/common": "^12.0.1",
@@ -86,7 +87,10 @@
86
87
  },
87
88
  "files": [
88
89
  "src",
89
- "plugin"
90
+ "plugin",
91
+ "CLAUDE.md",
92
+ "README.md",
93
+ "LLM-ACCESS-GUIDE.md"
90
94
  ],
91
95
  "keywords": [
92
96
  "react",